svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/cli/cmds/jobs/jobs_cmds.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.jobs.loader import schedule_from_env
+from svc_infra.jobs.worker import process_one
+
+app = typer.Typer(help="Background jobs and scheduler commands")
+
+
+@app.command("run")
+def run(
+    poll_interval: float = typer.Option(0.5, help="Sleep seconds between loops when idle"),
+    max_loops: Optional[int] = typer.Option(None, help="Max loops before exit (for tests)"),
+):
+    """Run scheduler ticks and process jobs in a simple loop."""
+
+    queue, scheduler = easy_jobs()
+    # load schedule from env JSON if provided
+    schedule_from_env(scheduler)
+
+    async def _loop():
+        loops = 0
+        while True:
+            await scheduler.tick()
+            processed = await process_one(queue, _noop_handler)
+            if not processed:
+                # idle
+                await asyncio.sleep(poll_interval)
+            if max_loops is not None:
+                loops += 1
+                if loops >= max_loops:
+                    break
+
+    async def _noop_handler(job):
+        # Default handler does nothing; users should write their own runners
+        return None
+
+    asyncio.run(_loop())

svc_infra/cli/cmds/obs/obs_cmds.py

@@ -182,6 +182,7 @@ def scaffold(target: str = typer.Option(..., help="compose|railway|k8s|fly")):
 
 
 def register(app: typer.Typer) -> None:
-    app.command("obs-up")(up)
-    app.command("obs-down")(down)
-    app.command("obs-scaffold")(scaffold)
+    # Attach to 'obs' group app
+    app.command("up")(up)
+    app.command("down")(down)
+    app.command("scaffold")(scaffold)

svc_infra/cli/cmds/sdk/sdk_cmds.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import subprocess
+
+import typer
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="Generate SDKs from OpenAPI.")
+
+
+def _echo(cmd: list[str]):
+    typer.echo("$ " + " ".join(cmd))
+
+
+def _parse_bool(val: str | bool | None, default: bool = True) -> bool:
+    if isinstance(val, bool):
+        return val
+    if val is None:
+        return default
+    s = str(val).strip().lower()
+    if s in {"1", "true", "yes", "y"}:
+        return True
+    if s in {"0", "false", "no", "n"}:
+        return False
+    return default
+
+
+@app.command("ts")
+def sdk_ts(
+    openapi: str = typer.Argument(..., help="Path to OpenAPI JSON"),
+    outdir: str = typer.Option("sdk-ts", help="Output directory"),
+    dry_run: str = typer.Option("true", help="Print commands instead of running (true/false)"),
+):
+    """Generate a TypeScript SDK (openapi-typescript-codegen as default)."""
+    cmd = [
+        "npx",
+        "openapi-typescript-codegen",
+        "--input",
+        openapi,
+        "--output",
+        outdir,
+    ]
+    if _parse_bool(dry_run, True):
+        _echo(cmd)
+        return
+    subprocess.check_call(cmd)
+    typer.secho(f"TS SDK generated → {outdir}", fg=typer.colors.GREEN)
+
+
+@app.command("py")
+def sdk_py(
+    openapi: str = typer.Argument(..., help="Path to OpenAPI JSON"),
+    outdir: str = typer.Option("sdk-py", help="Output directory"),
+    package_name: str = typer.Option("client_sdk", help="Python package name"),
+    dry_run: str = typer.Option("true", help="Print commands instead of running (true/false)"),
+):
+    """Generate a Python SDK via openapi-generator-cli with "python" generator."""
+    cmd = [
+        "npx",
+        "-y",
+        "@openapitools/openapi-generator-cli",
+        "generate",
+        "-i",
+        openapi,
+        "-g",
+        "python",
+        "-o",
+        outdir,
+        "--additional-properties",
+        f"packageName={package_name}",
+    ]
+    if _parse_bool(dry_run, True):
+        _echo(cmd)
+        return
+    subprocess.check_call(cmd)
+    typer.secho(f"Python SDK generated → {outdir}", fg=typer.colors.GREEN)
+
+
+@app.command("postman")
+def sdk_postman(
+    openapi: str = typer.Argument(..., help="Path to OpenAPI JSON"),
+    out: str = typer.Option("postman_collection.json", help="Output Postman collection"),
+    dry_run: str = typer.Option("true", help="Print commands instead of running (true/false)"),
+):
+    """Convert OpenAPI to a Postman collection via openapi-to-postmanv2."""
+    cmd = [
+        "npx",
+        "-y",
+        "openapi-to-postmanv2",
+        "-s",
+        openapi,
+        "-o",
+        out,
+    ]
+    if _parse_bool(dry_run, True):
+        _echo(cmd)
+        return
+    subprocess.check_call(cmd)
+    typer.secho(f"Postman collection generated → {out}", fg=typer.colors.GREEN)
+
+
+def register(root: typer.Typer):
+    root.add_typer(app, name="sdk")

