Function loadDatabase

pkg/modelsdev/store.go:261–315

loadDatabase loads the database from the local cache file or falls back to fetching from the models.dev API. When allowFetch is false the network is never touched: a fresh cache is returned as-is, a stale cache is returned regardless of age, and a missing cache falls back to the snapshot embedded a

(ctx context.Context, cacheFile string, allowFetch bool, fetch fetcher)

// this to avoid memoizing the fallback so a later lookup can retry once the
// cache or network recovers.
func loadDatabase(ctx context.Context, cacheFile string, allowFetch bool, fetch fetcher) (db *Database, authoritative bool) {
	// Try to load from cache first
	cached, err := loadFromCache(cacheFile)
	if err == nil && (!allowFetch || time.Since(cached.LastRefresh) < refreshInterval) {
		return &cached.Database, true
	}

	if !allowFetch {
		// No fresh cache and fetching is disallowed: use a stale cache if we
		// have one, otherwise fall back to the snapshot baked into the binary
		// so the caller still resolves against a real catalog with no network
		// call.
		if cached != nil {
			return &cached.Database, true
		}
		return embeddedSnapshot(), false
	}

	// Cache is stale or doesn't exist — try a conditional fetch with the ETag.
	var etag string
	if cached != nil {
		etag = cached.ETag
	}

	database, newETag, fetchErr := fetch(ctx, etag)
	if fetchErr != nil {
		// If API fetch fails but we have cached data, use it regardless of age.
		if cached != nil {
			slog.DebugContext(ctx, "API fetch failed, using stale cache", "error", fetchErr)
			return &cached.Database, true
		}
		// No cache either — fall back to the snapshot embedded at build time
		// instead of failing outright, so a fresh binary on a machine that
		// can't reach models.dev still has a usable catalog.
		slog.DebugContext(ctx, "API fetch failed and no cache available, using embedded snapshot", "error", fetchErr)
		return embeddedSnapshot(), false
	}

	// database is nil when the server returned 304 Not Modified.
	if database == nil && cached != nil {
		// Bump LastRefresh so we don't re-check until the next interval.
		cached.LastRefresh = time.Now()
		if saveErr := saveToCache(cacheFile, &cached.Database, cached.ETag); saveErr != nil {
			slog.WarnContext(ctx, "Failed to update cache timestamp", "error", saveErr)
		}
		return &cached.Database, true
	}

	// Save the fresh data to cache.
	if saveErr := saveToCache(cacheFile, database, newETag); saveErr != nil {
		slog.WarnContext(ctx, "Failed to save to cache", "error", saveErr)
	}

	return database, true
}

// fetchFromAPI fetches the models.dev database.
// If etag is non-empty it is sent as If-None-Match; a 304 response