fastapi-offline-sync 0.1.1__py3-none-any.whl

fastapi_offline_sync/__init__.py

@@ -0,0 +1,5 @@
+from .config import SyncConfig
+from .router import SyncRouter
+from .service import SyncService
+
+__all__ = ["SyncConfig", "SyncRouter", "SyncService"]

fastapi_offline_sync/cli.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from fastapi_offline_sync.config import SyncConfig
+from fastapi_offline_sync.service import SyncService
+
+
+async def _init_command(args: argparse.Namespace) -> None:
+    config = SyncConfig(mongodb_uri=args.mongodb_uri, database_name=args.database_name)
+    service = SyncService(config)
+    await service.initialize()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="fastapi-offline-sync")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init")
+    init_parser.add_argument("--mongodb-uri", required=True)
+    init_parser.add_argument("--database-name", required=True)
+
+    args = parser.parse_args()
+    if args.command == "init":
+        asyncio.run(_init_command(args))

fastapi_offline_sync/config.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+AuthorizationCallback = Callable[[Any, str], bool | Awaitable[bool]]
+JWTDependency = Callable[..., Any]
+WebSocketIdentityResolver = Callable[..., Any]
+ConflictResolver = Callable[[str, Any, dict[str, Any] | None, dict[str, Any], str | None, str], dict[str, Any] | None]
+IdentityResolver = Callable[[Any], str | None]
+IncomingDocumentTransform = Callable[[str, dict[str, Any] | None, Any], dict[str, Any] | None | Awaitable[dict[str, Any] | None]]
+
+
+@dataclass(slots=True)
+class CollectionPolicy:
+    delete_update_policy: str = "resurrect_on_update"
+
+    def __post_init__(self) -> None:
+        if self.delete_update_policy not in {"resurrect_on_update", "reject_update", "delete_wins"}:
+            raise ValueError(f"Unsupported delete_update_policy: {self.delete_update_policy}")
+
+
+@dataclass(slots=True)
+class SyncCollectionConfig:
+    name: str
+    allow_full_resync: bool = True
+    policy: CollectionPolicy = field(default_factory=CollectionPolicy)
+
+
+class SyncConfig(BaseSettings):
+    mongodb_uri: str
+    database_name: str
+    sync_prefix: str = "/sync"
+    sync_oplog_collection: str = "sync_oplog"
+    oplog_ttl_days: int = 30
+    default_pull_limit: int = 500
+    max_pull_limit: int = 1000
+    default_full_limit: int = 1000
+    collections: Sequence[str] = Field(default_factory=tuple)
+    collection_configs: Mapping[str, SyncCollectionConfig] = Field(default_factory=dict)
+    conflict_resolvers: Mapping[str, ConflictResolver] = Field(default_factory=dict)
+    jwt_dependency: JWTDependency | None = None
+    websocket_identity_resolver: WebSocketIdentityResolver | None = None
+    authorization_callback: AuthorizationCallback | None = None
+    incoming_document_transform: IncomingDocumentTransform | None = None
+    actor_id_field: str = "user_id"
+    scope_id_field: str = "user_id"
+    actor_id_resolver: IdentityResolver | None = None
+    scope_id_resolver: IdentityResolver | None = None
+    batch_atomic: bool = True
+    use_transactions: bool = True
+    metrics_enabled: bool = True
+    hlc_node_id: str | None = None
+    """Optional node identifier appended to HLC timestamps (e.g. ``"a3f2"``).
+
+    Set this to any short unique string per deployment unit (e.g. last 4 hex
+    of the pod IP, a worker index, or a UUID prefix). When ``None`` the
+    service will auto-derive a node ID from the local MAC address, which is
+    sufficient for single-host setups.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTAPI_OFFLINE_SYNC_",
+        arbitrary_types_allowed=True,
+    )
+
+    def configured_collections(self) -> tuple[str, ...]:
+        if self.collections:
+            return tuple(self.collections)
+        return tuple(self.collection_configs.keys())
+
+    def delete_update_policy_for(self, collection: str) -> str:
+        collection_config = self.collection_configs.get(collection)
+        if collection_config is None:
+            return "resurrect_on_update"
+        return collection_config.policy.delete_update_policy
+
+    def full_resync_allowed_for(self, collection: str) -> bool:
+        collection_config = self.collection_configs.get(collection)
+        if collection_config is None:
+            return True
+        return collection_config.allow_full_resync
+
+    def resolver_for(self, collection: str) -> ConflictResolver | None:
+        return self.conflict_resolvers.get(collection)

fastapi_offline_sync/exceptions.py

@@ -0,0 +1,29 @@
+class SyncError(Exception):
+    """Base exception for sync engine failures."""
+
+
+class ConflictRejection(SyncError):
+    """Raised when a conflict resolver permanently rejects a change."""
+
+
+class FullResyncRequired(SyncError):
+    """Raised when the client's sequence is older than oplog retention."""
+
+    def __init__(self, collections: list[str]) -> None:
+        super().__init__("Full resync required")
+        self.collections = collections
+
+
+class AuthorizationDenied(SyncError):
+    """Raised when a user is not authorized for a collection."""
+
+
+class TransactionUnavailable(SyncError):
+    """Raised when a MongoDB transaction cannot be started.
+
+    This typically means the server is not part of a replica set.
+    Transactions are required for atomic push operations; falling back to
+    non-transactional writes risks partial commits that corrupt sync state.
+    Set ``use_transactions=False`` in SyncConfig only if you explicitly accept
+    best-effort consistency (not recommended for production).
+    """

