svc-infra 0.1.600__py3-none-any.whl → 0.1.640__py3-none-any.whl

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/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/sql/repository.py

@@ -56,20 +56,31 @@ class SqlRepository:
         limit: int,
         offset: int,
         order_by: Optional[Sequence[Any]] = None,
+        where: Optional[Sequence[Any]] = None,
     ) -> Sequence[Any]:
-        stmt = self._base_select().limit(limit).offset(offset)
+        stmt = self._base_select()
+        if where:
+            stmt = stmt.where(and_(*where))
+        stmt = stmt.limit(limit).offset(offset)
         if order_by:
             stmt = stmt.order_by(*order_by)
         rows = (await session.execute(stmt)).scalars().all()
         return rows
 
-    async def count(self, session: AsyncSession) -> int:
-        stmt = select(func.count()).select_from(self._base_select().subquery())
+    async def count(self, session: AsyncSession, *, where: Optional[Sequence[Any]] = None) -> int:
+        base = self._base_select()
+        if where:
+            base = base.where(and_(*where))
+        stmt = select(func.count()).select_from(base.subquery())
         return (await session.execute(stmt)).scalar_one()
 
-    async def get(self, session: AsyncSession, id_value: Any) -> Any | None:
+    async def get(
+        self, session: AsyncSession, id_value: Any, *, where: Optional[Sequence[Any]] = None
+    ) -> Any | None:
         # honors soft-delete if configured
         stmt = self._base_select().where(self._id_column() == id_value)
+        if where:
+            stmt = stmt.where(and_(*where))
         return (await session.execute(stmt)).scalars().first()
 
     async def create(self, session: AsyncSession, data: dict[str, Any]) -> Any:
@@ -78,12 +89,18 @@ class SqlRepository:
         obj = self.model(**filtered)
         session.add(obj)
         await session.flush()
+        await session.refresh(obj)
         return obj
 
     async def update(
-        self, session: AsyncSession, id_value: Any, data: dict[str, Any]
+        self,
+        session: AsyncSession,
+        id_value: Any,
+        data: dict[str, Any],
+        *,
+        where: Optional[Sequence[Any]] = None,
     ) -> Any | None:
-        obj = await self.get(session, id_value)
+        obj = await self.get(session, id_value, where=where)
         if not obj:
             return None
         valid = self._model_columns()
@@ -91,17 +108,28 @@ class SqlRepository:
             if k in valid and k not in self.immutable_fields:
                 setattr(obj, k, v)
         await session.flush()
+        await session.refresh(obj)
         return obj
 
-    async def delete(self, session: AsyncSession, id_value: Any) -> bool:
-        obj = await session.get(self.model, id_value)
+    async def delete(
+        self, session: AsyncSession, id_value: Any, *, where: Optional[Sequence[Any]] = None
+    ) -> bool:
+        # Fast path: when no extra filters provided, use session.get for simplicity (matches tests)
+        if not where:
+            obj = await session.get(self.model, id_value)
+        else:
+            # Respect soft-delete and optional tenant/extra filters by selecting through base select
+            stmt = self._base_select().where(self._id_column() == id_value)
+            stmt = stmt.where(and_(*where))
+            obj = (await session.execute(stmt)).scalars().first()
         if not obj:
             return False
         if self.soft_delete:
             # Prefer timestamp, also optionally set flag to False
-            if hasattr(self.model, self.soft_delete_field):
+            # Check attributes on the instance to support test doubles without class-level fields
+            if hasattr(obj, self.soft_delete_field):
                 setattr(obj, self.soft_delete_field, func.now())
-            if self.soft_delete_flag_field and hasattr(self.model, self.soft_delete_flag_field):
+            if self.soft_delete_flag_field and hasattr(obj, self.soft_delete_flag_field):
                 setattr(obj, self.soft_delete_flag_field, False)
             await session.flush()
             return True
@@ -118,6 +146,7 @@ class SqlRepository:
         limit: int,
         offset: int,
         order_by: Optional[Sequence[Any]] = None,
+        where: Optional[Sequence[Any]] = None,
     ) -> Sequence[Any]:
         ilike = f"%{q}%"
         conditions = []
@@ -130,6 +159,8 @@ class SqlRepository:
                     # skip columns that cannot be used in ilike even with cast
                     continue
         stmt = self._base_select()
+        if where:
+            stmt = stmt.where(and_(*where))
         if conditions:
             stmt = stmt.where(or_(*conditions))
         stmt = stmt.limit(limit).offset(offset)
