feat: add redis cache for copyright label lookups (#566)

* feat: add redis cache for copyright label lookups

the moderation service call was causing 2-3s latency spikes on GET /tracks/
in production. since we have multiple fly.io instances, in-memory caching
wouldn't work - added distributed redis cache (reusing docket's redis).

- add backend/utilities/redis.py for async client from docket URL
- cache active label status with 5min TTL (matches queue cache)
- use mget/pipeline for efficient batch operations
- invalidate cache when labels are emitted
- fail closed on errors (treat as active)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* refactor: move cache settings to config, add async context manager

- add label_cache_prefix and label_cache_ttl_seconds to ModerationSettings
- add async_redis_client() context manager for isolated connections
- add clear_client_cache() for test cleanup
- remove hardcoded cache constants from moderation.py
- fix tests to properly clear client cache between runs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* test: add redis isolation for xdist parallel tests

- add redis_database fixture that assigns different DB per worker
- use unique URIs in cache tests to avoid cross-test pollution
- document redis test isolation pattern in docs/testing/README.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: handle missing redis gracefully in test fixture

the redis_database fixture now catches ConnectionError and skips
silently when redis is unavailable. tests that don't need redis
will pass, and tests that do need it will fail with specific errors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: mock settings in moderation cache tests

tests that mock httpx must also mock settings.moderation to avoid
early return on auth_token check. without this, tests pass locally
(where MODERATION_AUTH_TOKEN may be set) but fail in CI.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: use D: prefix for DOCKET_URL to allow CI override

pytest-env's D: prefix means "default" - only set if not already
set by the environment. this allows CI's DOCKET_URL=redis://localhost:6379
to take precedence over pyproject.toml's 6380 (for local docker-compose).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: move deferred imports to top of file, add type hints

- move redis imports to module level in moderation.py
- move asyncio import to module level in redis.py
- add type hint for kwargs dict in redis.py
- move imports to module level in conftest.py
- add rule to AGENTS.md: DO NOT UNNECESSARILY DEFER IMPORTS

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

---------

Co-authored-by: Claude <[e-mail]>

AGENTS.md

···
 *   **Async Everywhere:** Never block the event loop. Use `anyio`/`aiofiles`.
 *   **Type Hints:** Required everywhere (Python & TypeScript).
 *   **Communication:** Use emojis sparingly and strictly for emphasis.
+*   **DO NOT UNNECESSARILY DEFER IMPORTS.** Put imports at the top of the file where they belong. Deferred imports inside functions are only acceptable for avoiding circular imports - not for "lazy loading" or other reasons.
 
 ## 🛠️ Stack & Tooling
 *   **Backend:** FastAPI, Neon (Postgres), Cloudflare R2, Fly.io.