svc_infra/data/add.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import inspect
+from typing import Callable, Iterable, Optional
+
+from fastapi import FastAPI
+
+from svc_infra.cli.cmds.db.sql.alembic_cmds import cmd_setup_and_migrate
+
+
+def add_data_lifecycle(
+    app: FastAPI,
+    *,
+    auto_migrate: bool = True,
+    database_url: str | None = None,
+    discover_packages: Optional[list[str]] = None,
+    with_payments: bool | None = None,
+    on_load_fixtures: Optional[Callable[[], None]] = None,
+    retention_jobs: Optional[Iterable[Callable[[], None]]] = None,
+    erasure_job: Optional[Callable[[str], None]] = None,
+) -> None:
+    """
+    Wire data lifecycle conveniences:
+
+    - auto_migrate: run end-to-end Alembic setup-and-migrate on startup (idempotent).
+    - on_load_fixtures: optional callback to load reference/fixture data once at startup.
+    - retention_jobs: optional list of callables to register purge tasks (scheduler integration is external).
+    - erasure_job: optional callable to trigger a GDPR erasure workflow for a given principal ID.
+
+    This helper is intentionally minimal: it coordinates existing building blocks
+    and offers extension points. Jobs should be scheduled using svc_infra.jobs helpers.
+    """
+
+    async def _run_lifecycle() -> None:
+        # Startup
+        if auto_migrate:
+            cmd_setup_and_migrate(
+                database_url=database_url,
+                overwrite_scaffold=False,
+                create_db_if_missing=True,
+                create_followup_revision=True,
+                initial_message="initial schema",
+                followup_message="autogen",
+                discover_packages=discover_packages,
+                with_payments=with_payments,
+            )
+        if on_load_fixtures:
+            res = on_load_fixtures()
+            if inspect.isawaitable(res):
+                await res  # type: ignore[misc]
+
+    app.add_event_handler("startup", _run_lifecycle)
+
+    # Store optional jobs on app.state for external schedulers to discover/register.
+    if retention_jobs is not None:
+        app.state.data_retention_jobs = list(retention_jobs)
+    if erasure_job is not None:
+        app.state.data_erasure_job = erasure_job
+
+
+__all__ = ["add_data_lifecycle"]

svc_infra/data/backup.py

@@ -0,0 +1,53 @@
+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  # type: ignore[misc]
+        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,40 @@
+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):  # type: ignore[arg-type]
+            await res  # type: ignore[misc]
+    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,55 @@
+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)  # type: ignore[operator]
+
+    # 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})  # type: ignore[attr-defined]
+        res = await session.execute(stmt)
+        return getattr(res, "rowcount", 0)
+
+    # Hard delete fallback
+    stmt = m.delete().where(*where)  # type: ignore[attr-defined]
+    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/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/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/outbox.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Optional, Protocol
+
+
+@dataclass
+class OutboxMessage:
+    id: int
+    topic: str
+    payload: Dict[str, Any]
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    attempts: int = 0
+    processed_at: Optional[datetime] = None
+
+
+class OutboxStore(Protocol):
+    def enqueue(self, topic: str, payload: Dict[str, Any]) -> OutboxMessage:
+        pass
+
+    def fetch_next(self, *, topics: Optional[Iterable[str]] = None) -> Optional[OutboxMessage]:
+        """Return the next undispatched, unprocessed message (FIFO per-topic), or None.
+
+        Notes:
+        - Messages with attempts > 0 are considered "dispatched" to the job queue and won't be re-enqueued.
+        - Delivery retries are handled by the job queue worker, not by re-reading the outbox.
+        """
+        pass
+
+    def mark_processed(self, msg_id: int) -> None:
+        pass
+
+    def mark_failed(self, msg_id: int) -> None:
+        pass
+
+
+class InMemoryOutboxStore:
+    """Simple in-memory outbox for tests and local runs."""
+
+    def __init__(self):
+        self._seq = 0
+        self._messages: List[OutboxMessage] = []
+
+    def enqueue(self, topic: str, payload: Dict[str, Any]) -> OutboxMessage:
+        self._seq += 1
+        msg = OutboxMessage(id=self._seq, topic=topic, payload=dict(payload))
+        self._messages.append(msg)
+        return msg
+
+    def fetch_next(self, *, topics: Optional[Iterable[str]] = None) -> Optional[OutboxMessage]:
+        allowed = set(topics) if topics else None
+        for msg in self._messages:
+            if msg.processed_at is not None:
+                continue
+            # skip already dispatched messages (attempts>0)
+            if msg.attempts > 0:
+                continue
+            if allowed is not None and msg.topic not in allowed:
+                continue
+            return msg
+        return None
+
+    def mark_processed(self, msg_id: int) -> None:
+        for msg in self._messages:
+            if msg.id == msg_id:
+                msg.processed_at = datetime.now(timezone.utc)
+                return
+
+    def mark_failed(self, msg_id: int) -> None:
+        for msg in self._messages:
+            if msg.id == msg_id:
+                msg.attempts += 1
+                return
+
+
+class SqlOutboxStore:
+    """Skeleton for a SQL-backed outbox store.
+
+    Implementations should:
+    - INSERT on enqueue
+    - SELECT FOR UPDATE SKIP LOCKED (or equivalent) to fetch next
+    - UPDATE processed_at (and attempts on failure)
+    """
+
+    def __init__(self, session_factory):
+        self._session_factory = session_factory
+
+    # Placeholders to outline the API; not implemented here.
+    def enqueue(
+        self, topic: str, payload: Dict[str, Any]
+    ) -> OutboxMessage:  # pragma: no cover - skeleton
+        raise NotImplementedError
+
+    def fetch_next(
+        self, *, topics: Optional[Iterable[str]] = None
+    ) -> Optional[OutboxMessage]:  # pragma: no cover - skeleton
+        raise NotImplementedError
+
+    def mark_processed(self, msg_id: int) -> None:  # pragma: no cover - skeleton
+        raise NotImplementedError
+
+    def mark_failed(self, msg_id: int) -> None:  # pragma: no cover - skeleton
+        raise NotImplementedError

svc_infra/db/sql/apikey.py

@@ -40,7 +40,7 @@ def get_apikey_model() -> type:
 def bind_apikey_model(user_model: Type, *, table_name: str = "api_keys") -> type:
     """
     Create and register an ApiKey model bound to the provided user_model and table name.
-    Call this once during app boot (e.g., inside add_auth when enable_api_keys=True).
+    Call this once during app boot (e.g., inside add_auth_users when enable_api_keys=True).
     """
 
     class ApiKey(ModelBase):  # type: ignore[misc, valid-type]