svc-infra 0.1.589__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/data/backup.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Callable, Optional
+
+
+@dataclass(frozen=True)
+class BackupHealthReport:
+    ok: bool
+    last_success: Optional[datetime]
+    retention_days: Optional[int]
+    message: str = ""
+
+
+def verify_backups(
+    *, last_success: Optional[datetime] = None, retention_days: Optional[int] = None
+) -> BackupHealthReport:
+    """Return a basic backup health report.
+
+    In production, callers should plug a provider-specific checker and translate into this report.
+    """
+    if last_success is None:
+        return BackupHealthReport(
+            ok=False,
+            last_success=None,
+            retention_days=retention_days,
+            message="no_backup_seen",
+        )
+    now = datetime.now(timezone.utc)
+    age_days = (now - last_success).total_seconds() / 86400.0
+    ok = retention_days is None or age_days <= max(1, retention_days)
+    return BackupHealthReport(
+        ok=ok, last_success=last_success, retention_days=retention_days
+    )
+
+
+__all__ = ["BackupHealthReport", "verify_backups"]
+
+
+def make_backup_verification_job(
+    checker: Callable[[], BackupHealthReport],
+    *,
+    on_report: Optional[Callable[[BackupHealthReport], None]] = None,
+):
+    """Return a callable suitable for scheduling in a job runner.
+
+    The checker should perform provider-specific checks and return a BackupHealthReport.
+    If on_report is provided, it will be invoked with the report.
+    """
+
+    def _job() -> BackupHealthReport:
+        rep = checker()
+        if on_report:
+            on_report(rep)
+        return rep
+
+    return _job

svc_infra/data/erasure.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Iterable, Optional, Protocol
+
+
+class SqlSession(Protocol):  # minimal protocol for tests/integration
+    async def execute(self, stmt: Any) -> Any:
+        pass
+
+
+@dataclass(frozen=True)
+class ErasureStep:
+    name: str
+    run: Callable[[SqlSession, str], Awaitable[int] | int]
+
+
+@dataclass(frozen=True)
+class ErasurePlan:
+    steps: Iterable[ErasureStep]
+
+
+async def run_erasure(
+    session: SqlSession,
+    principal_id: str,
+    plan: ErasurePlan,
+    *,
+    on_audit: Optional[Callable[[str, dict[str, Any]], None]] = None,
+) -> int:
+    """Run an erasure plan and optionally emit an audit event.
+
+    Returns total affected rows across steps.
+    """
+    total = 0
+    for s in plan.steps:
+        res = s.run(session, principal_id)
+        if hasattr(res, "__await__"):
+            res = await res
+        total += int(res or 0)
+    if on_audit:
+        on_audit("erasure.completed", {"principal_id": principal_id, "affected": total})
+    return total
+
+
+__all__ = ["ErasureStep", "ErasurePlan", "run_erasure"]

svc_infra/data/fixtures.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+from typing import Awaitable, Callable, Iterable, Optional
+
+
+async def run_fixtures(
+    loaders: Iterable[Callable[[], None | Awaitable[None]]],
+    *,
+    run_once_file: Optional[str] = None,
+) -> None:
+    """Run a sequence of fixture loaders (sync or async).
+
+    - If run_once_file is provided and exists, does nothing.
+    - On success, creates the run_once_file sentinel (parent dirs included).
+    """
+    if run_once_file:
+        sentinel = Path(run_once_file)
+        if sentinel.exists():
+            return
+    for fn in loaders:
+        res = fn()
+        if inspect.isawaitable(res):
+            await res
+    if run_once_file:
+        sentinel.parent.mkdir(parents=True, exist_ok=True)
+        Path(run_once_file).write_text("ok")
+
+
+def make_on_load_fixtures(
+    *loaders: Callable[[], None | Awaitable[None]], run_once_file: Optional[str] = None
+) -> Callable[[], Awaitable[None]]:
+    """Return an async callable suitable for add_data_lifecycle(on_load_fixtures=...)."""
+
+    async def _runner() -> None:
+        await run_fixtures(loaders, run_once_file=run_once_file)
+
+    return _runner
+
+
+__all__ = ["run_fixtures", "make_on_load_fixtures"]