fastapi_offline_sync/hlc.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from threading import Lock
+
+
+def _derive_node_id() -> str:
+    """Return a 4-character hex string derived from this machine's MAC address.
+
+    Uses Python's ``uuid.getnode()`` which returns the MAC as an integer.
+    Falls back gracefully if the MAC cannot be determined (uuid will make one
+    up, which is still unique enough for our purposes).
+    """
+    mac = uuid.getnode()
+    return format(mac & 0xFFFF, "04x")
+
+
+def validate_hlc(value: str) -> str:
+    """Validate an HLC string, accepting both 2-part and 3-part formats.
+
+    2-part (legacy): ``20260502T143000.000Z-0001``
+    3-part (node-aware): ``20260502T143000.000Z-0001-a3f2``
+    """
+    try:
+        parts = value.split("-", maxsplit=2)
+        if len(parts) not in (2, 3):
+            raise ValueError("wrong number of parts")
+        timestamp_part = parts[0]
+        counter_part = parts[1]
+        datetime.strptime(timestamp_part, "%Y%m%dT%H%M%S.%fZ")
+        counter = int(counter_part)
+    except ValueError as exc:
+        raise ValueError(f"Invalid HLC value: {value}") from exc
+
+    if counter < 0:
+        raise ValueError(f"Invalid HLC counter: {value}")
+    return value
+
+
+@dataclass(slots=True)
+class HLCState:
+    last_timestamp: datetime = field(default_factory=lambda: datetime.fromtimestamp(0, tz=timezone.utc))
+    counter: int = 0
+
+
+class HybridLogicalClock:
+    def __init__(self, node_id: str | None = None) -> None:
+        self._lock = Lock()
+        self._state = HLCState()
+        self._node_id = node_id
+
+    @staticmethod
+    def derive_node_id() -> str:
+        """Return a 4-char hex node ID derived from the local MAC address.
+
+        Suitable for single-host multi-worker setups.  For multi-host
+        deployments supply an explicit ``hlc_node_id`` in ``SyncConfig``
+        (e.g. last 4 hex of the pod IP or a short UUID prefix).
+        """
+        return _derive_node_id()
+
+    def now(self) -> str:
+        with self._lock:
+            current = datetime.now(tz=timezone.utc)
+            if current > self._state.last_timestamp:
+                self._state.last_timestamp = current
+                self._state.counter = 0
+            else:
+                self._state.counter += 1
+
+            return self._format(self._state.last_timestamp, self._state.counter, self._node_id)
+
+    @staticmethod
+    def compare(left: str, right: str) -> int:
+        validate_hlc(left)
+        validate_hlc(right)
+        # Strip optional node_id suffix before comparing so that clocks from
+        # different nodes with the same timestamp+counter are considered equal.
+        left_core = "-".join(left.split("-", maxsplit=2)[:2])
+        right_core = "-".join(right.split("-", maxsplit=2)[:2])
+        if left_core == right_core:
+            return 0
+        return -1 if left_core < right_core else 1
+
+    @staticmethod
+    def _format(timestamp: datetime, counter: int, node_id: str | None) -> str:
+        base = f"{timestamp.strftime('%Y%m%dT%H%M%S.%f')[:-3]}Z-{counter:04d}"
+        if node_id:
+            return f"{base}-{node_id}"
+        return base

