perf(models): fetch the model list conditionally with ETag

internal/cache/modelcache/modelcache.go

@@ -19,6 +19,12 @@ type ModelCache struct {
 	// ModelListData holds the raw JSON model registry bytes for cache persistence,
 	// allowing the registry to restore its full model list without re-fetching.
 	ModelListData json.RawMessage `json:"model_list_data,omitempty"`
+	// ModelListETag is the HTTP validator ModelListData was downloaded with,
+	// letting the next fetch skip the download when the list is unchanged.
+	// ModelListURL records which URL issued it, so the validator is never
+	// presented to a reconfigured model list URL.
+	ModelListETag string `json:"model_list_etag,omitempty"`
+	ModelListURL  string `json:"model_list_url,omitempty"`
 }
 
 // CachedProvider holds shared fields for all models from a single provider.

internal/modeldata/fetcher.go

@@ -17,49 +17,84 @@ var httpClient = &http.Client{
 	Timeout: 60 * time.Second,
 }
 
+// FetchResult carries the outcome of one conditional model list fetch.
+type FetchResult struct {
+	List *ModelList
+	Raw  []byte
+	// ETag is the validator to send on the next conditional fetch. Empty when
+	// the server did not return one.
+	ETag string
+	// NotModified is true when the server answered 304 for the presented ETag;
+	// List and Raw are nil and the caller keeps its current data.
+	NotModified bool
+}
+
 // Fetch downloads and parses the model list from the given URL.
 // Returns the parsed ModelList, the raw JSON bytes (for caching), and any error.
 // Returns nil, nil, nil if the URL is empty (feature disabled).
 // The caller controls timeout via the provided context (e.g. context.WithTimeout).
 func Fetch(ctx context.Context, url string) (*ModelList, []byte, error) {
+	result, err := FetchIfChanged(ctx, url, "")
+	return result.List, result.Raw, err
+}
+
+// FetchIfChanged downloads and parses the model list unless the server reports
+// it unchanged. When etag is non-empty it is sent as If-None-Match; a 304
+// response returns NotModified=true with the etag carried forward, skipping
+// the download and reparse entirely. Servers without ETag support keep
+// answering 200, so callers transparently degrade to unconditional fetching.
+// Returns a zero FetchResult and nil error if the URL is empty (feature disabled).
+func FetchIfChanged(ctx context.Context, url, etag string) (FetchResult, error) {
 	if url == "" {
-		return nil, nil, nil
+		return FetchResult{}, nil
 	}
 
 	client := httpClient
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
 	if err != nil {
-		return nil, nil, fmt.Errorf("creating request: %w", err)
+		return FetchResult{}, fmt.Errorf("creating request: %w", err)
 	}
 	req.Header.Set("Accept", "application/json")
+	if etag != "" {
+		req.Header.Set("If-None-Match", etag)
+	}
 
 	resp, err := client.Do(req)
 	if err != nil {
-		return nil, nil, fmt.Errorf("fetching model list: %w", err)
+		return FetchResult{}, fmt.Errorf("fetching model list: %w", err)
 	}
 	defer resp.Body.Close()
 
+	if etag != "" && resp.StatusCode == http.StatusNotModified {
+		// RFC 9111: a 304 may carry updated metadata for the stored
+		// representation; adopt its ETag when present so future conditional
+		// requests use the server's current validator.
+		if respETag := resp.Header.Get("ETag"); respETag != "" {
+			etag = respETag
+		}
+		return FetchResult{ETag: etag, NotModified: true}, nil
+	}
 	if resp.StatusCode != http.StatusOK {
-		return nil, nil, fmt.Errorf("unexpected status %d from %s", resp.StatusCode, url)
+		return FetchResult{}, fmt.Errorf("unexpected status %d from %s", resp.StatusCode, url)
 	}
 
 	const maxBodySize = 10 * 1024 * 1024 // 10 MB
 	limited := io.LimitReader(resp.Body, maxBodySize+1)
 	raw, err := io.ReadAll(limited)
 	if err != nil {
-		return nil, nil, fmt.Errorf("reading response body: %w", err)
+		return FetchResult{}, fmt.Errorf("reading response body: %w", err)
 	}
 	if len(raw) > maxBodySize {
-		return nil, nil, fmt.Errorf("response body too large (exceeds %d bytes)", maxBodySize)
+		return FetchResult{}, fmt.Errorf("response body too large (exceeds %d bytes)", maxBodySize)
 	}
 
 	list, err := Parse(raw)
 	if err != nil {
-		return nil, nil, err
+		return FetchResult{}, err
 	}
 
-	return list, raw, nil
+	return FetchResult{List: list, Raw: raw, ETag: resp.Header.Get("ETag")}, nil
 }
 
 // Parse deserializes raw JSON bytes into a ModelList.