@@ -137,7 +168,14 @@ class SqlRepository:
             stmt = stmt.order_by(*order_by)
         return (await session.execute(stmt)).scalars().all()
 
-    async def count_filtered(self, session: AsyncSession, *, q: str, fields: Sequence[str]) -> int:
+    async def count_filtered(
+        self,
+        session: AsyncSession,
+        *,
+        q: str,
+        fields: Sequence[str],
+        where: Optional[Sequence[Any]] = None,
+    ) -> int:
         ilike = f"%{q}%"
         conditions = []
         for f in fields:
@@ -148,6 +186,8 @@ class SqlRepository:
                 except Exception:
                     continue
         stmt = self._base_select()
+        if where:
+            stmt = stmt.where(and_(*where))
         if conditions:
             stmt = stmt.where(or_(*conditions))
         # SELECT COUNT(*) FROM (<stmt>) as t

svc_infra/db/sql/resource.py

@@ -34,3 +34,8 @@ class SqlResource:
 
     # Only a type reference; no runtime dependency on FastAPI layer
     service_factory: Optional[Callable[[SqlRepository], "SqlService"]] = None
+
+    # Tenancy
+    tenant_field: Optional[str] = (
+        None  # when set, CRUD router will require TenantId and scope by field
+    )

svc_infra/db/sql/templates/setup/env_async.py.tmpl

@@ -177,8 +177,16 @@ def _collect_metadata() -> list[object]:
                 if name not in pkgs:
                     pkgs.append(name)
 
+    # Only attempt bare 'models' import if it is discoverable to avoid noisy tracebacks
     if "models" not in pkgs:
-        pkgs.append("models")
+        try:
+            spec = getattr(importlib, "util", None)
+            if spec is not None and getattr(spec, "find_spec", None) is not None:
+                if spec.find_spec("models") is not None:
+                    pkgs.append("models")
+        except Exception:
+            # Best-effort; if discovery fails, skip adding bare 'models'
+            pass
 
     def _import_and_collect(modname: str):
         try:

svc_infra/db/sql/templates/setup/env_sync.py.tmpl

@@ -191,9 +191,16 @@ def _collect_metadata() -> list[object]:
                 if name not in pkgs:
                     pkgs.append(name)
 
-    # Always also try a bare 'models'
+    # Only attempt a bare 'models' import if discoverable to avoid noisy tracebacks
     if "models" not in pkgs:
-        pkgs.append("models")
+        try:
+            spec = getattr(importlib, "util", None)
+            if spec is not None and getattr(spec, "find_spec", None) is not None:
+                if spec.find_spec("models") is not None:
+                    pkgs.append("models")
+        except Exception:
+            # If discovery fails, skip adding bare 'models'
+            pass
 
     def _import_and_collect(modname: str):
         try:

svc_infra/db/sql/tenant.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .service import SqlService
+
+
+class TenantSqlService(SqlService):
+    """
+    SQL service wrapper that automatically scopes operations to a tenant.
+
+    - Adds a where filter (model.tenant_field == tenant_id) for list/get/update/delete/search/count.
+    - On create, if the model has the tenant field and it's not set in data, injects tenant_id.
+    """
+
+    def __init__(self, repo, *, tenant_id: str, tenant_field: str = "tenant_id"):
+        super().__init__(repo)
+        self.tenant_id = tenant_id
+        self.tenant_field = tenant_field
+
+    def _where(self) -> Sequence[Any]:
+        model = self.repo.model
+        col = getattr(model, self.tenant_field, None)
+        if col is None:
+            return []
+        return [col == self.tenant_id]
+
+    async def list(self, session: AsyncSession, *, limit: int, offset: int, order_by=None):
+        return await self.repo.list(
+            session, limit=limit, offset=offset, order_by=order_by, where=self._where()
+        )
+
+    async def count(self, session: AsyncSession) -> int:
+        return await self.repo.count(session, where=self._where())
+
+    async def get(self, session: AsyncSession, id_value: Any):
+        return await self.repo.get(session, id_value, where=self._where())
+
+    async def create(self, session: AsyncSession, data: dict[str, Any]):
+        data = await self.pre_create(data)
+        # inject tenant_id if model supports it and value missing
+        if self.tenant_field in self.repo._model_columns() and self.tenant_field not in data:
+            data[self.tenant_field] = self.tenant_id
+        return await self.repo.create(session, data)
+
+    async def update(self, session: AsyncSession, id_value: Any, data: dict[str, Any]):
+        data = await self.pre_update(data)
+        return await self.repo.update(session, id_value, data, where=self._where())
+
+    async def delete(self, session: AsyncSession, id_value: Any) -> bool:
+        return await self.repo.delete(session, id_value, where=self._where())
+
+    async def search(
+        self,
+        session: AsyncSession,
+        *,
+        q: str,
+        fields: Sequence[str],
+        limit: int,
+        offset: int,
+        order_by=None,
+    ):
+        return await self.repo.search(
+            session,
+            q=q,
+            fields=fields,
+            limit=limit,
+            offset=offset,
+            order_by=order_by,
+            where=self._where(),
+        )
+
+    async def count_filtered(self, session: AsyncSession, *, q: str, fields: Sequence[str]) -> int:
+        return await self.repo.count_filtered(session, q=q, fields=fields, where=self._where())
+
+
+__all__ = ["TenantSqlService"]