fastapi_offline_sync/metrics.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final
+
+from prometheus_client import Counter, Gauge
+
+
+@dataclass(slots=True)
+class SyncMetrics:
+    push_total: Counter
+    push_changes_total: Counter
+    conflict_total: Counter
+    pull_total: Counter
+    pull_changes_served: Counter
+    full_resync_total: Counter
+    oplog_size: Gauge
+    websocket_connections: Gauge
+
+
+_METRICS: SyncMetrics | None = None
+
+
+def build_metrics() -> SyncMetrics:
+    global _METRICS
+
+    if _METRICS is None:
+        _METRICS = SyncMetrics(
+            push_total=Counter("sync_push_total", "Push requests", labelnames=("status",)),
+            push_changes_total=Counter("sync_push_changes_total", "Changes pushed"),
+            conflict_total=Counter("sync_conflict_total", "Conflicts detected", labelnames=("collection",)),
+            pull_total=Counter("sync_pull_total", "Pull requests"),
+            pull_changes_served=Counter("sync_pull_changes_served", "Changes served from pull"),
+            full_resync_total=Counter("sync_full_resync_total", "Full resync requests"),
+            oplog_size=Gauge("sync_oplog_size", "Estimated oplog document count"),
+            websocket_connections=Gauge("sync_websocket_connections", "Active websocket connections"),
+        )
+
+    return _METRICS

fastapi_offline_sync/mongo.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any
+
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorCollection, AsyncIOMotorDatabase
+from pymongo import ASCENDING, DESCENDING
+from pymongo.errors import CollectionInvalid
+
+from fastapi_offline_sync.config import SyncConfig
+
+
+class MongoManager:
+    def __init__(self, config: SyncConfig) -> None:
+        self._config = config
+        self._client = AsyncIOMotorClient(config.mongodb_uri)
+        self._database = self._client[config.database_name]
+
+    @property
+    def database(self) -> AsyncIOMotorDatabase:
+        return self._database
+
+    @property
+    def oplog(self) -> AsyncIOMotorCollection:
+        return self._database[self._config.sync_oplog_collection]
+
+    def collection(self, name: str) -> AsyncIOMotorCollection:
+        return self._database[name]
+
+    async def initialize(self) -> None:
+        try:
+            await self._database.create_collection(self._config.sync_oplog_collection)
+        except CollectionInvalid:
+            pass
+        await self.oplog.create_index([("timestamp", ASCENDING)], expireAfterSeconds=self._config.oplog_ttl_days * 86400)
+        await self.oplog.create_index([("scope_id", ASCENDING), ("collection", ASCENDING), ("_id", ASCENDING)])
+        for collection_name in self._config.configured_collections():
+            await self.ensure_business_indexes(collection_name)
+
+    async def ensure_business_indexes(self, collection_name: str) -> None:
+        collection = self.collection(collection_name)
+        await collection.create_index([("_sync_scope_id", ASCENDING), ("_sync_deleted", ASCENDING), ("_id", ASCENDING)])
+        await collection.create_index([("_sync_version", DESCENDING)])
+
+    async def estimate_oplog_size(self) -> int:
+        return await self.oplog.estimated_document_count()
+
+    async def transaction(self):
+        session = await self._client.start_session()
+        return session
+
+    @asynccontextmanager
+    async def watch_oplog(self, pipeline: list[dict[str, Any]], *, full_document: str = "updateLookup"):
+        async with self.oplog.watch(pipeline=pipeline, full_document=full_document) as stream:
+            yield stream