···
 └── STATUS.md         # Living status document
 ```
 
-this file ("AGENTS.md") is symlinked to `CLAUDE.md` and `GEMINI.md` for maximal compatibility.
+this file ("AGENTS.md") is symlinked to `CLAUDE.md` for maximal compatibility.

GEMINI.md

···
-AGENTS.md

backend/pyproject.toml

···
     "orjson>=3.11.4",
     "mutagen>=1.47.0",
     "pydocket>=0.15.2",
+    "redis>=7.1.0",
 ]
 
 requires-python = ">=3.11"
···
     # reduce connection pool for tests to avoid exhausting Neon's connection limit
     "DATABASE_POOL_SIZE=2",
     "DATABASE_MAX_OVERFLOW=0",
+    # redis URL for cache tests (uses test-redis from docker-compose)
+    # D: prefix means don't override if already set (e.g., by CI workflow)
+    "D:DOCKET_URL=redis://localhost:6380/0",
 ]
 markers = [
     "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",

backend/src/backend/_internal/moderation.py

···
 from backend.config import settings
 from backend.models import CopyrightScan, Track
 from backend.utilities.database import db_session
+from backend.utilities.redis import get_async_redis_client
 
 logger = logging.getLogger(__name__)
 
···
             )
             response.raise_for_status()
 
+            # invalidate cache since label status changed
+            await invalidate_label_cache(uri)
+
             logfire.info(
                 "copyright label emitted",
                 uri=uri,
···
 async def get_active_copyright_labels(uris: list[str]) -> set[str]:
     """check which URIs have active (non-negated) copyright-violation labels.
 
-    queries the moderation service's labeler to determine which tracks are
-    still actively flagged. this is the source of truth for flag status.
+    uses redis cache (shared across instances) to avoid repeated calls
+    to the moderation service. only URIs not in cache are fetched.
 
     args:
         uris: list of AT URIs to check
···
         logger.warning("MODERATION_AUTH_TOKEN not set, treating all as active")
         return set(uris)
 
+    # check redis cache first - partition into cached vs uncached
+    active_from_cache: set[str] = set()
+    uris_to_fetch: list[str] = []
+
+    try:
+        redis = get_async_redis_client()
+        prefix = settings.moderation.label_cache_prefix
+        cache_keys = [f"{prefix}{uri}" for uri in uris]
+        cached_values = await redis.mget(cache_keys)
+
+        for uri, cached_value in zip(uris, cached_values, strict=True):
+            if cached_value is not None:
+                if cached_value == "1":
+                    active_from_cache.add(uri)
+                # else: cached as "0" (not active), skip
+            else:
+                uris_to_fetch.append(uri)
+    except Exception as e:
+        # redis unavailable - fall through to fetch all
+        logger.warning("redis cache unavailable: %s", e)
+        uris_to_fetch = list(uris)
+
+    # if everything was cached, return early
+    if not uris_to_fetch:
+        logfire.debug(
+            "checked active copyright labels (all cached)",
+            total_uris=len(uris),
+            active_count=len(active_from_cache),
+        )
+        return active_from_cache
+
+    # fetch uncached URIs from moderation service
     try:
         async with httpx.AsyncClient(
             timeout=httpx.Timeout(settings.moderation.timeout_seconds)
         ) as client:
             response = await client.post(
                 f"{settings.moderation.labeler_url}/admin/active-labels",
-                json={"uris": uris},
+                json={"uris": uris_to_fetch},
                 headers={"X-Moderation-Key": settings.moderation.auth_token},
             )
             response.raise_for_status()
             data = response.json()
-            active = set(data.get("active_uris", []))
-            logfire.debug(
+            active_from_service = set(data.get("active_uris", []))
+
+            # update redis cache with results
+            try:
+                redis = get_async_redis_client()
+                prefix = settings.moderation.label_cache_prefix
+                ttl = settings.moderation.label_cache_ttl_seconds
+                async with redis.pipeline() as pipe:
+                    for uri in uris_to_fetch:
+                        cache_key = f"{prefix}{uri}"
+                        value = "1" if uri in active_from_service else "0"
+                        await pipe.set(cache_key, value, ex=ttl)
+                    await pipe.execute()
+            except Exception as e:
+                # cache update failed - not critical, just log
+                logger.warning("failed to update redis cache: %s", e)
+
+            logfire.info(
                 "checked active copyright labels",
                 total_uris=len(uris),
-                active_count=len(active),
+                cached_count=len(uris) - len(uris_to_fetch),
+                fetched_count=len(uris_to_fetch),
+                active_count=len(active_from_cache) + len(active_from_service),
             )
-            return active
+            return active_from_cache | active_from_service
+
     except Exception as e:
         # fail closed: if we can't confirm resolution, treat as active
+        # don't cache failures - we want to retry next time
         logger.warning("failed to check active labels, treating all as active: %s", e)
         return set(uris)
+
+
+async def invalidate_label_cache(uri: str) -> None:
+    """invalidate cache entry for a URI when its label status changes.
+
+    call this when emitting or negating labels to ensure fresh data.
+    """
+    try:
+        redis = get_async_redis_client()
+        prefix = settings.moderation.label_cache_prefix
+        await redis.delete(f"{prefix}{uri}")
+    except Exception as e:
+        logger.warning("failed to invalidate label cache for %s: %s", uri, e)
+
+
+async def clear_label_cache() -> None:
+    """clear all label cache entries. primarily for testing."""
+    try:
+        redis = get_async_redis_client()
+        prefix = settings.moderation.label_cache_prefix
+        # scan and delete all keys with our prefix
+        cursor = 0
+        while True:
+            cursor, keys = await redis.scan(cursor, match=f"{prefix}*", count=100)
+            if keys:
+                await redis.delete(*keys)
+            if cursor == 0:
+                break
+    except Exception as e:
+        logger.warning("failed to clear label cache: %s", e)
 
 
 async def _store_scan_error(track_id: int, error: str) -> None:

backend/src/backend/config.py

···
         default="https://moderation.plyr.fm",
         description="URL of the ATProto labeler service for emitting labels",
     )
+    label_cache_prefix: str = Field(
+        default="plyr:copyright-label:",
+        description="Redis key prefix for caching copyright label status",
+    )
+    label_cache_ttl_seconds: int = Field(
+        default=300,
+        description="TTL in seconds for cached copyright label status (default 5 min)",
+    )
 
 
 class DocketSettings(AppSettingsSection):

backend/src/backend/utilities/redis.py

···
+"""redis client utilities for distributed caching.
+
+provides async redis client initialized from docket URL settings.
+the client is lazily created and cached per event loop.
+"""
+
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+from urllib.parse import urlparse
+
+import redis.asyncio as async_redis
+
+from backend.config import settings
+
+logger = logging.getLogger(__name__)
+
+# client cache keyed by event loop to handle multiple loops in tests
+_client_cache: dict[int, async_redis.Redis] = {}
+
+
+def _parse_redis_url(url: str) -> dict:
+    """parse a redis URL into connection kwargs.
+
+    supports:
+        - redis://host:port/db
+        - redis://user:password@host:port/db
+        - rediss://... (SSL)
+    """
+    parsed = urlparse(url)
+
+    kwargs: dict[str, Any] = {
+        "host": parsed.hostname or "localhost",
+        "port": parsed.port or 6379,
+        "db": int(parsed.path.lstrip("/") or 0),
+        "decode_responses": True,
+    }
+
+    if parsed.username:
+        kwargs["username"] = parsed.username
+    if parsed.password:
+        kwargs["password"] = parsed.password
+    if parsed.scheme == "rediss":
+        kwargs["ssl"] = True
+
+    return kwargs
+
+
+def get_async_redis_client() -> async_redis.Redis:
+    """get a cached async redis client.
+
+    the client is created lazily on first call and reused.
+    parses connection info from settings.docket.url.
+
+    returns:
+        async redis client
+
+    raises:
+        RuntimeError: if docket URL is not configured
+    """
+    try:
+        loop = asyncio.get_running_loop()
+        loop_id = id(loop)
+    except RuntimeError:
+        loop_id = 0
+
+    if loop_id in _client_cache:
+        return _client_cache[loop_id]
+
+    if not settings.docket.url:
+        raise RuntimeError("docket URL not configured - cannot create redis client")
+
+    kwargs = _parse_redis_url(settings.docket.url)
+
+    client = async_redis.Redis(
+        socket_connect_timeout=5.0,
+        **kwargs,
+    )
+
+    _client_cache[loop_id] = client
+    logger.debug("created async redis client for loop %s", loop_id)
+
+    return client
+
+
+@asynccontextmanager
+async def async_redis_client() -> AsyncGenerator[async_redis.Redis, None]:
+    """async context manager for redis client.
+
+    ensures proper cleanup when used in isolated contexts.
+    for most cases, prefer get_async_redis_client() which caches
+    the connection for reuse.
+
+    yields:
+        async redis client
+
+    raises:
+        RuntimeError: if docket URL is not configured
+    """
+    if not settings.docket.url:
+        raise RuntimeError("docket URL not configured - cannot create redis client")
+
+    kwargs = _parse_redis_url(settings.docket.url)
+    client = async_redis.Redis(
+        socket_connect_timeout=5.0,
+        **kwargs,
+    )
+
+    try:
+        yield client
+    finally:
+        await client.aclose()
+
+
+async def close_redis_client() -> None:
+    """close all cached redis clients."""
+    try:
+        loop = asyncio.get_running_loop()
+        loop_id = id(loop)
+    except RuntimeError:
+        loop_id = 0
+
+    if loop_id in _client_cache:
+        client = _client_cache.pop(loop_id)
+        await client.aclose()
+        logger.debug("closed async redis client for loop %s", loop_id)
+
+
+def clear_client_cache() -> None:
+    """clear the client cache. primarily for testing."""
+    _client_cache.clear()

backend/tests/conftest.py

···
 """pytest configuration for relay tests."""
 
+import os
 from collections.abc import AsyncGenerator, Generator
 from contextlib import asynccontextmanager
 from datetime import UTC, datetime
···
 
 import asyncpg
 import pytest
+import redis as sync_redis_lib
 import sqlalchemy as sa
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
···
 
 from backend.config import settings
 from backend.models import Base
+from backend.utilities.redis import clear_client_cache
 
 
 class MockStorage:
···
     """provides a TestClient for testing the FastAPI application."""
     with TestClient(fastapi_app) as tc:
         yield tc
+
+
+def _redis_db_for_worker(worker_id: str) -> int:
+    """determine redis database number based on xdist worker id.
+
+    uses different DB numbers for each worker to isolate parallel tests:
+    - master/gw0: db 1
+    - gw1: db 2
+    - gw2: db 3
+    - etc.
+
+    db 0 is reserved for local development.
+    """
+    if worker_id == "master" or not worker_id:
+        return 1
+    if "gw" in worker_id:
+        return 1 + int(worker_id.replace("gw", ""))
+    return 1
+
+
+def _redis_url_with_db(base_url: str, db: int) -> str:
+    """replace database number in redis URL."""
+    # redis://host:port/db -> redis://host:port/{new_db}
+    if "/" in base_url.rsplit(":", 1)[-1]:
+        # has db number, replace it
+        base = base_url.rsplit("/", 1)[0]
+        return f"{base}/{db}"
+    else:
+        # no db number, append it
+        return f"{base_url}/{db}"
+
+
[e-mail](scope="session", autouse=True)
+def redis_database(worker_id: str) -> Generator[None, None, None]:
+    """use isolated redis databases for parallel test execution.
+
+    each xdist worker gets its own redis database to prevent cache pollution
+    between tests running in parallel. flushes the db before and after tests.
+
+    if redis is not available, silently skips - tests that actually need redis
+    will fail on their own with a more specific error.
+    """
+    # skip if no redis configured
+    if not settings.docket.url:
+        yield
+        return
+
+    db = _redis_db_for_worker(worker_id)
+    new_url = _redis_url_with_db(settings.docket.url, db)
+
+    # patch settings for this worker process
+    settings.docket.url = new_url
+    os.environ["DOCKET_URL"] = new_url
+
+    # clear any cached clients (they have old URL)
+    clear_client_cache()
+
+    # try to flush db before tests - if redis unavailable, skip silently
+    try:
+        client = sync_redis_lib.Redis.from_url(new_url, socket_connect_timeout=1)
+        client.flushdb()
+        client.close()
+    except sync_redis_lib.ConnectionError:
+        # redis not available - tests that need it will fail with specific errors
+        yield
+        return
+
+    yield
+
+    # flush db after tests and clear cached clients
+    clear_client_cache()
+    try:
+        client = sync_redis_lib.Redis.from_url(new_url, socket_connect_timeout=1)
+        client.flushdb()
+        client.close()
+    except sync_redis_lib.ConnectionError:
+        pass  # redis went away during tests, nothing to clean up

backend/tests/test_moderation.py

···
 async def test_get_active_copyright_labels_success() -> None:
     """test successful call to labeler returns active URIs."""
     uris = [
-        "at://did:plc:test/fm.plyr.track/1",
-        "at://did:plc:test/fm.plyr.track/2",
-        "at://did:plc:test/fm.plyr.track/3",
+        "at://did:plc:success/fm.plyr.track/1",
+        "at://did:plc:success/fm.plyr.track/2",
+        "at://did:plc:success/fm.plyr.track/3",
     ]
 
     mock_response = Mock()
     mock_response.json.return_value = {
-        "active_uris": ["at://did:plc:test/fm.plyr.track/1"]  # only one is active
+        "active_uris": [uris[0]]  # only first is active
     }
     mock_response.raise_for_status.return_value = None
 
-    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
-        mock_post.return_value = mock_response
+    with patch("backend._internal.moderation.settings") as mock_settings:
+        mock_settings.moderation.enabled = True
+        mock_settings.moderation.auth_token = "test-token"
+        mock_settings.moderation.labeler_url = "https://test.example.com"
+        mock_settings.moderation.timeout_seconds = 30
+        mock_settings.moderation.label_cache_prefix = "test:label:"
+        mock_settings.moderation.label_cache_ttl_seconds = 300
 
-        with patch("backend._internal.moderation.settings") as mock_settings:
-            mock_settings.moderation.enabled = True
-            mock_settings.moderation.auth_token = "test-token"
-            mock_settings.moderation.labeler_url = "https://labeler.example.com"
-            mock_settings.moderation.timeout_seconds = 10
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            mock_post.return_value = mock_response
 
             result = await get_active_copyright_labels(uris)
 
-    # only the active URI should be in the result
-    assert result == {"at://did:plc:test/fm.plyr.track/1"}
+        # only the active URI should be in the result
+        assert result == {uris[0]}
 
-    # verify correct endpoint was called
-    call_kwargs = mock_post.call_args
-    assert "/admin/active-labels" in str(call_kwargs)
-    assert call_kwargs.kwargs["json"] == {"uris": uris}
+        # verify correct endpoint was called
+        call_kwargs = mock_post.call_args
+        assert "/admin/active-labels" in str(call_kwargs)
+        assert call_kwargs.kwargs["json"] == {"uris": uris}
 
 
 async def test_get_active_copyright_labels_service_error() -> None:
     """test that service errors return all URIs as active (fail closed)."""
-    uris = ["at://did:plc:test/fm.plyr.track/1", "at://did:plc:test/fm.plyr.track/2"]
+    uris = [
+        "at://did:plc:error/fm.plyr.track/1",
+        "at://did:plc:error/fm.plyr.track/2",
+    ]
 
-    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
-        mock_post.side_effect = httpx.ConnectError("connection failed")
+    with patch("backend._internal.moderation.settings") as mock_settings:
+        mock_settings.moderation.enabled = True
+        mock_settings.moderation.auth_token = "test-token"
+        mock_settings.moderation.labeler_url = "https://test.example.com"
+        mock_settings.moderation.timeout_seconds = 30
+        mock_settings.moderation.label_cache_prefix = "test:label:"
+        mock_settings.moderation.label_cache_ttl_seconds = 300
 
-        with patch("backend._internal.moderation.settings") as mock_settings:
-            mock_settings.moderation.enabled = True
-            mock_settings.moderation.auth_token = "test-token"
-            mock_settings.moderation.labeler_url = "https://labeler.example.com"
-            mock_settings.moderation.timeout_seconds = 10
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            mock_post.side_effect = httpx.ConnectError("connection failed")
 
             result = await get_active_copyright_labels(uris)
 
-    # should fail closed - all URIs treated as active
-    assert result == set(uris)
+        # should fail closed - all URIs treated as active
+        assert result == set(uris)
+
+
+# tests for active labels caching (using real redis from test docker-compose)
+
+
+async def test_get_active_copyright_labels_caching() -> None:
+    """test that repeated calls use cache instead of calling service."""
+    uris = [
+        "at://did:plc:caching/fm.plyr.track/1",
+        "at://did:plc:caching/fm.plyr.track/2",
+    ]
+
+    mock_response = Mock()
+    mock_response.json.return_value = {
+        "active_uris": [uris[0]]  # only first is active
+    }
+    mock_response.raise_for_status.return_value = None
+
+    with patch("backend._internal.moderation.settings") as mock_settings:
+        mock_settings.moderation.enabled = True
+        mock_settings.moderation.auth_token = "test-token"
+        mock_settings.moderation.labeler_url = "https://test.example.com"
+        mock_settings.moderation.timeout_seconds = 30
+        mock_settings.moderation.label_cache_prefix = "test:label:"
+        mock_settings.moderation.label_cache_ttl_seconds = 300
+
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            mock_post.return_value = mock_response
+
+            # first call - should hit service
+            result1 = await get_active_copyright_labels(uris)
+            assert result1 == {uris[0]}
+            assert mock_post.call_count == 1
+
+            # second call with same URIs - should use cache, not call service
+            result2 = await get_active_copyright_labels(uris)
+            assert result2 == {uris[0]}
+            assert mock_post.call_count == 1  # still 1, no new call
+
+
+async def test_get_active_copyright_labels_partial_cache() -> None:
+    """test that cache hits are combined with service calls for new URIs."""
+    uris_batch1 = ["at://did:plc:partial/fm.plyr.track/1"]
+    uris_batch2 = [
+        "at://did:plc:partial/fm.plyr.track/1",  # cached
+        "at://did:plc:partial/fm.plyr.track/2",  # new
+    ]
+
+    mock_response1 = Mock()
+    mock_response1.json.return_value = {
+        "active_uris": ["at://did:plc:partial/fm.plyr.track/1"]
+    }
+    mock_response1.raise_for_status.return_value = None
+
+    mock_response2 = Mock()
+    mock_response2.json.return_value = {
+        "active_uris": []  # uri/2 is not active
+    }
+    mock_response2.raise_for_status.return_value = None
+
+    with patch("backend._internal.moderation.settings") as mock_settings:
+        mock_settings.moderation.enabled = True
+        mock_settings.moderation.auth_token = "test-token"
+        mock_settings.moderation.labeler_url = "https://test.example.com"
+        mock_settings.moderation.timeout_seconds = 30
+        mock_settings.moderation.label_cache_prefix = "test:label:"
+        mock_settings.moderation.label_cache_ttl_seconds = 300
+
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            mock_post.side_effect = [mock_response1, mock_response2]
+
+            # first call - cache uri/1 as active
+            result1 = await get_active_copyright_labels(uris_batch1)
+            assert result1 == {"at://did:plc:partial/fm.plyr.track/1"}
+            assert mock_post.call_count == 1
+
+            # second call - uri/1 from cache, only uri/2 fetched
+            result2 = await get_active_copyright_labels(uris_batch2)
+            # uri/1 is active (from cache), uri/2 is not active (from service)
+            assert result2 == {"at://did:plc:partial/fm.plyr.track/1"}
+            assert mock_post.call_count == 2
+
+            # verify second call only requested uri/2
+            second_call_args = mock_post.call_args_list[1]
+            assert second_call_args.kwargs["json"] == {
+                "uris": ["at://did:plc:partial/fm.plyr.track/2"]
+            }
+
+
+async def test_get_active_copyright_labels_cache_invalidation() -> None:
+    """test that invalidate_label_cache clears specific entry."""
+    from backend._internal.moderation import invalidate_label_cache
+
+    uris = ["at://did:plc:invalidate/fm.plyr.track/1"]
+
+    mock_response = Mock()
+    mock_response.json.return_value = {
+        "active_uris": ["at://did:plc:invalidate/fm.plyr.track/1"]
+    }
+    mock_response.raise_for_status.return_value = None
+
+    with patch("backend._internal.moderation.settings") as mock_settings:
+        mock_settings.moderation.enabled = True
+        mock_settings.moderation.auth_token = "test-token"
+        mock_settings.moderation.labeler_url = "https://test.example.com"
+        mock_settings.moderation.timeout_seconds = 30
+        mock_settings.moderation.label_cache_prefix = "test:label:"
+        mock_settings.moderation.label_cache_ttl_seconds = 300
+
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            mock_post.return_value = mock_response
+
+            # first call - populate cache
+            result1 = await get_active_copyright_labels(uris)
+            assert result1 == {"at://did:plc:invalidate/fm.plyr.track/1"}
+            assert mock_post.call_count == 1
+
+            # invalidate the cache entry
+            await invalidate_label_cache("at://did:plc:invalidate/fm.plyr.track/1")
+
+            # next call - should hit service again since cache was invalidated
+            result2 = await get_active_copyright_labels(uris)
+            assert result2 == {"at://did:plc:invalidate/fm.plyr.track/1"}
+            assert mock_post.call_count == 2
+
+
+async def test_service_error_does_not_cache() -> None:
+    """test that service errors don't pollute the cache."""
+    # use unique URIs for this test to avoid cache pollution from other tests
+    uris = ["at://did:plc:errnocache/fm.plyr.track/1"]
+
+    mock_success_response = Mock()
+    mock_success_response.json.return_value = {"active_uris": []}
+    mock_success_response.raise_for_status.return_value = None
+
+    with patch("backend._internal.moderation.settings") as mock_settings:
+        mock_settings.moderation.enabled = True
+        mock_settings.moderation.auth_token = "test-token"
+        mock_settings.moderation.labeler_url = "https://test.example.com"
+        mock_settings.moderation.timeout_seconds = 30
+        mock_settings.moderation.label_cache_prefix = "test:label:"
+        mock_settings.moderation.label_cache_ttl_seconds = 300
+
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            # first call fails
+            mock_post.side_effect = httpx.ConnectError("connection failed")
+
+            # first call - fails, returns all URIs as active (fail closed)
+            result1 = await get_active_copyright_labels(uris)
+            assert result1 == set(uris)
+            assert mock_post.call_count == 1
+
+            # reset mock to succeed
+            mock_post.side_effect = None
+            mock_post.return_value = mock_success_response
+
+            # second call - should try service again (error wasn't cached)
+            result2 = await get_active_copyright_labels(uris)
+            assert result2 == set()  # now correctly shows not active
+            assert mock_post.call_count == 2

backend/uv.lock

···
     { name = "python-dotenv" },
     { name = "python-jose", extra = ["cryptography"] },
     { name = "python-multipart" },
+    { name = "redis" },
     { name = "slowapi" },
     { name = "sqlalchemy" },
     { name = "uvicorn", extra = ["standard"] },
···
     { name = "python-dotenv", specifier = ">=1.1.0" },
     { name = "python-jose", extras = ["cryptography"], specifier = ">=3.3.0" },
     { name = "python-multipart", specifier = ">=0.0.20" },
+    { name = "redis", specifier = ">=7.1.0" },
     { name = "slowapi", git = "https://github.com/zzstoatzz/slowapi.git?rev=fix-deprecation" },
     { name = "sqlalchemy", specifier = ">=2.0.36" },
     { name = "uvicorn", extras = ["standard"], specifier = ">=0.34.0" },

docs/testing/README.md

···
 - some ORMs behave differently in uncommitted transactions
 
 delete-by-timestamp gives us real commits while staying fast.
+
+## redis isolation for parallel tests
+
+tests that use redis (caching, background tasks) need isolation between xdist workers. without isolation, one worker's cache entries pollute another's tests.
+
+### how it works
+
+each xdist worker uses a different redis database number:
+
+| worker | redis db |
+|--------|----------|
+| master/gw0 | 1 |
+| gw1 | 2 |
+| gw2 | 3 |
+| ... | ... |
+
+db 0 is reserved for local development.
+
+### the redis_database fixture
+
+```python
[e-mail](scope="session", autouse=True)
+def redis_database(worker_id: str) -> Generator[None, None, None]:
+    """use isolated redis databases for parallel test execution."""
+    db = _redis_db_for_worker(worker_id)
+    new_url = _redis_url_with_db(settings.docket.url, db)
+
+    # patch settings for this worker process
+    settings.docket.url = new_url
+    os.environ["DOCKET_URL"] = new_url
+    clear_client_cache()
+
+    # flush db before tests
+    sync_redis = redis.Redis.from_url(new_url)
+    sync_redis.flushdb()
+    sync_redis.close()
+
+    yield
+
+    # flush after tests
+    ...
+```
+
+this fixture is `autouse=True` so it applies to all tests automatically.
+
+### common pitfall: unique URIs in cache tests
+
+even with per-worker database isolation, tests within the same worker share redis state. if multiple tests use the same cache keys, they can interfere with each other.
+
+**wrong**:
+```python
+async def test_caching_first():
+    uris = ["at://did:plc:test/fm.plyr.track/1"]  # generic URI
+    result = await get_active_copyright_labels(uris)
+    # caches the result
+
+async def test_caching_second():
+    uris = ["at://did:plc:test/fm.plyr.track/1"]  # same URI!
+    result = await get_active_copyright_labels(uris)
+    # gets cached value from first test - may fail unexpectedly
+```
+
+**right**:
+```python
+async def test_caching_first():
+    uris = ["at://did:plc:first/fm.plyr.track/1"]  # unique to this test
+    ...
+
+async def test_caching_second():
+    uris = ["at://did:plc:second/fm.plyr.track/1"]  # different URI
+    ...
+```
+
+use unique identifiers (test name, uuid, etc.) in cache keys to avoid cross-test pollution.