svc_infra/db/sql/utils.py

@@ -196,10 +196,17 @@ def _ensure_timeout_default(u: URL) -> URL:
     """
     Ensure a conservative connection timeout is present for libpq-based drivers.
     For psycopg/psycopg2, 'connect_timeout' is honored via the query string.
+    For asyncpg, timeout is set via connect_args (not query string).
     """
     backend = (u.get_backend_name() or "").lower()
     if backend not in ("postgresql", "postgres"):
         return u
+
+    # asyncpg doesn't support connect_timeout in query string - use connect_args instead
+    dn = (u.drivername or "").lower()
+    if "+asyncpg" in dn:
+        return u
+
     if "connect_timeout" in u.query:
         return u
     # Default 10s unless overridden
@@ -337,9 +344,8 @@ def _ensure_ssl_default(u: URL) -> URL:
     mode = (mode_env or "").strip()
 
     if "+asyncpg" in driver:
-        # asyncpg: use 'ssl=true' (SQLAlchemy forwards to asyncpg)
-        if "ssl" not in u.query:
-            return u.set(query={**u.query, "ssl": "true"})
+        # asyncpg: SSL is handled in connect_args in build_engine(), not in URL query
+        # Do not add ssl parameter to URL query for asyncpg
         return u
     else:
         # libpq-based drivers: use sslmode (default 'require' for hosted PG)
@@ -382,10 +388,18 @@ def build_engine(url: URL | str, echo: bool = False) -> Union[SyncEngine, AsyncE
                 "Async driver URL provided but SQLAlchemy async extras are not available."
             )
 
-        # asyncpg: honor connection timeout
+        # asyncpg: honor connection timeout only (NOT connect_timeout)
         if "+asyncpg" in (u.drivername or ""):
             connect_args["timeout"] = int(os.getenv("DB_CONNECT_TIMEOUT", "10"))
 
