Module providers_cache 

Remote provider preset catalog — download, cache, and merge with the bundled + providers.d preset sources.

Design

The bundled providers.toml is the compile-time fallback. A JSON cache file at <user_data_dir>/providers_cache.json (written by recursive providers update) holds presets fetched from an upstream catalog URL. When the kernel resolves the effective preset list (see crate::providers::all_presets_effective), cached presets override bundled entries with the same id (so stale bundled pricing gets refreshed upstream), while bundled presets absent from the cache are kept as-is. User overrides from providers.d/ are layered on top by crate::providers::all_presets_effective.

Cache file format

{
  "schema_version": 1,
  "updated_at": "2026-06-06T00:00:00Z",
  "source_url": "https://...",
  "providers": [ ... ]
}

The providers array uses the same structure as ProviderPreset plus the same optional fields (anthropic_api_base, pricing, etc.).

Network policy

The only network touch is fetch_and_save, invoked explicitly by recursive providers update (and, if enabled, the best-effort spawn_background_refresh). Preset lookup never hits the network — load_cache reads a local JSON file. URLs are validated by validate_providers_url which mirrors the SSRF guard in tools::web_fetch (scheme + loopback/private/metadata blocking).

Structs

ProvidersCache

On-disk cache envelope.

Constants

CACHE_TTL

How old the cache can be before needs_update returns true.

DEFAULT_PROVIDERS_URL

Default upstream catalog. Users can override via the RECURSIVE_PROVIDERS_URL env var or recursive providers update --url. The repo jeffkit/recursive-providers publishes providers.json here.

PROVIDERS_URL_ENV

Env var override for the upstream URL.

Functions

cache_path

Return path to the cache file: <user_data_dir>/providers_cache.json.

configured_url

Return the configured upstream URL: RECURSIVE_PROVIDERS_URL if set, otherwise DEFAULT_PROVIDERS_URL.

fetch_and_save

Download the providers JSON from url, parse it, write to the cache file, and return the parsed ProvidersCache. The URL is validated by validate_providers_url before any request is made.

load_cache

Load the cache from disk. Returns None if the file is absent or unreadable — callers fall back to bundled presets in that case.

merge_over_bundled

Merge cached presets over bundled ones. For each preset in cache, the cached copy wins (placed first); bundled presets whose id is absent from the cache are appended afterwards. Used by crate::providers::all_presets_effective.

needs_update

True if the cache is absent or older than CACHE_TTL.

spawn_background_refresh

Spawn a best-effort background task that silently refreshes the cache if it is stale. Errors are logged at debug level and never surface to the caller. Returns immediately; the refresh happens concurrently. No-op if the cache is fresh.

validate_providers_url

Validate an upstream catalog URL. Mirrors the SSRF guard in tools::web_fetch: requires an http(s) scheme and rejects loopback / private / link-local / cloud-metadata hosts so a misconfigured RECURSIVE_PROVIDERS_URL cannot be turned into an internal-network probe.