internal/modeldata/fetcher_test.go

@@ -114,6 +114,117 @@ func TestFetch_OversizedBody(t *testing.T) {
 	}
 }
 
+func TestFetchIfChanged_CapturesETag(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("If-None-Match"); got != "" {
+			t.Errorf("unexpected If-None-Match header %q on unconditional fetch", got)
+		}
+		w.Header().Set("ETag", `"abc123"`)
+		_, _ = w.Write([]byte(`{"version": 1, "providers": {}, "models": {}, "provider_models": {}}`))
+	}))
+	defer server.Close()
+
+	result, err := FetchIfChanged(context.Background(), server.URL, "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.NotModified {
+		t.Error("expected NotModified=false for 200 response")
+	}
+	if result.List == nil || result.Raw == nil {
+		t.Fatal("expected list and raw bytes")
+	}
+	if result.ETag != `"abc123"` {
+		t.Errorf("ETag = %q, want %q", result.ETag, `"abc123"`)
+	}
+}
+
+func TestFetchIfChanged_NotModified(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("If-None-Match"); got != `"abc123"` {
+			t.Errorf("If-None-Match = %q, want %q", got, `"abc123"`)
+		}
+		w.WriteHeader(http.StatusNotModified)
+	}))
+	defer server.Close()
+
+	result, err := FetchIfChanged(context.Background(), server.URL, `"abc123"`)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !result.NotModified {
+		t.Fatal("expected NotModified=true for 304 response")
+	}
+	if result.List != nil || result.Raw != nil {
+		t.Error("expected nil list and raw on 304")
+	}
+	if result.ETag != `"abc123"` {
+		t.Errorf("ETag = %q, want the presented validator carried forward", result.ETag)
+	}
+}
+
+func TestFetchIfChanged_NotModifiedAdoptsResponseETag(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("ETag", `"refreshed"`)
+		w.WriteHeader(http.StatusNotModified)
+	}))
+	defer server.Close()
+
+	result, err := FetchIfChanged(context.Background(), server.URL, `"stale"`)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !result.NotModified {
+		t.Fatal("expected NotModified=true for 304 response")
+	}
+	if result.ETag != `"refreshed"` {
+		t.Errorf("ETag = %q, want the 304's refreshed validator", result.ETag)
+	}
+}
+
+func TestFetchIfChanged_ChangedContent(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("ETag", `"v2"`)
+		_, _ = w.Write([]byte(`{"version": 2, "providers": {}, "models": {}, "provider_models": {}}`))
+	}))
+	defer server.Close()
+
+	result, err := FetchIfChanged(context.Background(), server.URL, `"v1"`)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.NotModified {
+		t.Error("expected NotModified=false when content changed")
+	}
+	if result.List == nil || result.List.Version != 2 {
+		t.Fatal("expected updated list")
+	}
+	if result.ETag != `"v2"` {
+		t.Errorf("ETag = %q, want %q", result.ETag, `"v2"`)
+	}
+}
+
+func TestFetchIfChanged_ServerWithoutETagSupport(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{"version": 1, "providers": {}, "models": {}, "provider_models": {}}`))
+	}))
+	defer server.Close()
+
+	result, err := FetchIfChanged(context.Background(), server.URL, `"stale"`)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.NotModified {
+		t.Error("expected NotModified=false when server ignores validators")
+	}
+	if result.List == nil {
+		t.Fatal("expected list from 200 response")
+	}
+	if result.ETag != "" {
+		t.Errorf("ETag = %q, want empty when server returns none", result.ETag)
+	}
+}
+
 func TestParse_ValidJSON(t *testing.T) {
 	raw := []byte(`{
 		"version": 1,

internal/providers/init.go

@@ -65,8 +65,8 @@ func (r *InitResult) Close() error {
 //  2. Cache initialization (local or Redis based on config)
 //  3. Provider instantiation and registration
 //  4. Async model loading (from cache first, then network refresh)
-//  5. Best-effort background model-list fetch (goroutine with ~45s timeout that
-//     calls modeldata.Fetch, registry.EnrichModels, and SaveToCache)
+//  5. Best-effort background model-list fetch (goroutine with ~45s timeout;
+//     conditional via ETag, then enrich and SaveToCache when content changed)
 //  6. Background refresh scheduling (interval from cfg.Cache.RefreshInterval)
 //  7. Router creation
 //
@@ -133,25 +133,29 @@ func Init(ctx context.Context, result *config.LoadResult, factory *ProviderFacto
 			fetchCtx, cancel := context.WithTimeout(ctx, 45*time.Second)
 			defer cancel()
 
-			list, raw, err := modeldata.Fetch(fetchCtx, modelListURL)
+			result, err := modeldata.FetchIfChanged(fetchCtx, modelListURL, registry.currentModelListETag(modelListURL))
 			if err != nil {
 				slog.Warn("failed to fetch model list", "url", modelListURL, "error", err)
 				return
 			}
-			if list == nil {
+			if result.NotModified {
+				registry.updateModelListValidator(result.ETag, modelListURL)
+				slog.Info("model list unchanged since last download, using cached copy")
+				return
+			}
+			if result.List == nil {
 				return
 			}
 
-			registry.SetModelList(list, raw)
-			metadataStats := registry.enrichModels()
+			metadataStats := registry.setModelListAndEnrich(result.List, result.Raw, result.ETag, modelListURL)
 
 			if err := registry.SaveToCache(fetchCtx); err != nil {
 				slog.Warn("failed to save cache after model list fetch", "error", err)
 			}
 			attrs := []any{
-				"models", len(list.Models),
-				"providers", len(list.Providers),
-				"provider_models", len(list.ProviderModels),
+				"models", len(result.List.Models),
+				"providers", len(result.List.Providers),
+				"provider_models", len(result.List.ProviderModels),
 			}
 			attrs = append(attrs, metadataStats.slogAttrs()...)
 			slog.Info("model list loaded", attrs...)

internal/providers/registry.go

@@ -62,6 +62,12 @@ type ModelRegistry struct {
 	refreshOnce      sync.Once            // initializes refreshCh for zero-value safety
 	modelList        *modeldata.ModelList // parsed model list (nil = not loaded)
 	modelListRaw     json.RawMessage      // raw bytes for cache persistence
+	// modelListETag is the validator for conditional refetches and
+	// modelListETagURL the URL it was issued by; the validator is only sent
+	// back to that same URL, so a reconfigured MODEL_LIST_URL always fetches
+	// unconditionally. Empty etag = fetch unconditionally.
+	modelListETag    string
+	modelListETagURL string
 	// configMetadataOverrides holds operator-supplied metadata keyed by provider
 	// instance name -> raw model ID. Applied after remote-registry enrichment as
 	// a higher-priority layer. nil if no overrides declared.

internal/providers/registry_cache.go

@@ -134,6 +134,7 @@ func (r *ModelRegistry) LoadFromCache(ctx context.Context) (int, error) {
 	if list != nil {
 		r.modelList = list
 		r.modelListRaw = modelCache.ModelListData
+		r.setModelListValidatorLocked(modelCache.ModelListETag, modelCache.ModelListURL)
 	}
 	r.mu.Unlock()
 
@@ -166,6 +167,8 @@ func (r *ModelRegistry) SaveToCache(ctx context.Context) error {
 	providerTypes := make(map[core.Provider]string, len(r.providerTypes))
 	maps.Copy(providerTypes, r.providerTypes)
 	modelListRaw := r.modelListRaw
+	modelListETag := r.modelListETag
+	modelListETagURL := r.modelListETagURL
 	r.mu.RUnlock()
 
 	if cacheBackend == nil {
@@ -176,6 +179,8 @@ func (r *ModelRegistry) SaveToCache(ctx context.Context) error {
 		UpdatedAt:     time.Now().UTC(),
 		Providers:     make(map[string]modelcache.CachedProvider, len(modelsByProvider)),
 		ModelListData: modelListRaw,
+		ModelListETag: modelListETag,
+		ModelListURL:  modelListETagURL,
 	}
 
 	var totalModels int

internal/providers/registry_cache_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/enterpilot/gomodel/config"
 	"github.com/enterpilot/gomodel/internal/cache/modelcache"
 	"github.com/enterpilot/gomodel/internal/core"
+	"github.com/enterpilot/gomodel/internal/modeldata"
 )
 
 func TestCacheFile(t *testing.T) {
@@ -886,3 +887,43 @@ func TestSaveToCache_SkipsStaleProviderInventory(t *testing.T) {
 		t.Error("recovered provider beta missing from cache, want persisted again")
 	}
 }
+
+func TestCacheFile_ModelListETagRoundtrip(t *testing.T) {
+	tmpDir := t.TempDir()
+	cacheFile := filepath.Join(tmpDir, "models.json")
+
+	raw := []byte(`{"version": 1, "providers": {}, "models": {"m": {"display_name": "M", "modes": ["chat"]}}, "provider_models": {}}`)
+	list, err := modeldata.Parse(raw)
+	if err != nil {
+		t.Fatalf("Parse() error = %v", err)
+	}
+
+	saving := NewModelRegistry()
+	saving.SetCache(modelcache.NewLocalCache(cacheFile))
+	mock := &registryMockProvider{
+		name: "openai",
+		modelsResponse: &core.ModelsResponse{
+			Object: "list",
+			Data:   []core.Model{{ID: "gpt-4o", Object: "model", OwnedBy: "openai"}},
+		},
+	}
+	saving.RegisterProviderWithNameAndType(mock, "openai", "openai")
+	_ = saving.Initialize(context.Background())
+	saving.setModelListAndEnrich(list, raw, `"list-v7"`, "https://example.test/models.min.json")
+	if err := saving.SaveToCache(context.Background()); err != nil {
+		t.Fatalf("SaveToCache() error = %v", err)
+	}
+
+	loading := NewModelRegistry()
+	loading.SetCache(modelcache.NewLocalCache(cacheFile))
+	loading.RegisterProviderWithNameAndType(mock, "openai", "openai")
+	if _, err := loading.LoadFromCache(context.Background()); err != nil {
+		t.Fatalf("LoadFromCache() error = %v", err)
+	}
+	if got := loading.currentModelListETag("https://example.test/models.min.json"); got != `"list-v7"` {
+		t.Fatalf("currentModelListETag() after load = %q, want %q", got, `"list-v7"`)
+	}
+	if got := loading.currentModelListETag("https://other.test/models.min.json"); got != "" {
+		t.Fatalf("currentModelListETag() for another URL = %q, want empty", got)
+	}
+}