fastapi_offline_sync/resolver.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi_offline_sync.exceptions import ConflictRejection
+from fastapi_offline_sync.hlc import HybridLogicalClock
+
+
+@dataclass(slots=True)
+class ResolutionResult:
+    document: dict[str, Any] | None
+    operation: str
+    status: str
+
+
+class LastWriterWinsByHLC:
+    def resolve(
+        self,
+        *,
+        collection: str,
+        doc_id: str | int,
+        current_doc: dict[str, Any] | None,
+        incoming_change: dict[str, Any],
+        current_version: str | None,
+        incoming_parent_version: str,
+        delete_update_policy: str,
+    ) -> ResolutionResult:
+        del collection
+
+        if current_doc is None or current_version is None:
+            return ResolutionResult(
+                document=incoming_change.get("data"),
+                operation=incoming_change["operation"],
+                status="accepted",
+            )
+
+        if incoming_change["operation"] == "upsert" and current_doc.get("_sync_deleted"):
+            if delete_update_policy == "reject_update":
+                raise ConflictRejection(f"Update rejected for deleted document: {doc_id}")
+            if delete_update_policy == "delete_wins":
+                return ResolutionResult(document=None, operation="delete", status="rejected")
+
+        comparison = HybridLogicalClock.compare(incoming_parent_version, current_version)
+        if comparison >= 0:
+            return ResolutionResult(
+                document=incoming_change.get("data"),
+                operation=incoming_change["operation"],
+                status="conflict_resolved",
+            )
+
+        tie_break = str(doc_id)
+        if incoming_parent_version == current_version and tie_break <= str(doc_id):
+            return ResolutionResult(
+                document=incoming_change.get("data"),
+                operation=incoming_change["operation"],
+                status="conflict_resolved",
+            )
+
+        return ResolutionResult(
+            document=current_doc,
+            operation="upsert" if not current_doc.get("_sync_deleted") else "delete",
+            status="rejected",
+        )

