offline-sync-sdk 0.2.0__py3-none-any.whl

sync_sdk/registry.py

@@ -0,0 +1,44 @@
+"""Explicit opt-in entities and application-owned validation/conflict policy."""
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from .models import Mutation
+
+ConflictPolicy = Callable[[Mutation, int], str | None]
+
+
+def optimistic_version(mutation: Mutation, current_version: int) -> str | None:
+    if mutation.base_version is not None and mutation.base_version != current_version:
+        return "Version mismatch"
+    return None
+
+
+@dataclass(frozen=True)
+class Entity:
+    name: str
+    schema: type[BaseModel] | None = None
+    conflict_policy: ConflictPolicy = optimistic_version
+
+    def validate(self, mutation: Mutation) -> Mutation:
+        if self.schema is None or mutation.operation == "delete":
+            return mutation
+        payload = self.schema.model_validate(mutation.payload).model_dump(mode="json")
+        return mutation.model_copy(update={"payload": payload})
+
+
+class EntityRegistry:
+    def __init__(self, entities: Iterable[Entity] = ()):
+        self._entities: dict[str, Entity] = {}
+        for entity in entities:
+            self.register(entity)
+
+    def register(self, entity: Entity) -> None:
+        if not entity.name or entity.name in self._entities:
+            raise ValueError("Entity names must be nonempty and unique")
+        self._entities[entity.name] = entity
+
+    def get(self, name: str) -> Entity | None:
+        return self._entities.get(name)

sync_sdk/store.py

@@ -0,0 +1,147 @@
+"""Durable local state. Transactions contain no network calls or await points."""
+
+import json
+import sqlite3
+from pathlib import Path
+
+from .models import ChangeBatch, Mutation, MutationResult
+
+
+class SQLiteStore:
+    """Use one database per client and remote dataset; one sync worker per file."""
+
+    def __init__(self, path: str | Path, *, client_id: str):
+        self.db = sqlite3.connect(str(path))
+        self.db.row_factory = sqlite3.Row
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute("PRAGMA synchronous=FULL")
+        self.db.executescript("""
+            CREATE TABLE IF NOT EXISTS metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+            CREATE TABLE IF NOT EXISTS outbox (
+                position INTEGER PRIMARY KEY AUTOINCREMENT,
+                mutation_id TEXT UNIQUE NOT NULL, body TEXT NOT NULL,
+                status TEXT NOT NULL DEFAULT 'pending', result TEXT
+            );
+            CREATE TABLE IF NOT EXISTS records (
+                entity TEXT NOT NULL, entity_id TEXT NOT NULL,
+                payload TEXT NOT NULL, version INTEGER NOT NULL,
+                PRIMARY KEY(entity, entity_id)
+            );
+        """)
+        with self.db:
+            self.db.execute(
+                "INSERT OR IGNORE INTO metadata VALUES ('client_id', ?)", (client_id,)
+            )
+        if self._get("client_id") != client_id:
+            self.db.close()
+            raise ValueError("Database belongs to a different client_id")
+        self.client_id = client_id
+
+    def _get(self, key: str, default: str = "0") -> str:
+        row = self.db.execute(
+            "SELECT value FROM metadata WHERE key=?", (key,)
+        ).fetchone()
+        return row[0] if row else default
+
+    def _set(self, key: str, value: str) -> None:
+        self.db.execute("INSERT OR REPLACE INTO metadata VALUES (?, ?)", (key, value))
+
+    @property
+    def cursor(self) -> int:
+        return int(self._get("cursor"))
+
+    @property
+    def retry_state(self) -> tuple[int, float]:
+        return int(self._get("attempts")), float(self._get("retry_at"))
+
+    def schedule_retry(self, attempts: int, retry_at: float) -> None:
+        with self.db:
+            self._set("attempts", str(attempts))
+            self._set("retry_at", str(retry_at))
+
+    def enqueue(self, mutation: Mutation) -> None:
+        if mutation.client_id != self.client_id:
+            raise ValueError("Mutation client_id does not match database")
+        body = mutation.model_dump_json()
+        with self.db:
+            row = self.db.execute(
+                "SELECT body FROM outbox WHERE mutation_id=?",
+                (str(mutation.mutation_id),),
+            ).fetchone()
+            if row and row[0] != body:
+                raise ValueError("Cannot reuse a mutation_id with different content")
+            self.db.execute(
+                "INSERT OR IGNORE INTO outbox (mutation_id, body) VALUES (?, ?)",
+                (str(mutation.mutation_id), body),
+            )
+
+    def pending(self, limit: int) -> list[Mutation]:
+        rows = self.db.execute(
+            "SELECT body FROM outbox WHERE status='pending' ORDER BY position LIMIT ?",
+            (limit,),
+        )
+        return [Mutation.model_validate_json(row[0]) for row in rows]
+
+    def pending_count(self) -> int:
+        row = self.db.execute(
+            "SELECT COUNT(*) FROM outbox WHERE status='pending'"
+        ).fetchone()
+        return int(row[0])
+
+    def results(self) -> list[MutationResult]:
+        rows = self.db.execute(
+            "SELECT result FROM outbox WHERE result IS NOT NULL ORDER BY position"
+        )
+        return [MutationResult.model_validate_json(row[0]) for row in rows]
+
+    def acknowledge(self, results: list[MutationResult]) -> None:
+        with self.db:
+            for result in results:
+                self.db.execute(
+                    "UPDATE outbox SET status=?, result=? WHERE mutation_id=? AND status='pending'",
+                    (result.status, result.model_dump_json(), str(result.mutation_id)),
+                )
+
+    def apply_page(self, page: ChangeBatch) -> None:
+        """Validate progress, then commit the entire page and checkpoint atomically."""
+        cursor = self.cursor
+        for change in page.changes:
+            if change.sequence <= cursor:
+                raise ValueError("Change sequences must strictly increase")
+            cursor = change.sequence
+        if page.cursor != cursor or (page.has_more and not page.changes):
+            raise ValueError("Invalid change feed checkpoint")
+        with self.db:
+            for change in page.changes:
+                if change.operation == "delete":
+                    self.db.execute(
+                        "DELETE FROM records WHERE entity=? AND entity_id=?",
+                        (change.entity, change.entity_id),
+                    )
+                else:
+                    self.db.execute(
+                        "INSERT OR REPLACE INTO records VALUES (?, ?, ?, ?)",
+                        (
+                            change.entity,
+                            change.entity_id,
+                            json.dumps(change.payload),
+                            change.version,
+                        ),
+                    )
+            self._set("cursor", str(page.cursor))
+
+    def get_record(self, entity: str, entity_id: str) -> dict | None:
+        row = self.db.execute(
+            "SELECT payload, version FROM records WHERE entity=? AND entity_id=?",
+            (entity, entity_id),
+        ).fetchone()
+        return {"payload": json.loads(row[0]), "version": row[1]} if row else None
+
+    def close(self) -> None:
+        self.db.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

