Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(utils): CachedRemoteIndex — one remote-catalog engine (plan 77 F1)

Juan Denis57c0dc3956e1
diff --git a/backend/app/services/registry_service.py b/backend/app/services/registry_service.py
index 60da5ed1..4f166162 100644
--- a/backend/app/services/registry_service.py
+++ b/backend/app/services/registry_service.py
@@ -23,6 +23,7 @@ from urllib.parse import urljoin
import requests
from app.models.plugin import InstalledPlugin
+from app.utils.remote_index import CachedRemoteIndex
logger = logging.getLogger(__name__)
@@ -42,20 +43,6 @@ DEFAULT_REGISTRY_URL = (
)
-def _registry_url():
- """Resolve the live index URL per request (env changes apply without a
- restart). Unset ⇒ the public registry; set-but-empty ⇒ disabled."""
- value = os.environ.get('SERVERKIT_REGISTRY_URL')
- if value is None:
- return DEFAULT_REGISTRY_URL
- return value.strip()
-try:
- _TTL = int(os.environ.get('SERVERKIT_REGISTRY_TTL', '3600'))
-except ValueError:
- _TTL = 3600
-
-# Module-level cache: last successfully-parsed entry list + when we fetched it.
-_cache = {'ts': 0.0, 'entries': None, 'source': None}
# Fields we surface for a registry entry, with defaults. Index v2 adds
# `repo`, `logo`, and `bundled` (see the serverkit-extensions schema); any
@@ -171,56 +158,30 @@ def _read_index_payload(payload, base_url=None):
return [e for e in (_normalize(x, base_url) for x in exts) if e]
-def _load_bundled():
- try:
- with open(_BUNDLED_INDEX, 'r', encoding='utf-8') as f:
- # Bundled copy mirrors the public index; resolve its relative logos
- # against the default (raw-GitHub) index base.
- return _read_index_payload(json.load(f), base_url=DEFAULT_REGISTRY_URL)
- except Exception as e:
- logger.warning(f'Could not read bundled registry index: {e}')
- return []
-
+# One remote-catalog engine (plan 77 F1): fetch -> TTL -> last-good ->
+# bundled, with the failure-retry throttling theme_registry had already
+# hardened to. This module stays a thin normalizer (_read_index_payload).
+_index = CachedRemoteIndex(
+ name='Registry',
+ env_var='SERVERKIT_REGISTRY_URL',
+ default_url=DEFAULT_REGISTRY_URL,
+ normalize_fn=_read_index_payload,
+ bundled_path=_BUNDLED_INDEX,
+ # Bundled copy mirrors the public index; resolve its relative logos
+ # against the default index base.
+ bundled_base_url=DEFAULT_REGISTRY_URL,
+ ttl=3600,
+ ttl_env_var='SERVERKIT_REGISTRY_TTL',
+)
-def _fetch_remote():
- url = _registry_url()
- if not url:
- return None
- resp = requests.get(url, timeout=15, headers={
- 'Accept': 'application/json',
- 'User-Agent': 'ServerKit-Registry/1.0',
- })
- resp.raise_for_status()
- return _read_index_payload(resp.json(), base_url=url)
+# Test seam: the shared cache dict (tests reset/seed it in place).
+_cache = _index._cache
def refresh(force=False):
"""Return the registry entries, refreshing from the remote index when the
cache is stale. Never raises — falls back to cache, then bundled copy."""
- now = time.time()
- if not force and _cache['entries'] is not None and (now - _cache['ts']) < _TTL:
- return _cache['entries']
-
- entries = None
- source = None
- try:
- entries = _fetch_remote()
- if entries is not None:
- source = 'remote'
- except Exception as e:
- logger.warning(f'Registry fetch failed ({_registry_url()}): {e}')
-
- if entries is None:
- # Keep the last good remote cache if we have one; else bundled.
- if _cache['entries'] is not None:
- return _cache['entries']
- entries = _load_bundled()
- source = 'bundled'
-
- _cache['entries'] = entries
- _cache['ts'] = now
- _cache['source'] = source
- return entries
+ return _index.get(force=force)
def _show_unreviewed():
diff --git a/backend/app/services/theme_registry_service.py b/backend/app/services/theme_registry_service.py
index 157d5007..a72d69c8 100644
--- a/backend/app/services/theme_registry_service.py
+++ b/backend/app/services/theme_registry_service.py
@@ -22,6 +22,8 @@ from urllib.parse import urljoin
import requests
+from app.utils.remote_index import CachedRemoteIndex
+
from app.exceptions import (
DependencyUnavailableError,
NotFoundError,
@@ -57,24 +59,6 @@ _FIELDS = {
}
-def _registry_url():
- value = os.environ.get('SERVERKIT_THEMES_REGISTRY_URL')
- if value is None:
- return DEFAULT_REGISTRY_URL
- return value.strip()
-
-
-try:
- _TTL = int(os.environ.get('SERVERKIT_THEMES_REGISTRY_TTL', '3600'))
-except ValueError:
- _TTL = 3600
-
-# After a failed fetch with no cache to serve, hold the bundled fallback only
-# this long before retrying upstream (instead of the full TTL) — the panel
-# recovers quickly when the registry comes back, without hammering it.
-_FAILURE_TTL = 60
-
-_cache = {'ts': 0.0, 'entries': None, 'source': None}
def _resolve_url(path, base_url):
@@ -106,58 +90,33 @@ def _read_index_payload(payload, base_url=None):
return [t for t in (_normalize(x, base_url) for x in themes) if t]
-def _load_bundled():
- try:
- with open(_BUNDLED_INDEX, 'r', encoding='utf-8') as f:
- return _read_index_payload(json.load(f), base_url=None)
- except Exception as e:
- logger.warning('Could not read bundled themes index: %s', e)
- return []
-
+# One remote-catalog engine (plan 77 F1); this module stays a thin
+# normalizer. The failure-retry semantics this service pioneered
+# (last-good served under full TTL, bundled held only error_ttl) now live
+# in CachedRemoteIndex for every catalog.
+_index = CachedRemoteIndex(
+ name='Themes',
+ env_var='SERVERKIT_THEMES_REGISTRY_URL',
+ default_url=DEFAULT_REGISTRY_URL,
+ normalize_fn=_read_index_payload,
+ bundled_path=_BUNDLED_INDEX,
+ bundled_base_url=None,
+ ttl=3600,
+ ttl_env_var='SERVERKIT_THEMES_REGISTRY_TTL',
+ error_ttl=60,
+)
-def _fetch_remote():
- url = _registry_url()
- if not url:
- return None, None
- resp = requests.get(url, timeout=15, headers={
- 'Accept': 'application/json',
- 'User-Agent': 'ServerKit-Themes/1.0',
- })
- resp.raise_for_status()
- return _read_index_payload(resp.json(), base_url=url), url
+# Test seams: the shared cache dict + the failure-retry window name the
+# theme tests already use.
+_cache = _index._cache
+_FAILURE_TTL = _index.error_ttl
+_TTL = _index.ttl
def refresh(force=False):
"""Return registry entries, refreshing when the cache is stale. Never
raises — falls back to last-good cache, then the bundled index."""
- now = time.time()
- if not force and _cache['entries'] is not None and (now - _cache['ts']) < _TTL:
- return _cache['entries']
-
- entries = None
- source = None
- failed = False
- try:
- entries, _ = _fetch_remote()
- if entries is not None:
- source = 'remote'
- except Exception as e:
- failed = True
- logger.warning('Theme registry fetch failed (%s): %s', _registry_url(), e)
-
- if entries is None:
- if _cache['entries'] is not None:
- # Failed refresh with a last-good cache: serve it and stamp the
- # timestamp so the TTL applies — otherwise every call retries the
- # network and stalls up to the fetch timeout.
- _cache['ts'] = now
- return _cache['entries']
- entries = _load_bundled()
- source = 'bundled'
-
- ts = now - (_TTL - _FAILURE_TTL) if failed else now
- _cache.update({'entries': entries, 'ts': ts, 'source': source})
- return entries
+ return _index.get(force=force)
def _installed_slugs():
diff --git a/backend/app/utils/remote_index.py b/backend/app/utils/remote_index.py
new file mode 100644
index 00000000..d7fdd2b7
--- /dev/null
+++ b/backend/app/utils/remote_index.py
@@ -0,0 +1,128 @@
+"""CachedRemoteIndex — the one remote-catalog engine (plan 77 F1).
+
+The fetch → TTL cache → last-good fallback → bundled-file fallback pipeline
+was re-implemented per catalog (extension registry, theme registry, …) and
+has drifted in production before (bundled-index and proxy-rewrite
+incidents). This class owns the hardened behavior once; services stay thin
+normalizers and future catalogs get it free.
+
+Semantics (the superset that theme_registry had already hardened to):
+
+- Success: entries cached for ``ttl`` seconds, ``source='remote'``.
+- Env override: unset ⇒ ``default_url``; set-but-EMPTY ⇒ explicitly disabled
+ (bundled copy only — also how the test suite stays offline).
+- Fetch failure with a last-good copy: serve it and stamp the clock so the
+ TTL applies (every call retrying a dead upstream would stall each request
+ behind the fetch timeout).
+- Fetch failure with nothing cached: serve the bundled file, but hold it
+ only ``error_ttl`` seconds before retrying upstream — the panel recovers
+ quickly when the registry comes back, without hammering it.
+- ``normalize_fn(payload, base_url)`` turns the raw JSON payload into the
+ entry list; relative asset paths resolve against the URL actually fetched.
+"""
+import json
+import logging
+import os
+import threading
+import time
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class CachedRemoteIndex:
+ def __init__(self, name, env_var, default_url, normalize_fn,
+ bundled_path=None, bundled_base_url=None,
+ ttl=3600, ttl_env_var=None, error_ttl=60,
+ timeout=15, user_agent=None):
+ self.name = name
+ self.env_var = env_var
+ self.default_url = default_url
+ self.normalize_fn = normalize_fn
+ self.bundled_path = bundled_path
+ self.bundled_base_url = bundled_base_url
+ self.error_ttl = error_ttl
+ self.timeout = timeout
+ self.user_agent = user_agent or f'ServerKit-{name}/1.0'
+ self.ttl = ttl
+ if ttl_env_var:
+ try:
+ self.ttl = int(os.environ.get(ttl_env_var, str(ttl)))
+ except ValueError:
+ self.ttl = ttl
+ # Kept as a plain dict (not attributes) so a service module can alias
+ # it (`_cache = _index._cache`) for tests that inspect/twiddle it.
+ self._cache = {'ts': 0.0, 'entries': None, 'source': None}
+ self._lock = threading.Lock()
+
+ # ------------------------------------------------------------------ url
+ def url(self):
+ """Live index URL, resolved per call so env changes apply without a
+ restart. Unset ⇒ default; set-but-empty ⇒ disabled (empty string)."""
+ value = os.environ.get(self.env_var)
+ if value is None:
+ return self.default_url
+ return value.strip()
+
+ # ------------------------------------------------------------------ get
+ def get(self, force=False):
+ """Return the entries, refreshing when stale. Never raises."""
+ now = time.time()
+ with self._lock:
+ if (not force and self._cache['entries'] is not None
+ and (now - self._cache['ts']) < self.ttl):
+ return self._cache['entries']
+
+ entries = None
+ source = None
+ failed = False
+ try:
+ entries = self._fetch_remote()
+ if entries is not None:
+ source = 'remote'
+ except Exception as exc:
+ failed = True
+ logger.warning('%s index fetch failed (%s): %s',
+ self.name, self.url(), exc)
+
+ with self._lock:
+ if entries is None:
+ if self._cache['entries'] is not None:
+ # Serve last-good; stamp the clock so the TTL applies.
+ self._cache['ts'] = now
+ return self._cache['entries']
+ entries = self._load_bundled()
+ source = 'bundled'
+ ts = now - (self.ttl - self.error_ttl) if failed else now
+ self._cache.update({'entries': entries, 'ts': ts, 'source': source})
+ return entries
+
+ def invalidate(self):
+ with self._lock:
+ self._cache.update({'ts': 0.0, 'entries': None, 'source': None})
+
+ def source_label(self):
+ return self._cache.get('source')
+
+ # -------------------------------------------------------------- internals
+ def _fetch_remote(self):
+ url = self.url()
+ if not url:
+ return None
+ resp = requests.get(url, timeout=self.timeout, headers={
+ 'Accept': 'application/json',
+ 'User-Agent': self.user_agent,
+ })
+ resp.raise_for_status()
+ return self.normalize_fn(resp.json(), url)
+
+ def _load_bundled(self):
+ if not self.bundled_path:
+ return []
+ try:
+ with open(self.bundled_path, 'r', encoding='utf-8') as f:
+ return self.normalize_fn(json.load(f), self.bundled_base_url)
+ except Exception as exc:
+ logger.warning('Could not read bundled %s index: %s', self.name, exc)
+ return []
diff --git a/backend/tests/test_extension_signing.py b/backend/tests/test_extension_signing.py
index 491fd6ff..139dc916 100644
--- a/backend/tests/test_extension_signing.py
+++ b/backend/tests/test_extension_signing.py
@@ -312,7 +312,7 @@ def test_registry_install_passes_signature_through(
zip_bytes = _make_plugin_zip()
sig = signing_service.sign_bytes(zip_bytes, priv)
monkeypatch.setattr(plugin_service, '_download_zip', lambda url: io.BytesIO(zip_bytes))
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'signed-ext', 'display_name': 'Signed Ext', 'version': '1.0.0',
@@ -338,7 +338,7 @@ def test_registry_install_bad_signature_hard_fails(
zip_bytes = _make_plugin_zip()
bad_sig = signing_service.sign_bytes(b'other bytes', priv)
monkeypatch.setattr(plugin_service, '_download_zip', lambda url: io.BytesIO(zip_bytes))
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'signed-ext', 'display_name': 'Signed Ext', 'version': '1.0.0',
@@ -421,7 +421,7 @@ def fake_install(monkeypatch):
def _seed_entry(monkeypatch, entry):
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test', 'entries': [entry],
})
@@ -589,7 +589,7 @@ def _seed_update_entry(monkeypatch, slug, version='2.0.0', **overrides):
'min_panel_version': '0.0.1',
}
base.update(overrides)
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize(base)],
})
diff --git a/backend/tests/test_registry.py b/backend/tests/test_registry.py
index ac179b0f..39050e92 100644
--- a/backend/tests/test_registry.py
+++ b/backend/tests/test_registry.py
@@ -84,7 +84,7 @@ def test_version_helpers():
def test_registry_install_blocked_by_min_panel_version(app, plugin_dirs, monkeypatch):
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'future-ext', 'display_name': 'Future', 'version': '1.0.0',
@@ -127,7 +127,7 @@ def test_registry_install_stamps_registry_source_type(app, plugin_dirs, monkeypa
zip_bytes = _make_plugin_zip()
digest = hashlib.sha256(zip_bytes).hexdigest()
monkeypatch.setattr(plugin_service, '_download_zip', lambda url: io.BytesIO(zip_bytes))
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'regext', 'display_name': 'Registry Ext', 'version': '2.0.0',
@@ -155,7 +155,7 @@ def test_update_flow(app, plugin_dirs, monkeypatch):
assert plugin.source_type == 'url'
# Registry advertises v2.0.0 for the same slug.
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'regext', 'display_name': 'Registry Ext', 'version': '2.0.0',
@@ -183,7 +183,7 @@ def test_update_keeps_registry_source_type(app, plugin_dirs, monkeypatch):
v1 = _make_plugin_zip(slug='regext', version='1.0.0')
digest_v1 = hashlib.sha256(v1).hexdigest()
monkeypatch.setattr(plugin_service, '_download_zip', lambda url: io.BytesIO(v1))
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'regext', 'display_name': 'Registry Ext', 'version': '1.0.0',
@@ -197,7 +197,7 @@ def test_update_keeps_registry_source_type(app, plugin_dirs, monkeypatch):
# Registry moves to v2; run the update.
v2 = _make_plugin_zip(slug='regext', version='2.0.0')
monkeypatch.setattr(plugin_service, '_download_zip', lambda url: io.BytesIO(v2))
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'regext', 'display_name': 'Registry Ext', 'version': '2.0.0',
@@ -221,7 +221,7 @@ def test_update_preserves_builtin_source_type(app, plugin_dirs, monkeypatch):
v2 = _make_plugin_zip(slug='regext', version='2.0.0')
monkeypatch.setattr(plugin_service, '_download_zip', lambda url: io.BytesIO(v2))
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [registry_service._normalize({
'slug': 'regext', 'display_name': 'Registry Ext', 'version': '2.0.0',
@@ -244,7 +244,7 @@ def test_registry_url_defaults_to_public_index(monkeypatch):
it proxies the raw serverkit-extensions index with caching + logo URL
rewriting). conftest pins it EMPTY suite-wide, so simulate unset here."""
monkeypatch.delenv('SERVERKIT_REGISTRY_URL', raising=False)
- assert registry_service._registry_url() == registry_service.DEFAULT_REGISTRY_URL
+ assert registry_service._index.url() == registry_service.DEFAULT_REGISTRY_URL
assert registry_service.DEFAULT_REGISTRY_URL == 'https://serverkit.ai/ext/index.json'
@@ -252,13 +252,13 @@ def test_registry_url_empty_disables_remote(monkeypatch):
"""Explicitly-empty env disables the remote entirely (bundled only) —
the hermetic-test/air-gapped escape hatch."""
monkeypatch.setenv('SERVERKIT_REGISTRY_URL', '')
- assert registry_service._registry_url() == ''
- assert registry_service._fetch_remote() is None
+ assert registry_service._index.url() == ''
+ assert registry_service._index._fetch_remote() is None
def test_registry_url_env_override_wins(monkeypatch):
monkeypatch.setenv('SERVERKIT_REGISTRY_URL', 'https://example.test/index.json')
- assert registry_service._registry_url() == 'https://example.test/index.json'
+ assert registry_service._index.url() == 'https://example.test/index.json'
# --------------------------------------------------------------------------- #
@@ -312,7 +312,7 @@ def test_v1_entry_unaffected_by_v2_defaults():
def test_bundled_excluded_from_catalog_by_default(app, monkeypatch):
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [
registry_service._normalize({
@@ -335,7 +335,7 @@ def test_bundled_excluded_from_catalog_by_default(app, monkeypatch):
def test_registry_endpoint_include_bundled_flag(app, client, auth_headers, monkeypatch):
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test',
'entries': [
registry_service._normalize({
@@ -421,7 +421,7 @@ def fake_install(monkeypatch):
def _seed_cache(monkeypatch, entry):
- monkeypatch.setattr(registry_service, '_cache', {
+ registry_service._cache.update({
'ts': 9e18, 'source': 'test', 'entries': [entry],
})
diff --git a/backend/tests/test_remote_index.py b/backend/tests/test_remote_index.py
new file mode 100644
index 00000000..53d9e8db
--- /dev/null
+++ b/backend/tests/test_remote_index.py
@@ -0,0 +1,140 @@
+"""Plan 77 F1 — CachedRemoteIndex: the one remote-catalog engine.
+
+No network: the fetcher is monkeypatched. These pin the hardened semantics
+(last-good under full TTL after a failure; bundled held only error_ttl) that
+the per-service copies used to drift on.
+"""
+import json
+import time
+
+import pytest
+
+from app.utils.remote_index import CachedRemoteIndex
+
+
+def _normalize(payload, base_url):
+ items = payload.get('items') if isinstance(payload, dict) else None
+ if not isinstance(items, list):
+ return []
+ return [{'slug': x['slug'], 'base': base_url} for x in items if x.get('slug')]
+
+
+def _index(tmp_path, monkeypatch, env=None, bundled=None, **kwargs):
+ if env is not None:
+ monkeypatch.setenv('X_INDEX_URL', env)
+ else:
+ monkeypatch.delenv('X_INDEX_URL', raising=False)
+ bundled_path = None
+ if bundled is not None:
+ bundled_path = tmp_path / 'bundled.json'
+ bundled_path.write_text(json.dumps(bundled), encoding='utf-8')
+ return CachedRemoteIndex(
+ name='X', env_var='X_INDEX_URL',
+ default_url='https://example.test/index.json',
+ normalize_fn=_normalize,
+ bundled_path=str(bundled_path) if bundled_path else None,
+ bundled_base_url='bundled://',
+ ttl=100, error_ttl=10,
+ **kwargs,
+ )
+
+
+class _Fetch:
+ def __init__(self, results):
+ self.results = list(results)
+ self.calls = 0
+
+ def __call__(self):
+ self.calls += 1
+ result = self.results.pop(0) if self.results else self.results_last
+ if isinstance(result, Exception):
+ raise result
+ self.results_last = result
+ return result
+
+
+def test_success_caches_within_ttl(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch)
+ fetch = _Fetch([[{'slug': 'a', 'base': 'https://example.test/index.json'}]])
+ monkeypatch.setattr(idx, '_fetch_remote', fetch)
+ first = idx.get()
+ assert first[0]['slug'] == 'a'
+ assert idx.source_label() == 'remote'
+ assert idx.get() is first
+ assert fetch.calls == 1
+
+
+def test_force_refetches(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch)
+ fetch = _Fetch([[{'slug': 'a'}], [{'slug': 'b'}]])
+ monkeypatch.setattr(idx, '_fetch_remote', fetch)
+ idx.get()
+ assert idx.get(force=True)[0]['slug'] == 'b'
+ assert fetch.calls == 2
+
+
+def test_ttl_expiry_refetches(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch)
+ fetch = _Fetch([[{'slug': 'a'}], [{'slug': 'b'}]])
+ monkeypatch.setattr(idx, '_fetch_remote', fetch)
+ idx.get()
+ idx._cache['ts'] -= idx.ttl + 1
+ assert idx.get()[0]['slug'] == 'b'
+
+
+def test_failure_serves_last_good_under_full_ttl(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch)
+ fetch = _Fetch([[{'slug': 'good'}], RuntimeError('down')])
+ monkeypatch.setattr(idx, '_fetch_remote', fetch)
+ idx.get()
+ idx._cache['ts'] -= idx.ttl + 1
+ served = idx.get()
+ assert served[0]['slug'] == 'good'
+ assert fetch.calls == 2
+ # last-good is stamped with the full TTL — the next call must NOT retry
+ idx.get()
+ assert fetch.calls == 2
+
+
+def test_failure_with_nothing_serves_bundled_for_error_ttl_only(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch,
+ bundled={'items': [{'slug': 'bundled-entry'}]})
+ fetch = _Fetch([RuntimeError('down'), [{'slug': 'live'}]])
+ monkeypatch.setattr(idx, '_fetch_remote', fetch)
+ served = idx.get()
+ assert served[0]['slug'] == 'bundled-entry'
+ assert idx.source_label() == 'bundled'
+ # inside the error_ttl window: no retry
+ assert idx.get()[0]['slug'] == 'bundled-entry'
+ assert fetch.calls == 1
+ # after the error_ttl window (but well under the full TTL): retried
+ idx._cache['ts'] -= idx.error_ttl + 1
+ assert idx.get()[0]['slug'] == 'live'
+ assert fetch.calls == 2
+
+
+def test_bundled_normalize_uses_bundled_base_url(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch, env='', # disabled: bundled only
+ bundled={'items': [{'slug': 's'}]})
+ served = idx.get()
+ assert served[0]['base'] == 'bundled://'
+ assert idx.source_label() == 'bundled'
+
+
+def test_env_url_resolution(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch)
+ assert idx.url() == 'https://example.test/index.json'
+ monkeypatch.setenv('X_INDEX_URL', 'https://override.test/i.json')
+ assert idx.url() == 'https://override.test/i.json'
+ monkeypatch.setenv('X_INDEX_URL', '')
+ assert idx.url() == ''
+
+
+def test_invalidate_clears_cache(tmp_path, monkeypatch):
+ idx = _index(tmp_path, monkeypatch)
+ fetch = _Fetch([[{'slug': 'a'}], [{'slug': 'b'}]])
+ monkeypatch.setattr(idx, '_fetch_remote', fetch)
+ idx.get()
+ idx.invalidate()
+ assert idx.source_label() is None
+ assert idx.get()[0]['slug'] == 'b'