fastapi_offline_sync/router.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Any, Callable, cast
+
+from fastapi import APIRouter, Depends, HTTPException, Query, WebSocket, WebSocketDisconnect, status
+from fastapi.responses import StreamingResponse
+from prometheus_fastapi_instrumentator import Instrumentator
+
+from fastapi_offline_sync.config import SyncConfig
+from fastapi_offline_sync.exceptions import AuthorizationDenied, FullResyncRequired
+from fastapi_offline_sync.schemas import FullResyncRequiredResponse, FullSyncQuery, PullQuery, PullResponse, PushRequest, PushResponse, StreamSubscribeMessage
+from fastapi_offline_sync.service import SyncService
+
+
+def _noop_user(*, token: str | None = None) -> dict[str, str]:
+    del token
+    return {"user_id": "anonymous"}
+
+
+class SyncRouter(APIRouter):
+    def __init__(self, config: SyncConfig) -> None:
+        self.config = config
+        self.service = SyncService(config)
+        dependency = config.jwt_dependency or _noop_user
+        self._auth_dependency = dependency
+        self._websocket_auth_dependency: Callable[..., Any] = cast(
+            Callable[..., Any],
+            config.websocket_identity_resolver or dependency,
+        )
+
+        super().__init__(prefix=config.sync_prefix, tags=["sync"])
+        self.add_event_handler("startup", self.install)
+
+        async def push_endpoint(payload: PushRequest, user: Any = Depends(dependency)) -> PushResponse:
+            return await self._handle_push(payload, user)
+
+        async def pull_endpoint(
+            since: str,
+            collections: str | None = None,
+            limit: int = Query(default=config.default_pull_limit, ge=1, le=config.max_pull_limit),
+            user: Any = Depends(dependency),
+        ) -> PullResponse | FullResyncRequiredResponse:
+            return await self._handle_pull(since=since, collections=collections, limit=limit, user=user)
+
+        async def full_sync_endpoint(
+            collections: str,
+            cursor: str | None = None,
+            limit: int = Query(default=config.default_full_limit, ge=1, le=config.max_pull_limit),
+            user: Any = Depends(dependency),
+        ) -> StreamingResponse:
+            return await self._handle_full_sync(collections=collections, cursor=cursor, limit=limit, user=user)
+
+        self.add_api_route("/push", push_endpoint, methods=["POST"], response_model=PushResponse)
+        self.add_api_route("/pull", pull_endpoint, methods=["GET"], response_model=PullResponse | FullResyncRequiredResponse)
+        self.add_api_route("/full", full_sync_endpoint, methods=["GET"])
+        self.add_api_websocket_route("/stream", self.stream)
+
+    async def install(self) -> None:
+        await self.service.initialize()
+
+    def instrument(self, app: Any) -> None:
+        if not self.config.metrics_enabled:
+            return
+        Instrumentator().instrument(app).expose(app)
+
+    async def _handle_push(self, payload: PushRequest, user: Any) -> PushResponse:
+        try:
+            return await self.service.push(payload, user)
+        except AuthorizationDenied as exc:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+
+    async def _handle_pull(self, since: str, collections: str | None, limit: int, user: Any) -> PullResponse | FullResyncRequiredResponse:
+        parsed = PullQuery(since=since, collections=collections.split(",") if collections else [], limit=limit)
+        try:
+            return await self.service.pull(since=parsed.since, collections=parsed.collections, limit=parsed.limit, user=user)
+        except FullResyncRequired as exc:
+            return FullResyncRequiredResponse(collections=exc.collections)
+        except AuthorizationDenied as exc:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+
+    async def _handle_full_sync(self, collections: str, cursor: str | None, limit: int, user: Any) -> StreamingResponse:
+        query = FullSyncQuery(collections=collections.split(","), cursor=cursor, limit=limit)
+        try:
+            body, headers = await self.service.full_sync(query, user)
+        except AuthorizationDenied as exc:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc)) from exc
+        return StreamingResponse(body, media_type="application/x-ndjson", headers=headers)
+
+    async def stream(self, websocket: WebSocket) -> None:
+        subscription_task: asyncio.Task[None] | None = None
+        heartbeat_task: asyncio.Task[None] | None = None
+        try:
+            await websocket.accept()
+            message = await websocket.receive_json()
+            token = message.get("token") or websocket.query_params.get("token")
+            scope_id = message.get("scope_id") or websocket.query_params.get("scope_id")
+            user = await self._resolve_websocket_user(token, scope_id)
+            payload = dict(message)
+            payload.pop("token", None)
+            subscription = StreamSubscribeMessage.model_validate(payload)
+
+            async def forward_events() -> None:
+                async for event in self.service.stream_changes(subscription, user):
+                    await websocket.send_json(event)
+
+            async def forward_heartbeat() -> None:
+                async for ping in self.service.heartbeat():
+                    await websocket.send_json(ping)
+
+            subscription_task = asyncio.create_task(forward_events())
+            heartbeat_task = asyncio.create_task(forward_heartbeat())
+            done, pending = await asyncio.wait({subscription_task, heartbeat_task}, return_when=asyncio.FIRST_COMPLETED)
+            for task in done:
+                await task
+            for task in pending:
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+        except (WebSocketDisconnect, AuthorizationDenied):
+            return
+        finally:
+            if subscription_task is not None:
+                subscription_task.cancel()
+            if heartbeat_task is not None:
+                heartbeat_task.cancel()
+            with contextlib.suppress(RuntimeError):
+                await websocket.close()
+
+    async def _resolve_websocket_user(self, token: str | None, scope_id: str | None = None) -> Any:
+        if token is not None or scope_id is not None:
+            resolved = self._websocket_auth_dependency(token=token, scope_id=scope_id)
+        else:
+            resolved = self._websocket_auth_dependency()
+        if asyncio.iscoroutine(resolved):
+            return await resolved
+        return resolved