svc_infra/data/retention.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Iterable, Optional, Protocol, Sequence
+
+
+class SqlSession(Protocol):  # minimal protocol for tests/integration
+    async def execute(self, stmt: Any) -> Any:
+        pass
+
+
+@dataclass(frozen=True)
+class RetentionPolicy:
+    name: str
+    model: Any  # SQLAlchemy model or test double exposing columns
+    older_than_days: int
+    soft_delete_field: Optional[str] = "deleted_at"
+    extra_where: Optional[Sequence[Any]] = None
+    hard_delete: bool = False
+
+
+async def purge_policy(session: SqlSession, policy: RetentionPolicy) -> int:
+    """Execute a single retention purge according to policy.
+
+    If hard_delete is False and soft_delete_field exists on model, set timestamp; else DELETE.
+    Returns number of affected rows (best-effort; test doubles may return an int directly).
+    """
+    cutoff = datetime.now(timezone.utc) - timedelta(days=policy.older_than_days)
+    m = policy.model
+    where = list(policy.extra_where or [])
+    created_col = getattr(m, "created_at", None)
+    if created_col is not None and hasattr(created_col, "__le__"):
+        where.append(created_col <= cutoff)
+
+    # Soft-delete path when available and requested
+    if (
+        not policy.hard_delete
+        and policy.soft_delete_field
+        and hasattr(m, policy.soft_delete_field)
+    ):
+        stmt = m.update().where(*where).values({policy.soft_delete_field: cutoff})
+        res = await session.execute(stmt)
+        return getattr(res, "rowcount", 0)
+
+    # Hard delete fallback
+    stmt = m.delete().where(*where)
+    res = await session.execute(stmt)
+    return getattr(res, "rowcount", 0)
+
+
+async def run_retention_purge(
+    session: SqlSession, policies: Iterable[RetentionPolicy]
+) -> int:
+    total = 0
+    for p in policies:
+        total += await purge_policy(session, p)
+    return total
+
+
+__all__ = ["RetentionPolicy", "purge_policy", "run_retention_purge"]

svc_infra/db/__init__.py

@@ -0,0 +1,15 @@
+from svc_infra.db.ops import (
+    drop_table_safe,
+    get_database_url,
+    kill_blocking_queries,
+    run_sync_sql,
+    wait_for_database,
+)
+
+__all__ = [
+    "drop_table_safe",
+    "get_database_url",
+    "kill_blocking_queries",
+    "run_sync_sql",
+    "wait_for_database",
+]

svc_infra/db/crud_schema.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Optional, Sequence
+from typing import Any, Optional, Sequence, cast
 
 from pydantic import BaseModel, ConfigDict, create_model
 
@@ -27,9 +27,9 @@ class FieldSpec:
     exclude_from_update: bool = False
 
 
-def _opt(t: type[Any]) -> tuple[type[Any], object]:
+def _opt(t: type[Any]) -> tuple[Any, Any]:
     # convenience: Optional[t] with default None