sync_sdk/telemetry.py

@@ -0,0 +1,131 @@
+"""Small observability interface used by the sync pipeline."""
+
+from collections.abc import Iterator, Mapping
+from contextlib import AbstractContextManager, contextmanager, suppress
+from typing import Protocol
+
+AttributeValue = str | bool | int | float
+Attributes = Mapping[str, AttributeValue]
+
+
+class TelemetrySpan(Protocol):
+    def set_attribute(self, name: str, value: AttributeValue) -> None: ...
+
+    def add_event(self, name: str, attributes: Attributes | None = None) -> None: ...
+
+
+class PipelineTelemetry(Protocol):
+    """Receives traces and metrics from the client and gateway."""
+
+    def span(
+        self, name: str, attributes: Attributes | None = None
+    ) -> AbstractContextManager[TelemetrySpan]: ...
+
+    def count(
+        self, name: str, value: int = 1, attributes: Attributes | None = None
+    ) -> None: ...
+
+    def record(
+        self, name: str, value: float, attributes: Attributes | None = None
+    ) -> None: ...
+
+    def gauge(
+        self, name: str, value: float, attributes: Attributes | None = None
+    ) -> None: ...
+
+
+class _NoOpSpan:
+    def set_attribute(self, name: str, value: AttributeValue) -> None:
+        pass
+
+    def add_event(self, name: str, attributes: Attributes | None = None) -> None:
+        pass
+
+
+class _SafeSpan:
+    def __init__(self, span: TelemetrySpan):
+        self._span = span
+
+    def set_attribute(self, name: str, value: AttributeValue) -> None:
+        with suppress(Exception):
+            self._span.set_attribute(name, value)
+
+    def add_event(self, name: str, attributes: Attributes | None = None) -> None:
+        with suppress(Exception):
+            self._span.add_event(name, attributes)
+
+
+class NoOpTelemetry:
+    """Default telemetry target. It does no work and needs no extra package."""
+
+    @contextmanager
+    def span(
+        self, name: str, attributes: Attributes | None = None
+    ) -> Iterator[_NoOpSpan]:
+        yield _NoOpSpan()
+
+    def count(
+        self, name: str, value: int = 1, attributes: Attributes | None = None
+    ) -> None:
+        pass
+
+    def record(
+        self, name: str, value: float, attributes: Attributes | None = None
+    ) -> None:
+        pass
+
+    def gauge(
+        self, name: str, value: float, attributes: Attributes | None = None
+    ) -> None:
+        pass
+
+
+class SafeTelemetry:
+    """Stops monitoring errors from stopping data sync."""
+
+    def __init__(self, telemetry: PipelineTelemetry | None = None):
+        self._telemetry = telemetry or NoOpTelemetry()
+
+    @contextmanager
+    def span(
+        self, name: str, attributes: Attributes | None = None
+    ) -> Iterator[TelemetrySpan]:
+        try:
+            manager = self._telemetry.span(name, attributes)
+            span = manager.__enter__()
+        except Exception:  # noqa: BLE001 -- monitoring must not stop sync
+            yield _NoOpSpan()
+            return
+        try:
+            yield _SafeSpan(span)
+        except BaseException as error:
+            with suppress(Exception):
+                manager.__exit__(type(error), error, error.__traceback__)
+            raise
+        else:
+            with suppress(Exception):
+                manager.__exit__(None, None, None)
+
+    def count(
+        self, name: str, value: int = 1, attributes: Attributes | None = None
+    ) -> None:
+        with suppress(Exception):
+            self._telemetry.count(name, value, attributes)
+
+    def record(
+        self, name: str, value: float, attributes: Attributes | None = None
+    ) -> None:
+        with suppress(Exception):
+            self._telemetry.record(name, value, attributes)
+
+    def gauge(
+        self, name: str, value: float, attributes: Attributes | None = None
+    ) -> None:
+        with suppress(Exception):
+            self._telemetry.gauge(name, value, attributes)
+
+
+def safe_telemetry(telemetry: PipelineTelemetry | None) -> SafeTelemetry:
+    if isinstance(telemetry, SafeTelemetry):
+        return telemetry
+    return SafeTelemetry(telemetry)