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

svc_infra/mcp/svc_infra_mcp.py

@@ -5,6 +5,9 @@ from enum import Enum
 from ai_infra.llm.tools.custom.cli import cli_cmd_help, cli_subcmd_help
 from ai_infra.mcp.server.tools import mcp_from_functions
 
+from svc_infra.app.env import prepare_env
+from svc_infra.cli.foundation.runner import run_from_root
+
 CLI_PROG = "svc-infra"
 
 
@@ -17,34 +20,73 @@ async def svc_infra_cmd_help() -> dict:
     return await cli_cmd_help(CLI_PROG)
 
 
+# No dedicated 'docs list' function — users can use 'docs --help' to discover topics.
+
+
+async def svc_infra_docs_help() -> dict:
+    """
+    Run 'svc-infra docs --help' and return its output.
+    Prepares the project environment and executes from the repo root so
+    environment-provided docs directories and local topics are discoverable.
+    """
+    root = prepare_env()
+    text = await run_from_root(root, CLI_PROG, ["docs", "--help"])
+    return {
+        "ok": True,
+        "action": "docs_help",
+        "project_root": str(root),
+        "help": text,
+    }
+
+
 class Subcommand(str, Enum):
-    # SQL commands
-    sql_init = "sql-init"
-    sql_revision = "sql-revision"
-    sql_upgrade = "sql-upgrade"
-    sql_downgrade = "sql-downgrade"
-    sql_current = "sql-current"
-    sql_history = "sql-history"
-    sql_stamp = "sql-stamp"
-    sql_merge_heads = "sql-merge-heads"
-    sql_setup_and_migrate = "sql-setup-and-migrate"
-    sql_scaffold = "sql-scaffold"
-    sql_scaffold_models = "sql-scaffold-models"
-    sql_scaffold_schemas = "sql-scaffold-schemas"
-
-    # Mongo commands
-    mongo_prepare = "mongo-prepare"
-    mongo_setup_and_prepare = "mongo-setup-and-prepare"
-    mongo_ping = "mongo-ping"
-    mongo_scaffold = "mongo-scaffold"
-    mongo_scaffold_documents = "mongo-scaffold-documents"
-    mongo_scaffold_schemas = "mongo-scaffold-schemas"
-    mongo_scaffold_resources = "mongo-scaffold-resources"
-
-    # Observability commands
-    obs_up = "obs-up"
-    obs_down = "obs-down"
-    obs_scaffold = "obs-scaffold"
+    # SQL group commands
+    sql_init = "sql init"
+    sql_revision = "sql revision"
+    sql_upgrade = "sql upgrade"
+    sql_downgrade = "sql downgrade"
+    sql_current = "sql current"
+    sql_history = "sql history"
+    sql_stamp = "sql stamp"
+    sql_merge_heads = "sql merge-heads"
+    sql_setup_and_migrate = "sql setup-and-migrate"
+    sql_scaffold = "sql scaffold"
+    sql_scaffold_models = "sql scaffold-models"
+    sql_scaffold_schemas = "sql scaffold-schemas"
+    sql_export_tenant = "sql export-tenant"
+    sql_seed = "sql seed"
+
+    # Mongo group commands
+    mongo_prepare = "mongo prepare"
+    mongo_setup_and_prepare = "mongo setup-and-prepare"
+    mongo_ping = "mongo ping"
+    mongo_scaffold = "mongo scaffold"
+    mongo_scaffold_documents = "mongo scaffold-documents"
+    mongo_scaffold_schemas = "mongo scaffold-schemas"
+    mongo_scaffold_resources = "mongo scaffold-resources"
+
+    # Observability group commands
+    obs_up = "obs up"
+    obs_down = "obs down"
+    obs_scaffold = "obs scaffold"
+
+    # Docs group
+    docs_help = "docs --help"
+    docs_show = "docs show"
+
+    # DX group
+    dx_openapi = "dx openapi"
+    dx_migrations = "dx migrations"
+    dx_changelog = "dx changelog"
+    dx_ci = "dx ci"
+
+    # Jobs group
+    jobs_run = "jobs run"
+
+    # SDK group
+    sdk_ts = "sdk ts"
+    sdk_py = "sdk py"
+    sdk_postman = "sdk postman"
 
 
 async def svc_infra_subcmd_help(subcommand: Subcommand) -> dict:
@@ -52,7 +94,19 @@ async def svc_infra_subcmd_help(subcommand: Subcommand) -> dict:
     Get help text for a specific subcommand of svc-infra CLI.
     (Enum keeps a tight schema; function signature remains simple.)
     """
-    return await cli_subcmd_help(CLI_PROG, subcommand)
+    tokens = subcommand.value.split()
+    if len(tokens) == 1:
+        return await cli_subcmd_help(CLI_PROG, subcommand)
+
+    root = prepare_env()
+    text = await run_from_root(root, CLI_PROG, [*tokens, "--help"])
+    return {
+        "ok": True,
+        "action": "subcommand_help",
+        "subcommand": subcommand.value,
+        "project_root": str(root),
+        "help": text,
+    }
 
 
 mcp = mcp_from_functions(
@@ -60,8 +114,11 @@ mcp = mcp_from_functions(
     functions=[
         svc_infra_cmd_help,
         svc_infra_subcmd_help,
+        svc_infra_docs_help,
+        # Docs listing is available via 'docs --help'; no separate MCP function needed.
     ],
 )
 
+
 if __name__ == "__main__":
     mcp.run(transport="stdio")

svc_infra/obs/add.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Callable, Iterable, Optional
+from typing import Any, Callable, Iterable, Optional, Protocol
 
 from svc_infra.obs.settings import ObservabilitySettings
 
@@ -9,12 +9,20 @@ def _want_metrics(cfg: ObservabilitySettings) -> bool:
     return bool(cfg.METRICS_ENABLED)
 
 
+class RouteClassifier(Protocol):
+    def __call__(
+        self, route_path: str, method: str
+    ) -> str:  # e.g., returns "public|internal|admin"
+        ...
+
+
 def add_observability(
     app: Any | None = None,
     *,
     db_engines: Optional[Iterable[Any]] = None,
     metrics_path: str | None = None,
     skip_metric_paths: Optional[Iterable[str]] = None,
+    route_classifier: RouteClassifier | None = None,
 ) -> Callable[[], None]:
     """
     Enable Prometheus metrics for the ASGI app and optional SQLAlchemy pool metrics.
@@ -25,14 +33,53 @@ def add_observability(
     # --- Metrics (Prometheus) — import lazily so CLIs/tests don’t require prometheus_client
     if app is not None and _want_metrics(cfg):
         try:
-            from svc_infra.obs.metrics.asgi import add_prometheus  # lazy
+            from svc_infra.obs.metrics.asgi import (  # lazy
+                PrometheusMiddleware,
+                add_prometheus,
+                metrics_endpoint,
+            )
 
             path = metrics_path or cfg.METRICS_PATH
-            add_prometheus(
-                app,
-                path=path,
-                skip_paths=tuple(skip_metric_paths or (path, "/health", "/healthz")),
-            )
+            skip_paths = tuple(skip_metric_paths or (path, "/health", "/healthz"))
+            # If a route_classifier is provided, use a custom route_resolver to append class label
+            if route_classifier is None:
+                add_prometheus(
+                    app,
+                    path=path,
+                    skip_paths=skip_paths,
+                )
+            else:
+                # Install middleware manually to pass route_resolver
+                def _resolver(req):
+                    # Base template
+                    from svc_infra.obs.metrics.asgi import _route_template  # type: ignore
+
+                    base = _route_template(req)
+                    method = getattr(req, "method", "GET")
+                    cls = route_classifier(base, method)
+                    # Encode as base|class for downstream label splitting in dashboards
+                    return f"{base}|{cls}"
+
+                app.add_middleware(
+                    PrometheusMiddleware,
+                    skip_paths=skip_paths,
+                    route_resolver=_resolver,
+                )
+                # Mount /metrics endpoint without re-adding middleware
+                try:
+                    from svc_infra.api.fastapi.dual.public import public_router
+                    from svc_infra.app.env import CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV
+
+                    router = public_router()
+                    router.add_api_route(
+                        path,
+                        endpoint=metrics_endpoint(),
+                        include_in_schema=CURRENT_ENVIRONMENT in (LOCAL_ENV, DEV_ENV),
+                        tags=["observability"],
+                    )
+                    app.include_router(router)
+                except Exception:
+                    app.add_route(path, metrics_endpoint())
         except Exception:
             pass
 

svc_infra/obs/grafana/dashboards/http-overview.json

@@ -0,0 +1,45 @@
+{
+  "title": "Service HTTP Overview",
+  "tags": ["svc-infra", "http"],
+  "timezone": "browser",
+  "panels": [
+    {
+      "type": "timeseries",
+      "title": "Success Rate (5m)",
+      "targets": [
+        {
+          "expr": "sum(rate(http_server_requests_total{code!~\"5..\"}[5m])) / sum(rate(http_server_requests_total[5m]))",
+          "legendFormat": "success_rate"
+        }
+      ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Latency p99",
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.99, sum(rate(http_server_request_duration_seconds_bucket[5m])) by (le))",
+          "legendFormat": "p99"
+        }
+      ]
+    },
+    {
+      "type": "table",
+      "title": "Top Routes by Error (5m)",
+      "targets": [
+        {
+          "expr": "topk(10, sum(rate(http_server_requests_total{code=~\"5..\"}[5m])) by (route))",
+          "legendFormat": "{{route}}"
+        }
+      ]
+    }
+  ],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-6h",
+    "to": "now"
+  },
+  "refresh": "30s"
+}

