svc-infra 0.1.601__tar.gz → 0.1.602__tar.gz

{svc_infra-0.1.601 → svc_infra-0.1.602}/PKG-INFO

@@ -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 → svc_infra-0.1.602}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.601"
+version = "0.1.602"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"

svc_infra-0.1.602/src/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-0.1.602/src/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-0.1.602/src/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-0.1.602/src/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"]