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

svc_infra/cli/cmds/obs/obs_cmds.py

@@ -4,18 +4,22 @@ import os
 import socket
 import subprocess
 from pathlib import Path
+from typing import Any, Callable
 from urllib.parse import urlparse
 
 import typer
 
+from svc_infra.obs.cloud_dash import push_dashboards_from_pkg
+from svc_infra.utils import render_template, write
+
 # --- NEW: load .env automatically (best-effort) ---
+load_dotenv: Callable[..., Any] | None
 try:
-    from dotenv import load_dotenv  # type: ignore
+    from dotenv import load_dotenv as _real_load_dotenv
 except Exception:  # pragma: no cover
     load_dotenv = None
-
-from svc_infra.obs.cloud_dash import push_dashboards_from_pkg
-from svc_infra.utils import render_template, write
+else:
+    load_dotenv = _real_load_dotenv
 
 
 def _run(cmd: list[str], *, env: dict | None = None):
@@ -25,7 +29,9 @@ def _run(cmd: list[str], *, env: dict | None = None):
 def _emit_local_stack(root: Path, metrics_url: str):
     write(
         root / "docker-compose.yml",
-        render_template("svc_infra.obs.providers.grafana.templates", "docker-compose.yml.tmpl", {}),
+        render_template(
+            "svc_infra.obs.providers.grafana.templates", "docker-compose.yml.tmpl", {}
+        ),
     )
     p = urlparse(metrics_url)
     prom_yml = render_template(
@@ -102,7 +108,7 @@ def up():
       - Else → Local mode (Grafana + Prometheus).
     """
     # NEW: load .env once, best-effort, without crashing if package missing
-    if load_dotenv:
+    if load_dotenv is not None:
         try:
             load_dotenv(dotenv_path=Path(".env"), override=False)
         except Exception:
@@ -110,7 +116,9 @@ def up():
 
     root = Path(".obs")
     root.mkdir(exist_ok=True)
-    metrics_url = os.getenv("SVC_INFRA_METRICS_URL", "http://host.docker.internal:8000/metrics")
+    metrics_url = os.getenv(
+        "SVC_INFRA_METRICS_URL", "http://host.docker.internal:8000/metrics"
+    )
 
     cloud_url = os.getenv("GRAFANA_CLOUD_URL", "").strip()
     cloud_token = os.getenv("GRAFANA_CLOUD_TOKEN", "").strip()
@@ -131,7 +139,14 @@ def up():
         ):
             _emit_local_agent(root, metrics_url)
             _run(
-                ["docker", "compose", "-f", str(root / "docker-compose.cloud.yml"), "up", "-d"],
+                [
+                    "docker",
+                    "compose",
+                    "-f",
+                    str(root / "docker-compose.cloud.yml"),
+                    "up",
+                    "-d",
+                ],
                 env=os.environ.copy(),
             )
             typer.echo("[cloud] local Grafana Agent started (pushing metrics to Cloud)")
@@ -146,7 +161,10 @@ def up():
     env["GRAFANA_PORT"] = str(local_graf)
     env["PROM_PORT"] = str(local_prom)
     _emit_local_stack(root, metrics_url)
-    _run(["docker", "compose", "-f", str(root / "docker-compose.yml"), "up", "-d"], env=env)
+    _run(
+        ["docker", "compose", "-f", str(root / "docker-compose.yml"), "up", "-d"],
+        env=env,
+    )
     typer.echo(f"Local Grafana → http://localhost:{local_graf}  (admin/admin)")
     typer.echo(f"Local Prometheus → http://localhost:{local_prom}")
 
@@ -155,11 +173,13 @@ def down():
     root = Path(".obs")
     if (root / "docker-compose.yml").exists():
         subprocess.run(
-            ["docker", "compose", "-f", str(root / "docker-compose.yml"), "down"], check=False
+            ["docker", "compose", "-f", str(root / "docker-compose.yml"), "down"],
+            check=False,
         )
     if (root / "docker-compose.cloud.yml").exists():
         subprocess.run(
-            ["docker", "compose", "-f", str(root / "docker-compose.cloud.yml"), "down"], check=False
+            ["docker", "compose", "-f", str(root / "docker-compose.cloud.yml"), "down"],
+            check=False,
         )
     typer.echo("Stopped local obs services.")
 
@@ -171,7 +191,7 @@ def scaffold(target: str = typer.Option(..., help="compose|railway|k8s|fly")):
     out.mkdir(parents=True, exist_ok=True)
 
     base = files("svc_infra.obs.templates.sidecars").joinpath(target)
-    for p in base.rglob("*"):
+    for p in base.rglob("*"):  # type: ignore[attr-defined]
         if p.is_file():
             rel = p.relative_to(base)
             dst = out / rel
@@ -182,6 +202,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,112 @@
+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/cli/foundation/runner.py

@@ -25,7 +25,9 @@ def candidate_cmds(root: Path, prog: str, argv: List[str]) -> List[List[str]]:
         cmds.append([prog, *argv])
 
     py = shutil.which("python3") or shutil.which("python") or "python"
-    module = prog.replace("-", "_") + ".cli_shim"  # e.g., svc-infra -> svc_infra.cli_shim
+    module = (
+        prog.replace("-", "_") + ".cli_shim"
+    )  # e.g., svc-infra -> svc_infra.cli_shim
     cmds.append([py, "-m", module, *argv])
 
     return cmds
@@ -54,4 +56,6 @@ async def run_from_root(root: Path, prog: str, argv: List[str]) -> str:
         except Exception as e:
             last_exc = e
             continue
-    raise RuntimeError(f"All runners failed in {root} for: {prog} {' '.join(argv)}") from last_exc
+    raise RuntimeError(
+        f"All runners failed in {root} for: {prog} {' '.join(argv)}"
+    ) from last_exc

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 with_payments is not None else False,
+            )
+        if on_load_fixtures:
+            res = on_load_fixtures()
+            if inspect.isawaitable(res):
+                await res
+
+    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,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",