svc_infra/security/headers.py

@@ -6,8 +6,21 @@ SECURE_DEFAULTS = {
     "X-Frame-Options": "DENY",
     "Referrer-Policy": "strict-origin-when-cross-origin",
     "X-XSS-Protection": "0",
-    # CSP kept minimal; allow config override
-    "Content-Security-Policy": "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'",
+    # CSP with practical defaults - allows inline styles/scripts and data URIs for images
+    # Also allows cdn.jsdelivr.net for FastAPI docs (Swagger UI, ReDoc)
+    # Still secure: blocks arbitrary external scripts, prevents framing, restricts form actions
+    # Override via headers_overrides in add_security() for stricter or custom policies
+    "Content-Security-Policy": (
+        "default-src 'self'; "
+        "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+        "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+        "img-src 'self' data: https:; "
+        "connect-src 'self'; "
+        "font-src 'self' https://cdn.jsdelivr.net; "
+        "frame-ancestors 'none'; "
+        "base-uri 'self'; "
+        "form-action 'self'"
+    ),
 }
 
 

svc_infra/security/hibp.py

@@ -5,7 +5,7 @@ import time
 from dataclasses import dataclass
 from typing import Dict, Optional
 
-import httpx
+from svc_infra.http import new_httpx_client
 
 
 def sha1_hex(data: str) -> str:
@@ -39,7 +39,11 @@ class HIBPClient:
         self.timeout = timeout
         self.user_agent = user_agent
         self._cache: Dict[str, CacheEntry] = {}
-        self._http = httpx.Client(timeout=self.timeout, headers={"User-Agent": self.user_agent})
+        # Use central factory for consistent defaults; retain explicit timeout override
+        self._http = new_httpx_client(
+            timeout_seconds=self.timeout,
+            headers={"User-Agent": self.user_agent},
+        )
 
     def _get_cached(self, prefix: str) -> Optional[str]:
         now = time.time()

svc_infra/security/permissions.py

@@ -16,6 +16,7 @@ PERMISSION_REGISTRY: Dict[str, Set[str]] = {
         "billing.write",
         "security.session.revoke",
         "security.session.list",
+        "admin.impersonate",
     },
     "support": {"user.read", "billing.read"},
     "auditor": {"user.read", "billing.read", "audit.read"},

svc_infra/webhooks/service.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Dict, List
-
 from uuid import uuid4
 
 from svc_infra.db.outbox import OutboxStore
@@ -22,7 +21,16 @@ class InMemoryWebhookSubscriptions:
         self._subs: Dict[str, List[WebhookSubscription]] = {}
 
     def add(self, topic: str, url: str, secret: str) -> None:
-        self._subs.setdefault(topic, []).append(WebhookSubscription(topic, url, secret))
+        # Upsert semantics per (topic, url): if a subscription already exists
+        # for this topic and URL, rotate its secret instead of adding a new row.
+        # This mirrors typical real-world secret rotation flows where the
+        # endpoint remains the same but the signing secret changes.
+        lst = self._subs.setdefault(topic, [])
+        for sub in lst:
+            if sub.url == url:
+                sub.secret = secret
+                return
+        lst.append(WebhookSubscription(topic, url, secret))
 
     def get_for_topic(self, topic: str) -> List[WebhookSubscription]:
         return list(self._subs.get(topic, []))

{svc_infra-0.1.600.dist-info → svc_infra-0.1.640.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.600
+Version: 0.1.640
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
@@ -77,22 +77,48 @@ Description-Content-Type: text/markdown
 # svc-infra
 
 [![PyPI](https://img.shields.io/pypi/v/svc-infra.svg)](https://pypi.org/project/svc-infra/)
-[![Docs](https://img.shields.io/badge/docs-reference-blue)](docs/)
+[![Docs](https://img.shields.io/badge/docs-reference-blue)](.)
 
 svc-infra packages the shared building blocks we use to ship production FastAPI services fast—HTTP APIs with secure auth, durable persistence, background execution, cache, observability, and webhook plumbing that all share the same batteries-included defaults.
 
 ## Helper index
 
-| Helper | What it covers | Guide |
+| Area | What it covers | Guide |
 | --- | --- | --- |
-| API | FastAPI bootstrap, envelopes, middleware, docs wiring | [FastAPI guide](docs/api.md) |
-| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth settings](docs/auth.md) |
-| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database guide](docs/database.md) |
-| Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](docs/jobs.md) |
-| Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](docs/cache.md) |
-| Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](docs/observability.md) |
-| Webhooks | Subscription store, signing, retry worker | [Webhooks framework](docs/webhooks.md) |
-| Security | Password policy, lockout, signed cookies, headers | [Security hardening](docs/security.md) |
+| Getting Started | Overview and entry points | [This page](src/svc_infra/docs/getting-started.md) |
+| Environment | Feature switches and env vars | [Environment](src/svc_infra/docs/environment.md) |
+| API | FastAPI bootstrap, middleware, docs wiring | [API guide](src/svc_infra/docs/api.md) |
+| Auth | Sessions, OAuth/OIDC, MFA, SMTP delivery | [Auth](src/svc_infra/docs/auth.md) |
+| Security | Password policy, lockout, signed cookies, headers | [Security](ssrc/svc_infra/docs/ecurity.md) |
+| Database | SQL + Mongo wiring, Alembic helpers, inbox/outbox patterns | [Database](src/svc_infra/docs/database.md) |
+| Tenancy | Multi-tenant boundaries and helpers | [Tenancy](src/svc_infra/docs/tenancy.md) |
+| Idempotency | Idempotent endpoints and middleware | [Idempotency](src/svc_infra/docs/idempotency.md) |
+| Rate Limiting | Middleware, dependency limiter, headers | [Rate limiting](rsrc/svc_infra/docs/ate-limiting.md) |
+| Cache | cashews decorators, namespace management, TTL helpers | [Cache](src/svc_infra/docs/cache.md) |
+| Jobs | JobQueue, scheduler, CLI worker | [Jobs](src/svc_infra/docs/jobs.md) |
+| Observability | Prometheus, Grafana, OpenTelemetry | [Observability](src/svc_infra/docs/observability.md) |
+| Ops | Probes, breakers, SLOs & dashboards | [Ops](src/svc_infra/docs/ops.md) |
+| Webhooks | Subscription store, signing, retry worker | [Webhooks](src/svc_infra/docs/webhooks.md) |
+| CLI | Command groups for sql/mongo/obs/docs/dx/sdk/jobs | [CLI](src/svc_infra/docs/cli.md) |
+| Docs & SDKs | Publishing docs, generating SDKs | [Docs & SDKs](src/svc_infra/docs/docs-and-sdks.md) |
+| Acceptance | Acceptance harness and flows | [Acceptance](src/svc_infra/docs/acceptance.md), [Matrix](src/svc_infra/docs/acceptance-matrix.md) |
+| Contributing | Dev setup and quality gates | [Contributing](src/svc_infra/docs/contributing.md) |
+| Repo Review | Checklist for releasing/PRs | [Repo review](src/svc_infra/docs/repo-review.md) |
+| Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](src/svc_infra/docs/data-lifecycle.md) |
+
+## Quick Start with Template Example
+
+See **ALL** svc-infra features working together in a complete example:
+
+```bash
+# One-time setup (from repo root)
+make setup-template    # Scaffolds models, runs migrations
+
+# Run the example server
+make run-template      # Starts at http://localhost:8001
+```
+
+See [`examples/README.md`](examples/README.md) for full documentation and manual setup options.
 
 ## Minimal FastAPI bootstrap
 
@@ -120,9 +146,9 @@ async def handle_webhook(payload = Depends(require_signature(lambda: ["current",
 - **API** – toggle logging/observability and docs exposure with `ENABLE_LOGGING`, `LOG_LEVEL`, `LOG_FORMAT`, `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and `CORS_ALLOW_ORIGINS`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/api/fastapi/setup.py†L47-L88】
 - **Auth** – configure JWT secrets, SMTP, cookies, and policy using the `AUTH_…` settings family (e.g., `AUTH_JWT__SECRET`, `AUTH_SMTP_HOST`, `AUTH_SESSION_COOKIE_SECURE`). 【F:src/svc_infra/api/fastapi/auth/settings.py†L23-L91】
 - **Database** – set connection URLs or components via `SQL_URL`/`SQL_URL_FILE`, `DB_DIALECT`, `DB_HOST`, `DB_USER`, `DB_PASSWORD`, plus Mongo knobs like `MONGO_URL`, `MONGO_DB`, and `MONGO_URL_FILE`. 【F:src/svc_infra/api/fastapi/db/sql/add.py†L55-L114】【F:src/svc_infra/db/sql/utils.py†L85-L206】【F:src/svc_infra/db/nosql/mongo/settings.py†L9-L13】【F:src/svc_infra/db/nosql/utils.py†L56-L113】
-- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:docs/jobs.md†L11-L48】
+- **Jobs** – choose the queue backend with `JOBS_DRIVER` and provide Redis via `REDIS_URL`; interval schedules can be declared with `JOBS_SCHEDULE_JSON`. 【F:src/svc_infra/jobs/easy.py†L11-L27】【F:src/svc_infra/docs/jobs.md†L11-L48】
 - **Cache** – namespace keys and lifetimes through `CACHE_PREFIX`, `CACHE_VERSION`, and TTL overrides `CACHE_TTL_DEFAULT`, `CACHE_TTL_SHORT`, `CACHE_TTL_LONG`. 【F:src/svc_infra/cache/README.md†L20-L173】【F:src/svc_infra/cache/ttl.py†L26-L55】
 - **Observability** – turn metrics on/off or adjust scrape paths with `ENABLE_OBS`, `METRICS_PATH`, `OBS_SKIP_PATHS`, and Prometheus/Grafana flags like `SVC_INFRA_DISABLE_PROMETHEUS`, `SVC_INFRA_RATE_WINDOW`, `SVC_INFRA_DASHBOARD_REFRESH`, `SVC_INFRA_DASHBOARD_RANGE`. 【F:src/svc_infra/api/fastapi/ease.py†L67-L111】【F:src/svc_infra/obs/metrics/asgi.py†L49-L206】【F:src/svc_infra/obs/cloud_dash.py†L85-L108】
-- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:docs/webhooks.md†L32-L53】
-- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:docs/security.md†L24-L70】
+- **Webhooks** – reuse the jobs envs (`JOBS_DRIVER`, `REDIS_URL`) for the delivery worker and queue configuration. 【F:src/svc_infra/docs/webhooks.md†L32-L53】
+- **Security** – enforce password policy, MFA, and rotation with auth prefixes such as `AUTH_PASSWORD_MIN_LENGTH`, `AUTH_PASSWORD_REQUIRE_SYMBOL`, `AUTH_JWT__SECRET`, and `AUTH_JWT__OLD_SECRETS`. 【F:src/svc_infra/docs/security.md†L24-L70】