starfish-replica 3.0.0a5__tar.gz

starfish_replica-3.0.0a5/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: starfish-replica
+Version: 3.0.0a5
+Summary: Starfish replication extension (primary→replica sync, write modes, on-pull/scheduled triggers, push proxy) as a server plugin
+Requires-Python: >=3.11
+Requires-Dist: starfish-protocol
+Requires-Dist: starfish-server
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.23.1; extra == "dev"

starfish_replica-3.0.0a5/README.md

@@ -0,0 +1,58 @@
+# starfish-replica
+
+Replication extension for [Starfish](https://github.com/Drakkar-Software/starfish). Lets you run
+multiple Starfish servers that stay in sync: a **primary** holds the source of truth; **replicas**
+pull from it and serve reads locally.
+
+Shipped as a `ServerPlugin` — it owns its own config (the `remote` field is no longer part of the
+core `CollectionConfig`).
+
+## Install
+
+```bash
+pip install starfish-replica
+```
+
+## Usage
+
+```python
+from starfish_server import create_sync_router, SyncRouterOptions
+from starfish_replica import create_replica_server_plugin, RemoteConfig
+
+replica = create_replica_server_plugin(
+    store=store,
+    sync_config=config,
+    collections={
+        # keyed by root collection name
+        "posts": RemoteConfig(
+            url="https://primary.example.com/v1",
+            pullPath="/pull/posts/featured",
+            interval_ms=60_000,
+            headers={"Authorization": "Bearer <replica-token>"},
+            write_mode="pull_only",        # clients can't push to this replica
+            sync_triggers=["scheduled"],   # or ["on_pull"]
+        ),
+    },
+)
+
+router = create_sync_router(SyncRouterOptions(
+    store=store,
+    config=config,
+    role_resolver=role_resolver,
+    plugins=[replica.plugin],  # + other plugins
+))
+
+await replica.manager.start()  # begin scheduled / initial syncs
+# on shutdown: register replica.plugin in GracefulShutdownOptions(plugins=[...])
+```
+
+## Write modes
+
+| Mode | Client reads | Client writes | Syncs from primary |
+| --- | --- | --- | --- |
+| `pull_only` | ✓ | rejected (405) | ✓ replace |
+| `push_through` | ✓ | forwarded to primary | ✓ replace |
+| `bidirectional` | ✓ | stored locally | ✓ merge (remote-wins) |
+| `push_only` | rejected (405) | stored locally | — |
+
+`push_through` and `bidirectional` require `push_path`.

starfish_replica-3.0.0a5/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starfish-replica"
+version = "3.0.0a5"
+description = "Starfish replication extension (primary→replica sync, write modes, on-pull/scheduled triggers, push proxy) as a server plugin"
+requires-python = ">=3.11"
+dependencies = [
+  "starfish-protocol",
+  "starfish-server",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "respx>=0.23.1",
+]
+
+[tool.uv.sources]
+starfish-protocol = { path = "../protocol", editable = true }
+starfish-server = { path = "../server", editable = true }
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

starfish_replica-3.0.0a5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starfish_replica-3.0.0a5/starfish_replica/__init__.py

@@ -0,0 +1,30 @@
+"""``starfish-replica`` — primary→replica replication extension.
+
+Public surface: :class:`ReplicaManager` (the sync engine), the replica config
+types (:class:`RemoteConfig`/:class:`WriteMode`/:class:`SyncTrigger`/
+:class:`RemoteCollection`), :func:`validate_replica_config`, and
+:func:`create_replica_server_plugin` — a ``ServerPlugin`` whose
+``before_pull``/``intercept_push`` hooks enforce write modes and proxy
+push-through writes, and whose ``shutdown`` hook stops the sync timers.
+"""
+
+from starfish_replica.config import (
+    RemoteCollection,
+    RemoteConfig,
+    SyncTrigger,
+    WriteMode,
+)
+from starfish_replica.manager import ReplicaManager
+from starfish_replica.plugin import ReplicaServerPlugin, create_replica_server_plugin
+from starfish_replica.validate import validate_replica_config
+
+__all__ = [
+    "RemoteCollection",
+    "RemoteConfig",
+    "SyncTrigger",
+    "WriteMode",
+    "ReplicaManager",
+    "ReplicaServerPlugin",
+    "create_replica_server_plugin",
+    "validate_replica_config",
+]

starfish_replica-3.0.0a5/starfish_replica/config.py

@@ -0,0 +1,92 @@
+"""Replica configuration types. Owned by the replica plugin — apps pass a
+``{ collection_name: RemoteConfig }`` map to ``create_replica_server_plugin``.
+
+(Moved out of ``starfish-server``'s ``CollectionConfig`` so the core schema no
+longer knows about replication — mirrors how ``QueueConfig`` lives in
+``starfish-queuing``.)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class WriteMode(StrEnum):
+    """Controls how local client writes are handled on a replica collection."""
+
+    PULL_ONLY = "pull_only"
+    """Only the ReplicaManager writes locally; local client pushes are rejected (405)."""
+
+    PUSH_THROUGH = "push_through"
+    """Local client pushes are forwarded to the primary; the replica syncs back afterwards."""
+
+    BIDIRECTIONAL = "bidirectional"
+    """Local client pushes are stored locally and merged (remote-wins) with the primary on sync."""
+
+    PUSH_ONLY = "push_only"
+    """Local client pushes are stored locally; pull requests are rejected (405).
+    The replica does not sync from the primary — data is managed entirely locally."""
+
+
+class SyncTrigger(StrEnum):
+    """Events that trigger a sync from the primary."""
+
+    SCHEDULED = "scheduled"
+    """Sync on a fixed interval (``interval_ms``)."""
+
+    ON_PULL = "on_pull"
+    """Sync before serving each local ``GET /pull/…`` request (lazy / always-fresh)."""
+
+
+class RemoteConfig(BaseModel):
+    """Declares that a collection should be replicated from a remote (primary) starfish server."""
+
+    model_config = {"populate_by_name": True}
+
+    url: str
+    """Base URL of the primary starfish server, e.g. ``https://primary.example.com/v1``."""
+
+    pull_path: str = Field(alias="pullPath")
+    """Pull endpoint path on the primary, e.g. ``/pull/posts/featured``.
+    Must be a static path — no template variables."""
+
+    push_path: str | None = Field(default=None, alias="pushPath")
+    """Push endpoint path on the primary. Required for ``push_through`` and ``bidirectional`` write modes."""
+
+    interval_ms: int = Field(default=60_000, gt=0, alias="intervalMs")
+    """Sync interval in milliseconds (used by the ``scheduled`` trigger). Defaults to 60 000 ms."""
+
+    headers: dict[str, str] = Field(default_factory=dict)
+    """Static HTTP headers sent to the primary on every request (e.g. ``Authorization: Bearer <token>``).
+    These credentials must satisfy the primary collection's ``readRoles`` (and ``writeRoles`` for write-through)."""
+
+    write_mode: WriteMode = Field(default=WriteMode.PULL_ONLY, alias="writeMode")
+    """How local client writes are handled. Defaults to ``pull_only``."""
+
+    sync_triggers: list[SyncTrigger] = Field(
+        default_factory=lambda: [SyncTrigger.SCHEDULED],
+        alias="syncTriggers",
+    )
+    """Which events trigger a sync from the primary. Defaults to ``[scheduled]``."""
+
+    on_pull_min_interval_ms: int | None = Field(default=None, gt=0, alias="onPullMinIntervalMs")
+    """Minimum time in milliseconds between two consecutive syncs triggered by ``on_pull``.
+
+    When a client pulls and this cooldown has not elapsed since the last sync, the replica
+    skips the round-trip to the primary and serves the locally cached data instead.
+
+    ``None`` (default) means every ``on_pull`` request always syncs from the primary.
+    Only relevant when ``on_pull`` is listed in ``sync_triggers``."""
+
+
+@dataclass
+class RemoteCollection:
+    """A collection to replicate: the manager needs its name (route key), its
+    static storage path (document key), and its :class:`RemoteConfig`."""
+
+    name: str
+    storage_path: str
+    remote: RemoteConfig

starfish_replica-3.0.0a5/starfish_replica/manager.py

@@ -0,0 +1,243 @@
+"""Replica manager — scheduled and on-demand sync from a remote primary starfish."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from starfish_protocol.merge import deep_merge
+from starfish_server.protocol.push import push
+from starfish_server.router.helpers import deep_sanitize
+from starfish_server.protocol.types import PushSuccess
+from starfish_server.storage.base import AbstractObjectStore
+
+from starfish_replica.config import RemoteCollection, RemoteConfig, SyncTrigger, WriteMode
+
+logger = logging.getLogger(__name__)
+
+
+class ReplicaManager:
+    """Manages replication from remote (primary) starfish servers.
+
+    For each :class:`RemoteCollection`, syncs data from the primary to local
+    storage. Write mode, sync triggers, and interval are driven by config.
+    """
+
+    def __init__(
+        self,
+        store: AbstractObjectStore,
+        collections: list[RemoteCollection],
+        *,
+        client: httpx.AsyncClient | None = None,
+        on_error: Callable[[str, Exception], None] | None = None,
+    ) -> None:
+        self._store = store
+        self._remote_cols = list(collections)
+        self._owned_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=30.0)
+        self._on_error = on_error or (
+            lambda name, exc: logger.error("[ReplicaManager] %s: %s", name, exc)
+        )
+        self._last_hash: dict[str, str] = {}
+        self._last_sync_at: dict[str, float] = {}
+        self._tasks: list[asyncio.Task[None]] = []
+
+    def remote_for(self, name: str) -> RemoteConfig | None:
+        """The :class:`RemoteConfig` for a collection name, or ``None`` if not replicated."""
+        col = self._find(name)
+        return col.remote if col else None
+
+    async def start(self) -> None:
+        """Start background sync tasks for all remote collections."""
+        for col in self._remote_cols:
+            remote = col.remote
+
+            if SyncTrigger.SCHEDULED in remote.sync_triggers:
+                task = asyncio.create_task(self._run_loop(col))
+                self._tasks.append(task)
+            else:
+                asyncio.create_task(self._sync_safe(col))
+
+    async def stop(self) -> None:
+        """Cancel all background tasks and close the HTTP client (if owned)."""
+        for task in self._tasks:
+            task.cancel()
+        if self._tasks:
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+        self._tasks.clear()
+        if self._owned_client:
+            await self._client.aclose()
+
+    async def on_pull(self, collection_name: str) -> None:
+        """Called by the pull route when ``on_pull`` is listed in ``sync_triggers``.
+
+        Awaited before the local store is read, ensuring the response is fresh.
+        If ``on_pull_min_interval_ms`` is configured and the last sync occurred within
+        that window, the primary is not contacted and cached local data is served instead.
+        """
+        col = self._find(collection_name)
+        if col is None:
+            return
+
+        min_interval_ms = col.remote.on_pull_min_interval_ms
+        if min_interval_ms is not None:
+            last = self._last_sync_at.get(collection_name)
+            if last is not None and (time.monotonic() - last) * 1000 < min_interval_ms:
+                return  # within cooldown — serve cached local data
+
+        await self._sync_safe(col)
+
+    async def sync_now(self, name: str) -> None:
+        """Trigger an immediate sync for a single collection by name."""
+        col = self._find(name)
+        if col is None:
+            raise ValueError(f"[ReplicaManager] Unknown remote collection: {name!r}")
+        await self._do_sync(col)
+
+    async def sync_all(self) -> None:
+        """Trigger an immediate sync for all remote collections in parallel."""
+        await asyncio.gather(*(self._sync_safe(col) for col in self._remote_cols))
+
+    async def proxy_push(self, name: str, raw_body: bytes | str) -> tuple[int, Any]:
+        """Forward a client push to the primary (write_mode ``push_through``).
+
+        Returns ``(status, body)`` to relay to the client. On success, triggers
+        a background sync so the local replica catches up. Framework-neutral —
+        the caller (replica plugin) turns this into an HTTP response.
+        """
+        col = self._find(name)
+        if col is None:
+            return 404, {"error": f"Unknown remote collection: {name!r}"}
+        remote = col.remote
+        primary_url = f"{remote.url.rstrip('/')}{remote.push_path}"
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            **remote.headers,
+        }
+
+        try:
+            resp = await self._client.post(primary_url, content=raw_body, headers=headers)
+        except httpx.HTTPError as exc:
+            logger.error("Failed to reach primary for %r: %s", name, exc)
+            return 502, {"error": "Failed to reach primary"}
+
+        if resp.status_code == 409:
+            return 409, {"error": "hash_mismatch"}
+        if not resp.is_success:
+            return resp.status_code, {"error": f"Primary returned {resp.status_code}"}
+
+        body = resp.json()
+
+        # Validate the primary's response shape before relaying it to our client.
+        # A successful push returns ``{ hash, timestamp }``; refuse to forward an
+        # arbitrary/garbage body a compromised or misbehaving primary might send.
+        if not isinstance(body, dict) or not isinstance(body.get("hash"), str):
+            logger.error("Primary returned an unexpected push response shape for %r", name)
+            return 502, {"error": "Primary returned an unexpected response"}
+
+        # Trigger sync in background (don't await)
+        task = asyncio.create_task(self.sync_now(name))
+        task.add_done_callback(
+            lambda t: logger.error("replica sync_now failed for %r: %s", name, t.exception())
+            if not t.cancelled() and t.exception() is not None
+            else None
+        )
+
+        return resp.status_code, body
+
+    def _find(self, name: str) -> RemoteCollection | None:
+        return next((c for c in self._remote_cols if c.name == name), None)
+
+    async def _run_loop(self, col: RemoteCollection) -> None:
+        interval = col.remote.interval_ms / 1000
+        while True:
+            await self._sync_safe(col)
+            await asyncio.sleep(interval)
+
+    async def _sync_safe(self, col: RemoteCollection) -> None:
+        try:
+            await self._do_sync(col)
+        except Exception as exc:  # noqa: BLE001
+            self._on_error(col.name, exc)
+
+    async def _do_sync(self, col: RemoteCollection) -> None:
+        remote = col.remote
+
+        if remote.write_mode == WriteMode.PUSH_ONLY:
+            return
+
+        document_key = col.storage_path
+
+        primary_url = f"{remote.url.rstrip('/')}{remote.pull_path}"
+        resp = await self._client.get(
+            primary_url,
+            headers={"Accept": "application/json", **remote.headers},
+        )
+        resp.raise_for_status()
+        pulled: dict[str, Any] = resp.json()
+
+        primary_hash: str = pulled.get("hash", "")
+        primary_data: dict[str, Any] = pulled.get("data", {})
+
+        if not primary_hash:
+            return
+
+        if self._last_hash.get(col.name) == primary_hash:
+            return
+
+        raw_local = await self._store.get_string(document_key)
+        current_local_hash: str = ""
+        current_local_data: dict[str, Any] = {}
+        if raw_local:
+            try:
+                local_doc = json.loads(raw_local)
+                current_local_hash = local_doc.get("hash", "")
+                current_local_data = local_doc.get("data", {})
+            except json.JSONDecodeError as exc:
+                logger.error(
+                    "[ReplicaManager] Corrupt local document at %r — treating as empty: %s",
+                    document_key, exc,
+                )
+                # current_local_hash stays "" — push with baseHash="" will overwrite
+
+        if current_local_hash == primary_hash:
+            self._last_hash[col.name] = primary_hash
+            return
+
+        if remote.write_mode == WriteMode.BIDIRECTIONAL and current_local_data:
+            data_to_write = deep_merge(current_local_data, primary_data)
+        else:
+            data_to_write = primary_data
+
+        # Strip prototype-pollution keys before writing primary data into the
+        # local store. The bidirectional merge drops them via deep_merge, but the
+        # pull-only / push-through path writes the primary's ``data`` verbatim and
+        # must not trust it — a compromised primary could otherwise plant a
+        # ``__proto__`` / ``__class__`` payload.
+        sanitized = deep_sanitize(data_to_write)
+
+        # Use current_local_hash directly ("" works for both "no document" and
+        # "corrupt document"): push() treats base_hash="" the same as no hash when
+        # the stored current_hash is also "". Must NOT coerce "" → None — push()
+        # rejects base_hash=None when a (corrupt) doc is present, which would leave
+        # a corrupt local doc permanently unrecoverable (sync would raise
+        # "Concurrent write" forever). A valid local doc still yields its real
+        # hash, so genuine concurrent-write detection is preserved.
+        base_hash = current_local_hash
+        result = await push(self._store, document_key, sanitized, base_hash)
+
+        if not isinstance(result, PushSuccess):
+            raise RuntimeError(
+                f"[ReplicaManager] Concurrent write on {col.name!r} — will retry"
+            )
+
+        self._last_hash[col.name] = result.hash
+        self._last_sync_at[col.name] = time.monotonic()
+        logger.debug("[ReplicaManager] Synced %r (hash=%s)", col.name, result.hash)

starfish_replica-3.0.0a5/starfish_replica/plugin.py

@@ -0,0 +1,111 @@
+"""Server plugin for the replication extension (Python mirror).
+
+Implements the route hooks from the ``ServerPlugin`` contract:
+- ``before_pull``: rejects pulls on write-only (``push_only``) collections, and
+  triggers a sync from the primary when the ``on_pull`` trigger is configured.
+- ``intercept_push``: rejects pushes on read-only (``pull_only``) collections,
+  and proxies the push to the primary when the write mode is ``push_through``.
+- ``shutdown``: stops the manager's background tasks.
+
+Like ``starfish-queuing``, this plugin owns its config: apps pass a
+``{ collection_name: RemoteConfig }`` map; the field is no longer part of the
+core ``CollectionConfig``. The factory validates the config at construction and
+raises on conflict.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+import httpx
+
+from starfish_protocol.plugins import (
+    PullHookContext,
+    PullHookResult,
+    PushHookContext,
+    PushHookResult,
+    ServerPlugin,
+)
+from starfish_server.config.schema import SyncConfig
+from starfish_server.storage.base import AbstractObjectStore
+
+from starfish_replica.config import RemoteCollection, RemoteConfig, SyncTrigger, WriteMode
+from starfish_replica.manager import ReplicaManager
+from starfish_replica.validate import validate_replica_config
+
+
+@dataclass
+class ReplicaServerPlugin:
+    """Bundle returned by :func:`create_replica_server_plugin`.
+
+    Pass ``.plugin`` to ``SyncRouterOptions(plugins=[...])`` and call
+    ``await .manager.start()`` to begin scheduled/initial syncs.
+    """
+
+    plugin: ServerPlugin
+    manager: ReplicaManager
+
+
+def create_replica_server_plugin(
+    *,
+    store: AbstractObjectStore,
+    sync_config: SyncConfig,
+    collections: Mapping[str, RemoteConfig],
+    client: httpx.AsyncClient | None = None,
+    on_error: Callable[[str, Exception], None] | None = None,
+) -> ReplicaServerPlugin:
+    """Build a replica :class:`ServerPlugin` and its :class:`ReplicaManager`.
+
+    Validates the config (cross-referencing *collections* against
+    *sync_config*) and raises ``ValueError`` on conflict.
+    """
+    errors = validate_replica_config(sync_config, dict(collections))
+    if errors:
+        joined = "\n- ".join(errors)
+        raise ValueError(f"[starfish-replica] invalid configuration:\n- {joined}")
+
+    by_name = {c.name: c for c in sync_config.collections}
+    remote_cols = [
+        RemoteCollection(name=name, storage_path=by_name[name].storage_path, remote=remote)
+        for name, remote in collections.items()
+    ]
+
+    manager = ReplicaManager(store, remote_cols, client=client, on_error=on_error)
+
+    async def _before_pull(ctx: PullHookContext) -> PullHookResult:
+        remote = manager.remote_for(ctx.collection)
+        if remote is None:
+            return PullHookResult(action="proceed")
+        if remote.write_mode == WriteMode.PUSH_ONLY:
+            return PullHookResult(
+                action="reject", status=405, error="This collection is write-only on this server"
+            )
+        if SyncTrigger.ON_PULL in remote.sync_triggers:
+            await manager.on_pull(ctx.collection)
+        return PullHookResult(action="proceed")
+
+    async def _intercept_push(ctx: PushHookContext) -> PushHookResult:
+        remote = manager.remote_for(ctx.collection)
+        if remote is None:
+            return PushHookResult(action="proceed")
+        if remote.write_mode == WriteMode.PULL_ONLY:
+            return PushHookResult(
+                action="reject", status=405, error="This collection is read-only on this server"
+            )
+        if remote.write_mode == WriteMode.PUSH_THROUGH:
+            status, body = await manager.proxy_push(ctx.collection, ctx.raw_body)
+            return PushHookResult(action="respond", status=status, body=body)
+        # bidirectional / push_only → store locally, then sync reconciles
+        return PushHookResult(action="proceed")
+
+    async def _shutdown() -> None:
+        await manager.stop()
+
+    plugin = ServerPlugin(
+        name="starfish-replica",
+        before_pull=_before_pull,
+        intercept_push=_intercept_push,
+        shutdown=_shutdown,
+    )
+    return ReplicaServerPlugin(plugin=plugin, manager=manager)

starfish_replica-3.0.0a5/starfish_replica/validate.py

@@ -0,0 +1,66 @@
+"""Replica config validation.
+
+Cross-references the ``remotes`` map (collection name → :class:`RemoteConfig`)
+against the server's :class:`SyncConfig` collections. These rules were
+previously inline in ``starfish-server``'s config validator; they moved here
+when the ``remote`` field left the core ``CollectionConfig``.
+"""
+
+from __future__ import annotations
+
+import re
+
+from starfish_server.config.schema import CollectionConfig, SyncConfig
+from starfish_server.constants import ENCRYPTION_DELEGATED
+
+from starfish_replica.config import RemoteConfig, WriteMode
+
+MIME_JSON = "application/json"
+
+
+def _is_binary_collection(allowed_mime_types: list[str]) -> bool:
+    return MIME_JSON not in [m.lower() for m in allowed_mime_types]
+
+
+def validate_replica_config(
+    config: SyncConfig,
+    remotes: dict[str, RemoteConfig],
+) -> list[str]:
+    """Validate the replica configuration. Returns error messages (empty = valid)."""
+    errors: list[str] = []
+    by_name: dict[str, CollectionConfig] = {c.name: c for c in config.collections}
+
+    for name, remote in remotes.items():
+        col = by_name.get(name)
+        if col is None:
+            errors.append(
+                f'Collection "{name}": remote replication configured for an unknown root collection'
+            )
+            continue
+
+        if col.append_only:
+            errors.append(f'Collection "{name}": appendOnly cannot be used with remote replication')
+        if _is_binary_collection(col.allowed_mime_types):
+            errors.append(f'Collection "{name}": binary collections cannot have remote replication')
+        if re.search(r"\{[^}]+\}", col.storage_path):
+            errors.append(
+                f'Collection "{name}": remote collections must have a static storagePath '
+                f'with no template variables (found "{col.storage_path}")'
+            )
+        if col.push_only:
+            errors.append(f'Collection "{name}": remote collections cannot be pushOnly')
+        if col.bundle:
+            errors.append(f'Collection "{name}": remote collections cannot be part of a bundle')
+        if col.encryption == ENCRYPTION_DELEGATED:
+            errors.append(
+                f'Collection "{name}": remote collections cannot use "{col.encryption}" encryption '
+                f'(server cannot replicate opaque client-encrypted blobs)'
+            )
+        if remote.write_mode in (WriteMode.PUSH_THROUGH, WriteMode.BIDIRECTIONAL):
+            if not remote.push_path:
+                errors.append(
+                    f'Collection "{name}": write_mode "{remote.write_mode.value}" '
+                    f'requires remote.push_path to be set'
+                )
+
+    return errors

starfish_replica-3.0.0a5/starfish_replica.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: starfish-replica
+Version: 3.0.0a5
+Summary: Starfish replication extension (primary→replica sync, write modes, on-pull/scheduled triggers, push proxy) as a server plugin
+Requires-Python: >=3.11
+Requires-Dist: starfish-protocol
+Requires-Dist: starfish-server
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.23.1; extra == "dev"

starfish_replica-3.0.0a5/starfish_replica.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+starfish_replica/__init__.py
+starfish_replica/config.py
+starfish_replica/manager.py
+starfish_replica/plugin.py
+starfish_replica/validate.py
+starfish_replica.egg-info/PKG-INFO
+starfish_replica.egg-info/SOURCES.txt
+starfish_replica.egg-info/dependency_links.txt
+starfish_replica.egg-info/requires.txt
+starfish_replica.egg-info/top_level.txt
+tests/test_config_validation.py
+tests/test_manager.py
+tests/test_plugin.py

starfish_replica-3.0.0a5/starfish_replica.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

starfish_replica-3.0.0a5/starfish_replica.egg-info/requires.txt

@@ -0,0 +1,8 @@
+starfish-protocol
+starfish-server
+httpx>=0.27
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+respx>=0.23.1

starfish_replica-3.0.0a5/starfish_replica.egg-info/top_level.txt

@@ -0,0 +1 @@
+starfish_replica

starfish_replica-3.0.0a5/tests/test_config_validation.py

@@ -0,0 +1,113 @@
+"""Tests for replica config validation (validate_replica_config)."""
+
+
+from starfish_server.config.schema import CollectionConfig, SyncConfig
+
+from starfish_replica.config import RemoteConfig, WriteMode
+from starfish_replica.validate import validate_replica_config
+
+
+def _col(**kwargs) -> CollectionConfig:
+    """Build a minimal collection config, overriding with kwargs."""
+    defaults = dict(
+        name="featured",
+        storagePath="posts/featured",
+        readRoles=["public"],
+        writeRoles=[],
+        encryption="none",
+        maxBodyBytes=65536,
+        pullOnly=True,
+    )
+    defaults.update(kwargs)
+    return CollectionConfig(**defaults)
+
+
+def _config(*cols: CollectionConfig) -> SyncConfig:
+    return SyncConfig(version=1, collections=list(cols))
+
+
+def _remote(**kwargs) -> RemoteConfig:
+    defaults = dict(
+        url="https://primary.example.com/v1",
+        pullPath="/pull/posts/featured",
+        intervalMs=30_000,
+    )
+    defaults.update(kwargs)
+    return RemoteConfig(**defaults)
+
+
+def test_valid_remote_collection_passes():
+    errors = validate_replica_config(_config(_col()), {"featured": _remote()})
+    assert errors == []
+
+
+def test_remote_for_unknown_collection_rejected():
+    errors = validate_replica_config(_config(_col()), {"ghost": _remote()})
+    assert any("unknown root collection" in e for e in errors)
+
+
+def test_remote_with_template_vars_rejected():
+    col = _col(storagePath="users/{identity}/data")
+    errors = validate_replica_config(_config(col), {"featured": _remote()})
+    assert any("template variables" in e for e in errors)
+
+
+def test_remote_push_only_rejected():
+    col = _col(pushOnly=True, pullOnly=None)
+    errors = validate_replica_config(_config(col), {"featured": _remote()})
+    assert any("pushOnly" in e for e in errors)
+
+
+def test_remote_in_bundle_rejected():
+    col = _col(storagePath="users/shared/data", bundle="my-bundle")
+    errors = validate_replica_config(_config(col), {"featured": _remote()})
+    assert any("bundle" in e for e in errors)
+
+
+def test_remote_delegated_encryption_rejected():
+    col = _col(encryption="delegated")
+    errors = validate_replica_config(_config(col), {"featured": _remote()})
+    assert any("delegated" in e for e in errors)
+
+
+def test_appendonly_remote_rejected():
+    col = _col(appendOnly=True)
+    errors = validate_replica_config(_config(col), {"featured": _remote()})
+    assert any("appendOnly cannot be used with remote replication" in e for e in errors)
+
+
+def test_binary_remote_rejected():
+    col = _col(allowedMimeTypes=["image/png"])
+    errors = validate_replica_config(_config(col), {"featured": _remote()})
+    assert any("binary collections cannot have remote replication" in e for e in errors)
+
+
+def test_push_through_without_push_path_rejected():
+    errors = validate_replica_config(
+        _config(_col()), {"featured": _remote(writeMode=WriteMode.PUSH_THROUGH)}
+    )
+    assert any("push_path" in e for e in errors)
+
+
+def test_bidirectional_without_push_path_rejected():
+    errors = validate_replica_config(
+        _config(_col()), {"featured": _remote(writeMode=WriteMode.BIDIRECTIONAL)}
+    )
+    assert any("push_path" in e for e in errors)
+
+
+def test_push_through_with_push_path_passes():
+    errors = validate_replica_config(
+        _config(_col(pullOnly=None)),
+        {"featured": _remote(pushPath="/push/posts/featured", writeMode=WriteMode.PUSH_THROUGH)},
+    )
+    assert errors == []
+
+
+def test_push_only_without_push_path_passes():
+    """PUSH_ONLY does not require push_path (writes are local-only, no proxying)."""
+    errors = validate_replica_config(
+        _config(_col(pullOnly=None)),
+        {"featured": _remote(writeMode=WriteMode.PUSH_ONLY)},
+    )
+    assert errors == []

starfish_replica-3.0.0a5/tests/test_manager.py

@@ -0,0 +1,356 @@
+"""Tests for ReplicaManager — sync logic and write modes."""
+
+
+import json
+import time
+
+import httpx
+import pytest
+import respx
+
+from starfish_protocol.merge import deep_merge
+from starfish_server.protocol.push import push
+from starfish_replica.config import RemoteCollection, RemoteConfig, SyncTrigger, WriteMode
+from starfish_replica.manager import ReplicaManager
+from tests.helpers import MemoryObjectStore
+
+
+def _make_col(
+    write_mode: WriteMode = WriteMode.PULL_ONLY,
+    sync_triggers: list[SyncTrigger] | None = None,
+    on_pull_min_interval_ms: int | None = None,
+) -> RemoteCollection:
+    return RemoteCollection(
+        name="featured",
+        storage_path="posts/featured",
+        remote=RemoteConfig(
+            url="https://primary.example.com/v1",
+            pull_path="/pull/posts/featured",
+            push_path="/push/posts/featured",
+            interval_ms=60_000,
+            write_mode=write_mode,
+            sync_triggers=sync_triggers or [SyncTrigger.SCHEDULED],
+            on_pull_min_interval_ms=on_pull_min_interval_ms,
+        ),
+    )
+
+
+def _primary_response(data: dict, hash_val: str = "abc123", timestamp: int = 1000) -> dict:
+    return {"data": data, "hash": hash_val, "timestamp": timestamp}
+
+
+
+def test_deep_merge_remote_wins_scalar():
+    result = deep_merge({"a": 1}, {"a": 2})
+    assert result == {"a": 2}
+
+
+def test_deep_merge_adds_remote_keys():
+    result = deep_merge({"a": 1}, {"b": 2})
+    assert result == {"a": 1, "b": 2}
+
+
+def test_deep_merge_recursive():
+    local = {"nested": {"x": 1, "y": 2}}
+    remote = {"nested": {"y": 99, "z": 3}}
+    result = deep_merge(local, remote)
+    assert result == {"nested": {"x": 1, "y": 99, "z": 3}}
+
+
+
+@respx.mock
+async def test_sync_writes_primary_data_to_store():
+    store = MemoryObjectStore()
+    col = _make_col()
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"title": "Hello"}, hash_val="hash1")
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.sync_now("featured")
+
+    raw = await store.get_string("posts/featured")
+    assert raw is not None
+    doc = json.loads(raw)
+    assert doc["data"] == {"title": "Hello"}
+
+
+@respx.mock
+async def test_sync_skips_write_when_hash_unchanged():
+    store = MemoryObjectStore()
+    col = _make_col()
+
+    # Pre-populate local store with same data
+    await push(store, "posts/featured", {"title": "Hello"}, None)
+    local_raw = await store.get_string("posts/featured")
+    local_hash = json.loads(local_raw)["hash"]
+
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"title": "Hello"}, hash_val=local_hash)
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        manager._last_hash["featured"] = local_hash  # simulate already synced
+        await manager.sync_now("featured")
+
+    # Store content should be unchanged
+    raw = await store.get_string("posts/featured")
+    assert json.loads(raw)["data"] == {"title": "Hello"}
+
+
+@respx.mock
+async def test_sync_empty_primary_is_noop():
+    store = MemoryObjectStore()
+    col = _make_col()
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json={"data": {}, "hash": "", "timestamp": 1000}
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.sync_now("featured")
+
+    assert await store.get_string("posts/featured") is None
+
+
+@respx.mock
+async def test_sync_bidirectional_merges_local_and_remote():
+    store = MemoryObjectStore()
+    col = _make_col(write_mode=WriteMode.BIDIRECTIONAL)
+
+    # Local has {a: 1, b: 2}; primary has {b: 99, c: 3}
+    await push(store, "posts/featured", {"a": 1, "b": 2}, None)
+
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"b": 99, "c": 3}, hash_val="newhash")
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.sync_now("featured")
+
+    raw = await store.get_string("posts/featured")
+    doc = json.loads(raw)
+    # remote wins on b; local a survives; remote adds c
+    assert doc["data"]["a"] == 1
+    assert doc["data"]["b"] == 99
+    assert doc["data"]["c"] == 3
+
+
+# Regression (parity with the TS test): a corrupt local replica document is
+# recovered by overwriting it on sync. `_do_sync` passes `base_hash =
+# current_local_hash` ("" for a corrupt/empty read); push() treats base_hash="" the
+# same as no hash when current_hash is also "". Before the fix the manager coerced
+# `current_local_hash if current_local_hash else None` → None, and push() rejects
+# base_hash=None when a (corrupt) doc is present, so sync_now raised "Concurrent
+# write" every cycle and the replica was permanently stuck.
+@respx.mock
+async def test_sync_recovers_from_a_corrupt_local_document():
+    store = MemoryObjectStore()
+    col = _make_col()  # pull_only → writes primary data verbatim
+    await store.put("posts/featured", "{ this is not valid json")  # left by a crash
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"x": 1}, hash_val="h1")
+    )
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.sync_now("featured")  # must not raise — the corrupt doc is recoverable
+    doc = json.loads(await store.get_string("posts/featured"))
+    assert doc["data"] == {"x": 1}
+
+
+@respx.mock
+async def test_sync_bidirectional_converges_on_repeat():
+    # local and remote diverge; the merged doc's hash differs from the primary's,
+    # so each sync re-pulls and re-merges. Pin that the loop is stable: the second
+    # cycle produces the same data (no drift, no key loss/growth).
+    store = MemoryObjectStore()
+    col = _make_col(write_mode=WriteMode.BIDIRECTIONAL)
+    await push(store, "posts/featured", {"local": "value", "shared": "old"}, None)
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"remote": "value", "shared": "new"}, hash_val="remote-hash")
+    )
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.sync_now("featured")
+        after1 = json.loads(await store.get_string("posts/featured"))["data"]
+        await manager.sync_now("featured")
+        after2 = json.loads(await store.get_string("posts/featured"))["data"]
+    assert after2 == after1  # idempotent: no drift across cycles
+    assert after1 == {"local": "value", "remote": "value", "shared": "new"}
+
+
+@respx.mock
+async def test_on_pull_triggers_sync():
+    store = MemoryObjectStore()
+    col = _make_col(sync_triggers=[SyncTrigger.ON_PULL])
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"title": "Fresh"}, hash_val="freshhash")
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.on_pull("featured")
+
+    raw = await store.get_string("posts/featured")
+    assert json.loads(raw)["data"] == {"title": "Fresh"}
+
+
+@respx.mock
+async def test_primary_error_calls_on_error_handler():
+    """Background sync paths (on_pull) catch primary errors via on_error
+    rather than propagating them to the caller."""
+    store = MemoryObjectStore()
+    col = _make_col(sync_triggers=[SyncTrigger.ON_PULL])
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(503)
+
+    errors: list[tuple[str, Exception]] = []
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client, on_error=lambda name, exc: errors.append((name, exc)))
+        await manager.on_pull("featured")  # should not raise
+
+    assert len(errors) == 1
+    assert errors[0][0] == "featured"
+
+
+async def test_sync_now_unknown_collection_raises():
+    store = MemoryObjectStore()
+    manager = ReplicaManager(store, [])
+    with pytest.raises(ValueError, match="Unknown remote collection"):
+        await manager.sync_now("nonexistent")
+
+
+
+@respx.mock
+async def test_on_pull_respects_cooldown():
+    """Second on_pull within cooldown window skips the primary."""
+    store = MemoryObjectStore()
+    col = _make_col(
+        sync_triggers=[SyncTrigger.ON_PULL],
+        on_pull_min_interval_ms=5_000,  # 5-second cooldown
+    )
+    route = respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"title": "Hello"}, hash_val="hash1")
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.on_pull("featured")   # first call — hits primary
+        await manager.on_pull("featured")   # within cooldown — should NOT hit primary
+
+    assert route.call_count == 1
+
+
+@respx.mock
+async def test_on_pull_syncs_after_cooldown_expires():
+    """on_pull syncs again once the cooldown has elapsed."""
+    store = MemoryObjectStore()
+    col = _make_col(
+        sync_triggers=[SyncTrigger.ON_PULL],
+        on_pull_min_interval_ms=1,  # 1 ms — expires almost immediately
+    )
+    route = respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"title": "Hello"}, hash_val="hash1")
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.on_pull("featured")   # first sync
+        # Force last_sync_at into the past so the cooldown is expired
+        manager._last_sync_at["featured"] = time.monotonic() - 1.0
+        await manager.on_pull("featured")   # cooldown elapsed — hits primary again
+
+    assert route.call_count == 2
+
+
+@respx.mock
+async def test_on_pull_no_cooldown_always_syncs():
+    """Without on_pull_min_interval_ms, every on_pull hits the primary."""
+    store = MemoryObjectStore()
+    col = _make_col(sync_triggers=[SyncTrigger.ON_PULL])  # no cooldown
+    route = respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"title": "Hello"}, hash_val="hash1")
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.on_pull("featured")
+        await manager.on_pull("featured")
+
+    assert route.call_count == 2
+
+
+
+@respx.mock
+async def test_push_only_skips_sync_from_primary():
+    """PUSH_ONLY collections never pull from the primary."""
+    store = MemoryObjectStore()
+    col = _make_col(write_mode=WriteMode.PUSH_ONLY)
+    route = respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response({"title": "Should not arrive"}, hash_val="x")
+    )
+
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.sync_now("featured")
+
+    # Primary should never have been contacted
+    assert route.call_count == 0
+    # Store should remain empty — no data pulled
+    assert await store.get_string("posts/featured") is None
+
+
+@respx.mock
+async def test_push_only_allows_local_writes():
+    """PUSH_ONLY collections accept local writes to the store."""
+    store = MemoryObjectStore()
+    _ = _make_col(write_mode=WriteMode.PUSH_ONLY)
+
+    # Simulate a local push (as the route handler would do)
+    from starfish_server.protocol.types import PushSuccess
+    result = await push(store, "posts/featured", {"submitted": True}, None)
+    assert isinstance(result, PushSuccess)
+
+    raw = await store.get_string("posts/featured")
+    assert json.loads(raw)["data"] == {"submitted": True}
+
+
+@respx.mock
+async def test_sync_strips_prototype_pollution_keys():
+    # A compromised primary must not be able to plant prototype-pollution keys
+    # into the local store via the pull-only (verbatim) write path.
+    store = MemoryObjectStore()
+    col = _make_col()
+    malicious = {"safe": 1, "__proto__": {"polluted": True}, "constructor": {"x": 1}}
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json=_primary_response(malicious, hash_val="hash1")
+    )
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        await manager.sync_now("featured")
+
+    raw = await store.get_string("posts/featured")
+    assert raw is not None
+    doc = json.loads(raw)
+    assert doc["data"]["safe"] == 1
+    assert "__proto__" not in doc["data"]
+    assert "constructor" not in doc["data"]
+
+
+@respx.mock
+async def test_proxy_push_rejects_unexpected_response_shape():
+    store = MemoryObjectStore()
+    col = _make_col(write_mode=WriteMode.PUSH_THROUGH)
+    # Primary replies 200 but with a body that is not a valid push result.
+    respx.post("https://primary.example.com/v1/push/posts/featured").respond(
+        200, json={"unexpected": True}
+    )
+    async with httpx.AsyncClient() as client:
+        manager = ReplicaManager(store, [col], client=client)
+        status, _body = await manager.proxy_push(
+            "featured", json.dumps({"data": {"x": 1}, "baseHash": None})
+        )
+    assert status == 502

