svc-infra 0.1.601__py3-none-any.whl → 0.1.602__py3-none-any.whl

svc_infra/api/fastapi/docs/add.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI
+
+
+def add_docs(
+    app: FastAPI,
+    *,
+    redoc_url: str = "/redoc",
+    swagger_url: str = "/docs",
+    openapi_url: str = "/openapi.json",
+    export_openapi_to: Optional[str] = None,
+) -> None:
+    """Enable docs endpoints and optionally export OpenAPI schema to disk on startup."""
+    # Configure FastAPI docs URLs
+    app.docs_url = swagger_url
+    app.redoc_url = redoc_url
+    app.openapi_url = openapi_url
+
+    if export_openapi_to:
+        export_path = Path(export_openapi_to)
+
+        @app.on_event("startup")
+        async def _export_spec() -> None:  # noqa: ANN202
+            spec = app.openapi()
+            export_path.parent.mkdir(parents=True, exist_ok=True)
+            export_path.write_text(json.dumps(spec, indent=2))
+
+
+def add_sdk_generation_stub(
+    app: FastAPI,
+    *,
+    on_generate: Optional[callable] = None,
+    openapi_path: str = "/openapi.json",
+) -> None:
+    """Hook to add an SDK generation stub.
+
+    Provide `on_generate()` to run generation (e.g., openapi-generator). This is a stub only; we
+    don't ship a hard dependency. If `on_generate` is provided, we expose `/_docs/generate-sdk`.
+    """
+    from svc_infra.api.fastapi.dual.public import public_router
+
+    if not on_generate:
+        return
+
+    router = public_router(prefix="/_docs", include_in_schema=False)
+
+    @router.post("/generate-sdk")
+    async def _generate() -> dict:  # noqa: ANN201
+        on_generate()
+        return {"status": "ok"}
+
+    app.include_router(router)
+
+
+__all__ = ["add_docs", "add_sdk_generation_stub"]

svc_infra/api/fastapi/ops/add.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+from typing import Callable
+
+from fastapi import FastAPI, HTTPException, Request
+from starlette.responses import JSONResponse
+
+
+def add_probes(
+    app: FastAPI,
+    *,
+    prefix: str = "/_ops",
+    include_in_schema: bool = False,
+) -> None:
+    """Mount basic liveness/readiness/startup probes under prefix."""
+    from svc_infra.api.fastapi.dual.public import public_router
+
+    router = public_router(prefix=prefix, tags=["ops"], include_in_schema=include_in_schema)
+
+    @router.get("/live")
+    async def live() -> JSONResponse:  # noqa: D401, ANN201
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/ready")
+    async def ready() -> JSONResponse:  # noqa: D401, ANN201
+        # In the future, add checks (DB ping, cache ping) via DI hooks.
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/startup")
+    async def startup_probe() -> JSONResponse:  # noqa: D401, ANN201
+        return JSONResponse({"status": "ok"})
+
+    app.include_router(router)
+
+
+def add_maintenance_mode(app: FastAPI, *, env_var: str = "MAINTENANCE_MODE") -> None:
+    """Enable a simple maintenance gate controlled by an env var.
+
+    When MAINTENANCE_MODE is truthy, all non-GET requests return 503.
+    """
+
+    @app.middleware("http")
+    async def _maintenance_gate(request: Request, call_next):  # noqa: ANN001, ANN202
+        flag = str(os.getenv(env_var, "")).lower() in {"1", "true", "yes", "on"}
+        if flag and request.method not in {"GET", "HEAD", "OPTIONS"}:
+            return JSONResponse({"detail": "maintenance"}, status_code=503)
+        return await call_next(request)
+
+
+def circuit_breaker_dependency(limit: int = 100, window_seconds: int = 60) -> Callable:
+    """Return a dependency that can trip rejective errors based on external metrics.
+
+    This is a placeholder; callers can swap with a provider that tracks failures and opens the
+    breaker. Here, we read an env var to simulate an open breaker.
+    """
+
+    async def _dep(_: Request) -> None:  # noqa: D401, ANN202
+        if str(os.getenv("CIRCUIT_OPEN", "")).lower() in {"1", "true", "yes", "on"}:
+            raise HTTPException(status_code=503, detail="circuit open")
+
+    return _dep
+
+
+__all__ = ["add_probes", "add_maintenance_mode", "circuit_breaker_dependency"]