-    return (t | None, None)  # type: ignore[operator]
+    return (t | None, None)
 
 
 def make_crud_schemas_from_specs(
@@ -40,9 +40,9 @@ def make_crud_schemas_from_specs(
     update_name: Optional[str],
     json_encoders: Optional[dict[type[Any], Any]] = None,
 ) -> tuple[type[BaseModel], type[BaseModel], type[BaseModel]]:
-    ann_read: dict[str, tuple[type, object]] = {}
-    ann_create: dict[str, tuple[type, object]] = {}
-    ann_update: dict[str, tuple[type, object]] = {}
+    ann_read: dict[str, tuple[Any, Any]] = {}
+    ann_create: dict[str, tuple[Any, Any]] = {}
+    ann_update: dict[str, tuple[Any, Any]] = {}
 
     for s in specs:
         # READ: include unless excluded; all fields Optional
@@ -60,9 +60,9 @@ def make_crud_schemas_from_specs(
         if not s.exclude_from_update:
             ann_update[s.name] = _opt(s.typ)
 
-    Read = create_model(read_name or "Read", **ann_read)  # type: ignore[arg-type]
-    Create = create_model(create_name or "Create", **ann_create)  # type: ignore[arg-type]
-    Update = create_model(update_name or "Update", **ann_update)  # type: ignore[arg-type]
+    Read = create_model(read_name or "Read", **cast(dict[str, Any], ann_read))
+    Create = create_model(create_name or "Create", **cast(dict[str, Any], ann_create))
+    Update = create_model(update_name or "Update", **cast(dict[str, Any], ann_update))
 
     cfg = ConfigDict(from_attributes=True)
     if json_encoders:

svc_infra/db/inbox.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import time
+from typing import Protocol
+
+
+class InboxStore(Protocol):
+    def mark_if_new(self, key: str, ttl_seconds: int = 24 * 3600) -> bool:
+        """Mark key as processed if not seen; return True if newly marked, False if duplicate."""
+        ...
+
+    def purge_expired(self) -> int:
+        """Optional: remove expired keys, return number purged."""
+        ...
+
+    def is_marked(self, key: str) -> bool:
+        """Return True if key is already marked (not expired), without modifying it."""
+        ...
+
+
+class InMemoryInboxStore:
+    def __init__(self) -> None:
+        self._keys: dict[str, float] = {}
+
+    def mark_if_new(self, key: str, ttl_seconds: int = 24 * 3600) -> bool:
+        now = time.time()
+        exp = self._keys.get(key)
+        if exp and exp > now:
+            return False
+        self._keys[key] = now + ttl_seconds
+        return True
+
+    def purge_expired(self) -> int:
+        now = time.time()
+        to_del = [k for k, e in self._keys.items() if e <= now]
+        for k in to_del:
+            self._keys.pop(k, None)
+        return len(to_del)
+
+    def is_marked(self, key: str) -> bool:
+        now = time.time()
+        exp = self._keys.get(key)
+        return bool(exp and exp > now)
+
+
+class SqlInboxStore:
+    """Skeleton for a SQL-backed inbox store (dedupe table).
+
+    Implementations should:
+    - INSERT key with expires_at if not exists (unique constraint)
+    - Return False on duplicate key violations
+    - Periodically DELETE expired rows
+    """
+
+    def __init__(self, session_factory):
+        self._session_factory = session_factory
+
+    def mark_if_new(
+        self, key: str, ttl_seconds: int = 24 * 3600
+    ) -> bool:  # pragma: no cover - skeleton
+        raise NotImplementedError
+
+    def purge_expired(self) -> int:  # pragma: no cover - skeleton
+        raise NotImplementedError
+
+    def is_marked(self, key: str) -> bool:  # pragma: no cover - skeleton
+        raise NotImplementedError

svc_infra/db/nosql/__init__.py

@@ -1,7 +1,10 @@
+from __future__ import annotations
+
 from svc_infra.db.nosql.resource import NoSqlResource
 
 from .repository import NoSqlRepository
 
+
 __all__ = [
     "NoSqlResource",
     "NoSqlRepository",

svc_infra/db/nosql/core.py

@@ -1,13 +1,25 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Iterable, Sequence
+from typing import Any, Iterable, Sequence, cast
 
-from motor.motor_asyncio import AsyncIOMotorDatabase
-from pymongo import IndexModel
+try:
+    from motor.motor_asyncio import AsyncIOMotorDatabase
+    from pymongo import IndexModel
+
+    HAS_MOTOR = True
+except ImportError:  # pragma: no cover
+    HAS_MOTOR = False
+    AsyncIOMotorDatabase = Any  # type: ignore[assignment, misc]
+    IndexModel = Any  # type: ignore[assignment, misc]
 
 from svc_infra.db.nosql.indexes import normalize_indexes
-from svc_infra.db.nosql.mongo.client import acquire_db, close_mongo, init_mongo, ping_mongo
+from svc_infra.db.nosql.mongo.client import (
+    acquire_db,
+    close_mongo,
+    init_mongo,
+    ping_mongo,
+)
 from svc_infra.db.nosql.resource import NoSqlResource
 from svc_infra.db.nosql.utils import (
     get_mongo_dbname_from_env,
@@ -34,7 +46,8 @@ async def _apply_indexes(
 ) -> list[str]:
     if not indexes:
         return []
-    return await db[collection].create_indexes(list(indexes))
+    result = await db[collection].create_indexes(list(indexes))
+    return cast(list[str], result)
 
 
 # collection + doc used to "lock" the chosen DB name for this app
@@ -48,7 +61,9 @@ async def assert_db_locked(
     registry = db.client.get_database(_REG_DB)
     await registry[_REG_COLL].create_index("service_id", unique=True)
 
-    doc = await registry[_REG_COLL].find_one({"service_id": service_id}, projection={"db_name": 1})
+    doc = await registry[_REG_COLL].find_one(
+        {"service_id": service_id}, projection={"db_name": 1}
+    )
     if doc is None:
         await registry[_REG_COLL].insert_one(
             {"service_id": service_id, "db_name": expected_db_name}
@@ -91,9 +106,13 @@ async def prepare_mongo(
 
     expected_db = get_mongo_dbname_from_env(required=True)
     if db.name != expected_db:
-        raise RuntimeError(f"Connected to Mongo DB '{db.name}', but env says '{expected_db}'.")
+        raise RuntimeError(
+            f"Connected to Mongo DB '{db.name}', but env says '{expected_db}'."
+        )
 
-    await assert_db_locked(db, expected_db, service_id=service_id, allow_rebind=allow_rebind)
+    await assert_db_locked(
+        db, expected_db, service_id=service_id, allow_rebind=allow_rebind
+    )
 
     # collections
     colls = [r.resolved_collection() for r in resources]
@@ -109,7 +128,9 @@ async def prepare_mongo(
             names = await _apply_indexes(db, collection=coll, indexes=idx_models)
             created_idx[coll] = names
 
-    return PrepareResult(ok=True, created_collections=created_colls, created_indexes=created_idx)
+    return PrepareResult(
+        ok=True, created_collections=created_colls, created_indexes=created_idx
+    )
 
 
 def setup_and_prepare(

svc_infra/db/nosql/indexes.py

@@ -66,7 +66,9 @@ def normalize_index(idx: Union[IndexModel, Alias]) -> IndexModel:
     return IndexModel(keys, **kwargs)
 
 
-def normalize_indexes(indexes: Optional[Iterable[Union[IndexModel, Alias]]]) -> List[IndexModel]:
+def normalize_indexes(
+    indexes: Optional[Iterable[Union[IndexModel, Alias]]],
+) -> List[IndexModel]:
     if not indexes:
         return []
     return [normalize_index(i) for i in indexes]

svc_infra/db/nosql/management.py

@@ -83,7 +83,7 @@ def make_document_crud_schemas(
         )
 
     # Backstop encoders in case any exotic types slip through
-    encoders = {ObjectId: str, PyObjectId: str}
+    encoders: dict[type, Any] = {ObjectId: str, PyObjectId: str}
     if json_encoders:
         encoders.update(json_encoders)
 

svc_infra/db/nosql/mongo/README.md

@@ -29,17 +29,17 @@ We provide four CLI commands. You can register them on your Typer app or invoke
 
 ### Commands
 
-- `mongo-scaffold` — create both document **and** CRUD schemas
-- `mongo-scaffold-documents` — create only the **document** model (Pydantic)
-- `mongo-scaffold-schemas` — create only the **CRUD schemas**
-- `mongo-scaffold-resources` — create a starter `resources.py` with a `RESOURCES` list
+- `mongo scaffold` — create both document **and** CRUD schemas
+- `mongo scaffold-documents` — create only the **document** model (Pydantic)
+- `mongo scaffold-schemas` — create only the **CRUD schemas**
+- `mongo scaffold-resources` — create a starter `resources.py` with a `RESOURCES` list
 
 ### Typical usage
 
 #### A) Scaffold documents + schemas together
 
 ```bash
-yourapp mongo-scaffold \
+yourapp mongo scaffold \
   --entity-name Product \
   --documents-dir ./src/your_app/products \
   --schemas-dir ./src/your_app/products \
@@ -57,7 +57,7 @@ src/your_app/products/schemas.py     # ProductRead/ProductCreate/ProductUpdate
 B) Documents only
 
 ```bash
-yourapp mongo-scaffold-documents \
+yourapp mongo scaffold-documents \
   --dest-dir ./src/your_app/products \
   --entity-name Product \
   --documents-filename product_doc.py
@@ -66,7 +66,7 @@ yourapp mongo-scaffold-documents \
 C) Schemas only
 
 ```bash
-yourapp mongo-scaffold-schemas \
+yourapp mongo scaffold-schemas \
   --dest-dir ./src/your_app/products \
   --entity-name Product \
   --schemas-filename product_schemas.py
@@ -75,7 +75,7 @@ yourapp mongo-scaffold-schemas \
 D) Starter resources.py
 
 ```bash
-yourapp mongo-scaffold-resources \
+yourapp mongo scaffold-resources \
   --dest-dir ./src/your_app/mongo \
   --filename resources.py \
   --overwrite
@@ -131,7 +131,7 @@ There are two flavors:
 A) Async, minimal (connect, create collections, apply indexes)
 
 ```bash
-yourapp mongo-prepare \
+yourapp mongo prepare \
   --resources your_app.mongo.resources:RESOURCES \
   --mongo-url "$MONGO_URL" \
   --mongo-db "$MONGO_DB"
@@ -140,7 +140,7 @@ yourapp mongo-prepare \
 B) Synchronous wrapper (end-to-end convenience)
 
 ```bash
-yourapp mongo-setup-and-prepare \
+yourapp mongo setup-and-prepare \
   --resources your_app.mongo.resources:RESOURCES \
   --mongo-url "$MONGO_URL" \
   --mongo-db "$MONGO_DB"
@@ -149,7 +149,7 @@ yourapp mongo-setup-and-prepare \
 You can also ping connectivity:
 
 ```bash
-yourapp mongo-ping --mongo-url "$MONGO_URL" --mongo-db "$MONGO_DB"
+yourapp mongo ping --mongo-url "$MONGO_URL" --mongo-db "$MONGO_DB"
 ```
 
 Behind the scenes, preparation also locks a service ID to a DB name to prevent accidental cross-DB usage. You can pass --allow-rebind if you intentionally move environments.
@@ -430,9 +430,9 @@ NoSqlResource(
 	•	If using explicit schemas with PyObjectId, make sure model_config.json_encoders includes {PyObjectId: str}.
 	•	When using auto-schemas, we expose ObjectId-like fields as str so no custom encoder is needed.
 	•	Connected to wrong DB name
-	•	The system locks a service_id to the DB name once prepared. If you change DBs, run mongo-prepare with --allow-rebind.
+  •	The system locks a service_id to the DB name once prepared. If you change DBs, run `mongo prepare` with --allow-rebind.
 	•	Indexes not created
-	•	Double-check RESOURCES[indexes]. Run mongo-prepare again and inspect the output dictionary of created indexes.
+  •	Double-check RESOURCES[indexes]. Run `mongo prepare` again and inspect the output dictionary of created indexes.
 
 ⸻
 

svc_infra/db/nosql/mongo/client.py

@@ -1,8 +1,15 @@
 from __future__ import annotations
 
-from typing import Optional
+from typing import Any, Optional
 
-from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+try:
+    from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+
+    HAS_MOTOR = True
+except ImportError:  # pragma: no cover
+    HAS_MOTOR = False
+    AsyncIOMotorClient = Any  # type: ignore[assignment, misc]
+    AsyncIOMotorDatabase = Any  # type: ignore[assignment, misc]
 
 from .settings import MongoSettings
 
@@ -10,6 +17,15 @@ _client: Optional[AsyncIOMotorClient] = None
 _db: Optional[AsyncIOMotorDatabase] = None
 
 
+def _require_motor() -> None:
+    """Raise ImportError if motor is not installed."""
+    if not HAS_MOTOR:
+        raise ImportError(
+            "MongoDB support requires the 'motor' package. "
+            "Install with: pip install svc-infra[mongodb]"
+        )
+
+
 def _client_opts(cfg: MongoSettings) -> dict:
     return {
         "appname": cfg.appname,
@@ -20,6 +36,7 @@ def _client_opts(cfg: MongoSettings) -> dict:
 
 
 async def init_mongo(cfg: MongoSettings | None = None) -> AsyncIOMotorDatabase:
+    _require_motor()
     global _client, _db
     cfg = cfg or MongoSettings()
     if _client is None:

svc_infra/db/nosql/mongo/settings.py

@@ -6,8 +6,12 @@ from pydantic import AnyUrl, BaseModel, Field
 
 
 class MongoSettings(BaseModel):
-    url: AnyUrl = Field(default_factory=lambda: os.getenv("MONGO_URL", "mongodb://localhost:27017"))
+    url: AnyUrl = Field(
+        default_factory=lambda: os.getenv("MONGO_URL", "mongodb://localhost:27017")
+    )  # type: ignore[assignment]
     db_name: str = Field(default_factory=lambda: os.getenv("MONGO_DB", ""))
-    appname: str = Field(default_factory=lambda: os.getenv("MONGO_APPNAME", "svc-infra"))
+    appname: str = Field(
+        default_factory=lambda: os.getenv("MONGO_APPNAME", "svc-infra")
+    )
     min_pool_size: int = int(os.getenv("MONGO_MIN_POOL", "0"))
     max_pool_size: int = int(os.getenv("MONGO_MAX_POOL", "100"))