starfish_replica-3.0.0a5/tests/test_plugin.py

@@ -0,0 +1,151 @@
+"""Tests for create_replica_server_plugin — route hooks, validation, shutdown."""
+
+
+import asyncio
+
+import httpx
+import pytest
+import respx
+
+from starfish_protocol.plugins import PullHookContext, PushHookContext
+from starfish_server.config.schema import CollectionConfig, SyncConfig
+
+from starfish_replica.config import RemoteConfig, SyncTrigger, WriteMode
+from starfish_replica.plugin import create_replica_server_plugin
+from tests.helpers import MemoryObjectStore
+
+
+def _col(**kwargs) -> CollectionConfig:
+    defaults = dict(
+        name="featured",
+        storagePath="posts/featured",
+        readRoles=["public"],
+        writeRoles=[],
+        encryption="none",
+        maxBodyBytes=65536,
+    )
+    defaults.update(kwargs)
+    return CollectionConfig(**defaults)
+
+
+def _config() -> SyncConfig:
+    return SyncConfig(version=1, collections=[_col()])
+
+
+def _remote(**kwargs) -> RemoteConfig:
+    defaults = dict(url="https://primary.example.com/v1", pullPath="/pull/posts/featured")
+    defaults.update(kwargs)
+    return RemoteConfig(**defaults)
+
+
+def test_invalid_config_raises_at_construction():
+    with pytest.raises(ValueError, match="invalid configuration"):
+        create_replica_server_plugin(
+            store=MemoryObjectStore(),
+            sync_config=_config(),
+            collections={"featured": _remote(writeMode=WriteMode.PUSH_THROUGH)},  # missing push_path
+        )
+
+
+async def test_before_pull_rejects_push_only():
+    replica = create_replica_server_plugin(
+        store=MemoryObjectStore(),
+        sync_config=_config(),
+        collections={"featured": _remote(writeMode=WriteMode.PUSH_ONLY)},
+    )
+    res = await replica.plugin.before_pull(PullHookContext(collection="featured", params={}))
+    assert res.action == "reject"
+    assert res.status == 405
+    assert "write-only" in res.error
+
+
+async def test_before_pull_proceeds_for_non_remote():
+    replica = create_replica_server_plugin(
+        store=MemoryObjectStore(),
+        sync_config=_config(),
+        collections={"featured": _remote()},
+    )
+    res = await replica.plugin.before_pull(PullHookContext(collection="other", params={}))
+    assert res.action == "proceed"
+
+
+@respx.mock
+async def test_before_pull_syncs_on_pull_trigger():
+    route = respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json={"data": {"a": 1}, "hash": "h1", "timestamp": 1}
+    )
+    replica = create_replica_server_plugin(
+        store=MemoryObjectStore(),
+        sync_config=_config(),
+        collections={"featured": _remote(syncTriggers=[SyncTrigger.ON_PULL])},
+    )
+    res = await replica.plugin.before_pull(PullHookContext(collection="featured", params={}))
+    assert res.action == "proceed"
+    assert route.call_count == 1
+    await replica.manager.stop()
+
+
+async def test_intercept_push_rejects_pull_only():
+    replica = create_replica_server_plugin(
+        store=MemoryObjectStore(),
+        sync_config=_config(),
+        collections={"featured": _remote(writeMode=WriteMode.PULL_ONLY)},
+    )
+    res = await replica.plugin.intercept_push(
+        PushHookContext(collection="featured", params={}, raw_body="{}")
+    )
+    assert res.action == "reject"
+    assert res.status == 405
+    assert "read-only" in res.error
+
+
+@respx.mock
+async def test_intercept_push_proxies_push_through():
+    respx.post("https://primary.example.com/v1/push/posts/featured").respond(
+        200, json={"hash": "primary-hash", "timestamp": 5}
+    )
+    respx.get("https://primary.example.com/v1/pull/posts/featured").respond(
+        200, json={"data": {}, "hash": "primary-hash", "timestamp": 5}
+    )
+    replica = create_replica_server_plugin(
+        store=MemoryObjectStore(),
+        sync_config=_config(),
+        collections={
+            "featured": _remote(writeMode=WriteMode.PUSH_THROUGH, pushPath="/push/posts/featured")
+        },
+    )
+    res = await replica.plugin.intercept_push(
+        PushHookContext(collection="featured", params={}, raw_body='{"data": {}}')
+    )
+    assert res.action == "respond"
+    assert res.status == 200
+    assert res.body == {"hash": "primary-hash", "timestamp": 5}
+    await asyncio.sleep(0)  # let the background sync task run under respx
+    await replica.manager.stop()
+
+
+async def test_intercept_push_proceeds_for_bidirectional():
+    replica = create_replica_server_plugin(
+        store=MemoryObjectStore(),
+        sync_config=_config(),
+        collections={
+            "featured": _remote(writeMode=WriteMode.BIDIRECTIONAL, pushPath="/push/posts/featured")
+        },
+    )
+    res = await replica.plugin.intercept_push(
+        PushHookContext(collection="featured", params={}, raw_body="{}")
+    )
+    assert res.action == "proceed"
+    await replica.manager.stop()
+
+
+async def test_shutdown_stops_manager():
+    replica = create_replica_server_plugin(
+        store=MemoryObjectStore(),
+        sync_config=_config(),
+        collections={"featured": _remote(syncTriggers=[SyncTrigger.SCHEDULED])},
+    )
+    await replica.manager.start()
+    assert len(replica.manager._tasks) == 1
+    await replica.plugin.shutdown()
+    assert replica.manager._tasks == []