feat: add check_mutable_updates flag for conditional upstream revalidation

When check_mutable_updates: true is set on a remote, expired user-defined
mutable files are revalidated before re-downloading:

- On expiry a conditional HEAD is sent with If-None-Match / If-Modified-Since
- 304 Not Modified: TTL is refreshed in Redis, S3 cache is untouched
- 200 / no conditional support: cache is invalidated and file re-downloaded
- Network error: safe fallback — assume changed, re-download

ETag and Last-Modified from upstream responses are stored in Redis under
mutable:meta:<remote>:<hash> (no expiry, cleaned up on re-download or
cache flush). The flag only applies to user-configured mutable_patterns;
built-in package-type defaults (APKINDEX, repomd.xml, Docker manifests)
are always re-fetched unconditionally.

cache/flush also clears mutable:meta:* keys alongside index:* keys.

tests/conftest.py

@@ -59,6 +59,14 @@ TEST_REMOTES = {
             "mutable_patterns": ["metadata\\.json$"],
             "cache": {"immutable_ttl": 0, "mutable_ttl": 600},
         },
+        "check-mutable-test": {
+            "base_url": "https://example.com",
+            "type": "remote",
+            "package": "generic",
+            "mutable_patterns": ["metadata\\.json$"],
+            "check_mutable_updates": True,
+            "cache": {"immutable_ttl": 0, "mutable_ttl": 600},
+        },
         "local-test": {
             "type": "local",
             "package": "generic",

tests/test_cache.py

@@ -235,3 +235,51 @@ class TestIndexValidity:
         # client is None when Redis is unavailable — setex cannot be called
         assert unavailable_cache.client is None
         unavailable_cache.mark_index_cached("remote", "some/path", 300)  # must not raise
+
+
+# ---------------------------------------------------------------------------
+# mutable meta (ETag / Last-Modified storage)
+# ---------------------------------------------------------------------------
+
+
+class TestMutableMeta:
+    def test_meta_key_format(self, bare_cache):
+        path = "repo/metadata.json"
+        expected_hash = hashlib.sha256(path.encode()).hexdigest()[:16]
+        assert bare_cache.get_mutable_meta_key("myremote", path) == f"mutable:meta:myremote:{expected_hash}"
+
+    def test_meta_key_hash_is_16_chars(self, bare_cache):
+        key = bare_cache.get_mutable_meta_key("remote", "some/path/file.json")
+        assert len(key.split(":")[-1]) == 16
+
+    def test_store_and_retrieve_etag(self, cache_with_redis, mock_redis_client):
+        mock_redis_client.hgetall.return_value = {"etag": '"abc123"'}
+        cache_with_redis.store_mutable_meta("remote", "path/meta.json", '"abc123"', None)
+        mock_redis_client.hset.assert_called_once()
+        meta = cache_with_redis.get_mutable_meta("remote", "path/meta.json")
+        assert meta["etag"] == '"abc123"'
+
+    def test_store_and_retrieve_last_modified(self, cache_with_redis, mock_redis_client):
+        lm = "Mon, 01 Jan 2024 00:00:00 GMT"
+        mock_redis_client.hgetall.return_value = {"last_modified": lm}
+        cache_with_redis.store_mutable_meta("remote", "path/meta.json", None, lm)
+        meta = cache_with_redis.get_mutable_meta("remote", "path/meta.json")
+        assert meta["last_modified"] == lm
+
+    def test_store_no_op_when_both_none(self, cache_with_redis, mock_redis_client):
+        cache_with_redis.store_mutable_meta("remote", "path/meta.json", None, None)
+        mock_redis_client.hset.assert_not_called()
+
+    def test_store_no_op_when_unavailable(self, unavailable_cache):
+        unavailable_cache.store_mutable_meta("remote", "path", "etag", None)  # must not raise
+
+    def test_get_returns_empty_when_unavailable(self, unavailable_cache):
+        assert unavailable_cache.get_mutable_meta("remote", "path") == {}
+
+    def test_delete_removes_meta_key(self, cache_with_redis, mock_redis_client):
+        expected_key = cache_with_redis.get_mutable_meta_key("remote", "path/meta.json")
+        cache_with_redis.delete_mutable_meta("remote", "path/meta.json")
+        mock_redis_client.delete.assert_called_once_with(expected_key)
+
+    def test_delete_no_op_when_unavailable(self, unavailable_cache):
+        unavailable_cache.delete_mutable_meta("remote", "path")  # must not raise

tests/test_config.py

@@ -208,6 +208,39 @@ class TestGetImmutablePatterns:
         assert cfg.get_immutable_patterns("r", "/unknown/path") == [r".*\.tar\.gz$"]
 
 
+# ---------------------------------------------------------------------------
+# get_user_mutable_patterns
+# ---------------------------------------------------------------------------
+
+
+class TestGetUserMutablePatterns:
+    def test_returns_only_user_patterns(self, make_config):
+        cfg = make_config(
+            {
+                "r": {
+                    "type": "remote",
+                    "package": "alpine",
+                    "base_url": "https://x.com",
+                    "mutable_patterns": [r"custom\.json$"],
+                }
+            }
+        )
+        assert cfg.get_user_mutable_patterns("r") == [r"custom\.json$"]
+
+    def test_excludes_package_defaults(self, make_config):
+        # Package defaults (APKINDEX etc.) must NOT appear here
+        cfg = make_config({"r": {"type": "remote", "package": "alpine", "base_url": "https://x.com"}})
+        assert cfg.get_user_mutable_patterns("r") == []
+
+    def test_returns_empty_for_missing_remote(self, make_config):
+        cfg = make_config({})
+        assert cfg.get_user_mutable_patterns("nonexistent") == []
+
+    def test_returns_empty_when_key_absent(self, make_config):
+        cfg = make_config({"r": {"type": "remote", "package": "generic", "base_url": "https://x.com"}})
+        assert cfg.get_user_mutable_patterns("r") == []
+
+
 # ---------------------------------------------------------------------------
 # get_cache_config
 # ---------------------------------------------------------------------------

tests/test_routes.py

@@ -419,6 +419,53 @@ class TestGenericArtifactRoute:
         response = client.get("/api/v1/remote/alpine-test/alpine/v3.18/x86_64/APKINDEX.tar.gz")
         assert response.status_code == 200
 
+    def test_mutable_unchanged_refreshes_ttl_without_redownload(self, client, patched_deps):
+        """When check_mutable_updates=True and upstream says 304, TTL is refreshed in place."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = True
+        deps["storage"].download_object.return_value = b"metadata content"
+        # File is mutable and its TTL has expired
+        deps["cache"].is_mutable_file.return_value = True
+        deps["cache"].is_index_valid.return_value = False
+        deps["cache"].get_mutable_meta.return_value = {"etag": '"abc"'}
+
+        with patch("artifactapi.main.check_upstream_changed", new_callable=AsyncMock, return_value=False):
+            response = client.get("/api/v1/remote/check-mutable-test/metadata.json")
+
+        assert response.status_code == 200
+        deps["cache"].mark_index_cached.assert_called()
+        # S3 object must NOT have been deleted (no re-download)
+        deps["storage"].client.delete_object.assert_not_called()
+
+    def test_mutable_changed_triggers_redownload(self, client, patched_deps):
+        """When check_mutable_updates=True and upstream says 200, cache is invalidated."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = False
+        deps["cache"].is_mutable_file.return_value = True
+        deps["cache"].is_index_valid.return_value = False
+        deps["cache"].get_mutable_meta.return_value = {"etag": '"abc"'}
+
+        with patch("artifactapi.main.check_upstream_changed", new_callable=AsyncMock, return_value=True):
+            with patch("artifactapi.main.cache_single_artifact", new_callable=AsyncMock) as mock_cache:
+                mock_cache.return_value = {"status": "error", "error": "upstream gone"}
+                response = client.get("/api/v1/remote/check-mutable-test/metadata.json")
+
+        assert response.status_code == 502
+
+    def test_mutable_flag_off_skips_conditional_check(self, client, patched_deps):
+        """When check_mutable_updates is not set, expired mutable files are always re-fetched."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = False
+        deps["cache"].is_mutable_file.return_value = True
+        deps["cache"].is_index_valid.return_value = False
+
+        with patch("artifactapi.main.check_upstream_changed", new_callable=AsyncMock) as mock_check:
+            with patch("artifactapi.main.cache_single_artifact", new_callable=AsyncMock) as mock_cache:
+                mock_cache.return_value = {"status": "error", "error": "upstream gone"}
+                client.get("/api/v1/remote/custom-index-test/metadata.json")
+
+        mock_check.assert_not_called()
+
     def test_local_repo_file_not_found_returns_404(self, client, patched_deps):
         deps = patched_deps
         deps["database"].get_local_file_metadata.return_value = None
@@ -519,8 +566,8 @@ class TestCacheFlushEndpoint:
         deps["cache"].available = True
         redis_mock = MagicMock()
         deps["cache"].client = redis_mock
-        # First pattern (index:*) returns keys; subsequent pattern returns nothing
-        redis_mock.keys.side_effect = [["index:test:abc", "index:test:def"], []]
+        # index:* returns keys; mutable:meta:* and metrics:* return nothing
+        redis_mock.keys.side_effect = [["index:test:abc", "index:test:def"], [], []]
         deps["storage"].client.list_objects_v2.return_value = {}
 
         response = client.put("/cache/flush")