fastapi_offline_sync/schemas/__init__.py

@@ -0,0 +1,20 @@
+from .common import OplogEntry, SyncChangePayload
+from .full import FullSyncQuery, FullSyncRecord
+from .pull import FullResyncRequiredResponse, PullQuery, PullResponse
+from .push import PushRequest, PushResponse, PushResult
+from .stream import StreamControlMessage, StreamSubscribeMessage
+
+__all__ = [
+    "FullResyncRequiredResponse",
+    "FullSyncQuery",
+    "FullSyncRecord",
+    "OplogEntry",
+    "PullQuery",
+    "PullResponse",
+    "PushRequest",
+    "PushResponse",
+    "PushResult",
+    "StreamControlMessage",
+    "StreamSubscribeMessage",
+    "SyncChangePayload",
+]

fastapi_offline_sync/schemas/common.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from fastapi_offline_sync.hlc import validate_hlc
+
+
+class SyncModel(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class SyncChangePayload(SyncModel):
+    collection: str
+    operation: str
+    doc_id: str | int = Field(serialization_alias="doc_id")
+    data: dict[str, Any] | None = None
+    parent_version: str | None = None
+
+    @field_validator("operation")
+    @classmethod
+    def validate_operation(cls, value: str) -> str:
+        if value not in {"upsert", "delete"}:
+            raise ValueError("operation must be 'upsert' or 'delete'")
+        return value
+
+    @field_validator("parent_version")
+    @classmethod
+    def validate_parent_version(cls, value: str | None) -> str | None:
+        if value in {None, ""}:
+            return None
+        return validate_hlc(value)
+
+
+class OplogEntry(SyncModel):
+    version: str
+    collection: str
+    doc_id: str | int
+    operation: str
+    data: dict[str, Any] | None
+    parent_version: str | None = None

fastapi_offline_sync/schemas/full.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from fastapi_offline_sync.schemas.common import SyncModel
+
+
+class FullSyncQuery(SyncModel):
+    collections: list[str]
+    cursor: str | None = None
+    limit: int = 1000
+
+
+class FullSyncRecord(SyncModel):
+    collection: str
+    doc_id: str | int
+    data: dict[str, object] | None
+    deleted: bool = False
+    """True when this document was soft-deleted on the server.
+
+    Clients should remove the record from their local store when they see
+    ``deleted=True``.  ``data`` will be ``None`` for deleted records.
+    """
+

fastapi_offline_sync/schemas/pull.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pydantic import field_validator
+
+from fastapi_offline_sync.hlc import validate_hlc
+from fastapi_offline_sync.schemas.common import OplogEntry, SyncModel
+
+
+class PullQuery(SyncModel):
+    since: str
+    collections: list[str] = []
+    limit: int = 500
+
+    @field_validator("since")
+    @classmethod
+    def validate_since(cls, value: str) -> str:
+        return validate_hlc(value)
+
+    @field_validator("limit")
+    @classmethod
+    def validate_limit(cls, value: int) -> int:
+        if value < 1 or value > 1000:
+            raise ValueError("limit must be between 1 and 1000")
+        return value
+
+
+class PullResponse(SyncModel):
+    changes: list[OplogEntry]
+    last_seq: str
+
+
+class FullResyncRequiredResponse(SyncModel):
+    full_resync_required: bool = True
+    collections: list[str]