svc_infra/data/add.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+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.
+    """
+
+    @app.on_event("startup")
+    async def _data_lifecycle_startup() -> None:  # noqa: D401, ANN202
+        if auto_migrate:
+            # Use existing CLI function to perform end-to-end setup and 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:
+            # Run user-provided fixture loader (idempotent expected).
+            on_load_fixtures()
+
+    # 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/dx/add.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def write_ci_workflow(
+    *,
+    target_dir: str | Path,
+    name: str = "ci.yml",
+    python_version: str = "3.12",
+) -> Path:
+    """Write a minimal CI workflow file (GitHub Actions) with tests/lint/type steps."""
+    p = Path(target_dir) / ".github" / "workflows" / name
+    p.parent.mkdir(parents=True, exist_ok=True)
+    content = f"""
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '{python_version}'
+      - name: Install Poetry
+        run: pipx install poetry
+      - name: Install deps
+        run: poetry install
+      - name: Lint
+        run: poetry run flake8 --select=E,F
+      - name: Typecheck
+        run: poetry run mypy src
+      - name: Tests
+        run: poetry run pytest -q -W error
+"""
+    p.write_text(content.strip() + "\n")
+    return p
+
+
+def write_openapi_lint_config(*, target_dir: str | Path, name: str = ".redocly.yaml") -> Path:
+    """Write a minimal OpenAPI lint config placeholder (Redocly)."""
+    p = Path(target_dir) / name
+    content = """
+apis:
+  main:
+    root: openapi.json
+
+rules:
+  operation-operationId: warn
+  no-unused-components: warn
+  security-defined: off
+"""
+    p.write_text(content.strip() + "\n")
+    return p
+
+
+__all__ = ["write_ci_workflow", "write_openapi_lint_config"]

{svc_infra-0.1.601.dist-info → svc_infra-0.1.602.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.601
+Version: 0.1.602
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

{svc_infra-0.1.601.dist-info → svc_infra-0.1.602.dist-info}/RECORD

@@ -56,6 +56,7 @@ svc_infra/api/fastapi/db/sql/session.py,sha256=DUBqKTRJAX4fqRz9B-w9eD9SpzZ8EUS86
 svc_infra/api/fastapi/db/sql/users.py,sha256=68HGJgYVTEjKJm4-DPPC8-6nwXJoCukmgrYIIOHEUjs,5346
 svc_infra/api/fastapi/dependencies/ratelimit.py,sha256=DiOC-MJfqTtSydM6RAaeAsiXXL_6oZQoBLvRSpdWzs4,3794
 svc_infra/api/fastapi/docs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+svc_infra/api/fastapi/docs/add.py,sha256=qbGO6GHW7tXH34njnGjqQM8Php_jT3iLVe_yxDPmkpU,1671
 svc_infra/api/fastapi/docs/landing.py,sha256=5JqJYCxQDCWy-BeDLfkv7OBlzWQKSGWUCYXQ51hojG8,4627
 svc_infra/api/fastapi/docs/scoped.py,sha256=AuN35Op-9fUvHQCLOBtRjd5eWSpB5C9EAW_7-Boxmfo,7540
 svc_infra/api/fastapi/dual/__init__.py,sha256=scHLcNFkGbgX_R21V702xnAv6GMCkQ4n7yUtNDNgliM,552
@@ -91,6 +92,7 @@ svc_infra/api/fastapi/openapi/mutators.py,sha256=KcWnJ3dsn_VdBG-x0ytddf_vwJ6u-84
 svc_infra/api/fastapi/openapi/pipeline.py,sha256=GAf-qzwmWlYbrAlPirr8w89fEO4-kFrhCoeMj-7mE44,646
 svc_infra/api/fastapi/openapi/responses.py,sha256=pBUoJd0lltBkQBJACS1Zd1wd975gbw6dYyMEqyueRuw,1093
 svc_infra/api/fastapi/openapi/security.py,sha256=U78KMwgc7FilFPLbIE2f6xrp74hq6TDFXpUMGRyK_bg,1248
+svc_infra/api/fastapi/ops/add.py,sha256=39puYLuJdZuIBkpmMiHF6N8H4D-96TRtFdYidbzqndI,2311
 svc_infra/api/fastapi/pagination.py,sha256=770RbYyzgJotMA8gcc_y5zeAiP3em7fOHKuKDDlpOkI,10867
 svc_infra/api/fastapi/paths/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/api/fastapi/paths/auth.py,sha256=hy9N0QFQnpv7dBOuHStui5eP9oIGHrawa0sADIVVD64,553
@@ -142,6 +144,7 @@ svc_infra/cli/cmds/obs/obs_cmds.py,sha256=fltUZu5fcnZdl0_JPJBIxIaA1Xqpw1BXE-SWBP
 svc_infra/cli/foundation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/cli/foundation/runner.py,sha256=RbfjKwb3aHk1Y0MYU8xMpKRpIqRVMVr8GuL2EDZ6n38,1862
 svc_infra/cli/foundation/typer_bootstrap.py,sha256=KapgH1R-qON9FuYH1KYlVx_5sJvjmAGl25pB61XCpm4,985
+svc_infra/data/add.py,sha256=GbTdPDDsHg9ahQuMlLn4M_YoBFcc16Mf20FeWv1p1sU,2252
 svc_infra/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/db/crud_schema.py,sha256=-fv-Om1lHVt6lcNbie6A2kRcPex4SDByUPfks6SpmUc,2521
 svc_infra/db/inbox.py,sha256=drxLRLHaMRrCDgo_8wj12do80wDh5ssHV6LGkaM98no,1996
@@ -198,6 +201,7 @@ svc_infra/db/sql/uniq_hooks.py,sha256=6gCnO0_Y-rhB0p-VuY0mZ9m1u3haiLWI3Ns_iUTqF_
 svc_infra/db/sql/utils.py,sha256=nzuDcDhnVNehx5Y9BZLgxw8fvpfYbxTfXQsgnznVf4w,32862
 svc_infra/db/sql/versioning.py,sha256=okZu2ad5RAFXNLXJgGpcQvZ5bc6gPjRWzwiBT0rEJJw,400
 svc_infra/db/utils.py,sha256=aTD49VJSEu319kIWJ1uijUoP51co4lNJ3S0_tvuyGio,802
+svc_infra/dx/add.py,sha256=FAnLGP0BPm_q_VCEcpUwfj-b0mEse988chh9DHeS7GU,1474
 svc_infra/jobs/builtins/outbox_processor.py,sha256=VZoehNyjdaV_MmV74WMcbZR6z9E3VFMtZC-pxEwK0x0,1247
 svc_infra/jobs/builtins/webhook_delivery.py,sha256=z_cl6YKwnduGjGaB8ZoUpKhFcEAhUZqqBma8v2FO1so,2982
 svc_infra/jobs/easy.py,sha256=eix-OxWeE3vdkY3GGNoYM0GAyOxc928SpiSzMkr9k0A,977
@@ -274,7 +278,7 @@ svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA
 svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
 svc_infra/webhooks/service.py,sha256=hWgiJRXKBwKunJOx91C7EcLUkotDtD3Xp0RT6vj2IC0,1797
 svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
-svc_infra-0.1.601.dist-info/METADATA,sha256=--fXg5XHvGu56tmJ-UArjNr8FjrvQ9d-75Bwww4i3bI,7839
-svc_infra-0.1.601.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-svc_infra-0.1.601.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
-svc_infra-0.1.601.dist-info/RECORD,,
+svc_infra-0.1.602.dist-info/METADATA,sha256=GarD5h35kMI5JWTb1QpqupgtKdpT8GIsv71yTKOEdgA,7839
+svc_infra-0.1.602.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.602.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.602.dist-info/RECORD,,