+            # asyncpg doesn't accept sslmode or ssl=true in query params
+            # Remove these and set ssl='require' in connect_args
+            if "ssl" in u.query or "sslmode" in u.query:
+                new_query = {k: v for k, v in u.query.items() if k not in ("ssl", "sslmode")}
+                u = u.set(query=new_query)
+            # Set ssl in connect_args - 'require' is safest for hosted databases
+            connect_args["ssl"] = "require"
+
         # NEW: aiomysql SSL default
         if "+aiomysql" in (u.drivername or "") and not any(
             k in u.query for k in ("ssl", "ssl_ca", "sslmode")

svc_infra/docs/acceptance-matrix.md

@@ -0,0 +1,71 @@
+# Acceptance Matrix (A-IDs)
+
+This document maps Acceptance scenarios (A-IDs) to endpoints, CLIs, fixtures, and seed data. Use it to drive the CI promotion gate and local `make accept` runs.
+
+## A0. Harness
+- Stack: docker-compose.test.yml (api, db, redis)
+- Makefile targets: accept, compose_up, wait, seed, down
+- Tests bootstrap: tests/acceptance/conftest.py (BASE_URL), _auth.py, _seed.py, _http.py
+
+## A1. Security & Auth
+- A1-01 Register → Verify → Login → /auth/me
+  - Endpoints: POST /auth/register, POST /auth/verify, POST /auth/login, GET /auth/me
+  - Fixtures: admin, user
+- A1-02 Password policy & breach check
+  - Endpoints: POST /auth/register
+- A1-03 Lockout escalation and cooldown
+  - Endpoints: POST /auth/login
+- A1-04 RBAC/ABAC enforced
+  - Endpoints: GET /admin/*, resource GET with owner guard
+- A1-05 Session list & revoke
+  - Endpoints: GET/DELETE /auth/sessions
+- A1-06 API keys lifecycle
+  - Endpoints: POST/GET/DELETE /auth/api-keys, usage via Authorization header
+- A1-07 MFA lifecycle
+  - Endpoints: /auth/mfa/*
+
+## A2. Rate Limiting
+- A2-01 Global limit → 429 with Retry-After
+- A2-02 Per-route & tenant override honored
+- A2-03 Window reset
+
+## A3. Idempotency & Concurrency
+- A3-01 Same Idempotency-Key → identical 2xx
+- A3-02 Conflicting payload + same key → 409
+- A3-03 Optimistic lock mismatch → 409; success increments version
+
+## A4. Jobs & Scheduling
+- A4-01 Custom job consumed
+- A4-02 Backoff & DLQ
+- A4-03 Cron tick observed
+
+## A5. Webhooks
+- A5-01 Producer → delivery (HMAC verified)
+- A5-02 Retry stops on success
+- A5-03 Secret rotation window accepts old+new
+
+## A6. Tenancy
+- A6-01 tenant_id injected on create; list scoped
+- A6-02 Cross-tenant → 404/403
+- A6-03 Per-tenant quotas enforced
+
+## A7. Data Lifecycle
+- A7-01 Soft delete hides; undelete restores
+- A7-02 GDPR erasure steps with audit
+- A7-03 Retention purge soft→hard
+- A7-04 Backup verification healthy
+
+## A8. SLOs & Ops
+- A8-01 Metrics http_server_* and db_pool_* present
+- A8-02 Maintenance mode 503; circuit breaker trips/recover
+- A8-03 Liveness/readiness under DB up/down
+
+## A9. OpenAPI & Error Contracts
+- A9-01 /openapi.json valid; examples present
+- A9-02 Problem+JSON conforms
+- A9-03 Spectral + API Doctor pass
+
+## A10. CLI & DX
+- A10-01 DB migrate/rollback/seed
+- A10-02 Jobs runner consumes a sample job
+- A10-03 SDK smoke-import and /ping

svc_infra/docs/acceptance.md

@@ -0,0 +1,44 @@
+# Pre-Deploy Acceptance (Promotion Gate)
+
+This guide describes the acceptance harness that runs post-build against an ephemeral stack. Artifacts are promoted only if acceptance checks pass.
+
+## Stack
+- docker-compose.test.yml: api (uvicorn serving tests.acceptance.app), optional db/redis (via profiles), and a tester container to run pytest inside
+- Makefile targets: accept, compose_up, wait, seed, down
+- Health probes: /healthz (liveness), /readyz (readiness), /startupz (startup)
+
+## Workflow
+1. Build image
+2. docker compose up -d (test stack)
+3. CLI DB checks & seed: run `sql setup-and-migrate`, `sql current`, `sql downgrade -1`, `sql upgrade head` against an ephemeral SQLite DB, then call `sql seed tests.acceptance._seed:acceptance_seed` (no-op by default)
+4. Run pytest inside tester: docker compose run --rm tester (Makefile wires this)
+5. OpenAPI lint & API Doctor
+6. Teardown
+
+## Supply-chain & Matrix (v1 scope)
+- SBOM: generate and upload as artifact; image scan (Trivy/Grype) with severity gate.
+- Provenance: sign/attest images (cosign/SLSA) on best-effort basis.
+- Backend matrix: run acceptance against two stacks via COMPOSE_PROFILES:
+	1) in-memory stores (default), 2) Redis + Postgres (COMPOSE_PROFILES=pg-redis).
+
+## Additional Acceptance Checks (fast wins)
+- Headers/CORS: assert HSTS, X-Content-Type-Options, Referrer-Policy, X-Frame-Options/SameSite; OPTIONS preflight behavior.
+- Resilience: restart DB/Redis during request; expect breaker trip and recovery.
+- DR drill: restore a tiny SQL dump then run smoke.
+- OpenAPI invariants: no orphan routes; servers block correctness for versions; 100% examples for public JSON; stable operationIds; reject /auth/{id} path via lint rule.
+- CLI contracts: `svc-infra --help` and key subcommands exit 0 and print expected flags.
+
+## Local usage
+- make accept (runs the full flow locally)
+- make down (tears down the stack)
+- To run tests manually: docker compose run --rm tester
+- To target a different backend: COMPOSE_PROFILES=pg-redis make accept
+
+## Files
+- tests/acceptance/conftest.py: BASE_URL, httpx client, fixtures
+- tests/acceptance/_auth.py: login/register helpers
+- tests/acceptance/_seed.py: seed users/tenants/api keys
+- tests/acceptance/_http.py: HTTP helpers
+
+## Scenarios
+See docs/acceptance-matrix.md for A-IDs and mapping to endpoints.