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

svc_infra/mcp/svc_infra_mcp.py

@@ -1,58 +1,113 @@
 from __future__ import annotations
 
 from enum import Enum
+from typing import Any, cast
 
 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"
 
 
-async def svc_infra_cmd_help() -> dict:
+async def svc_infra_cmd_help() -> dict[Any, Any]:
     """
     Get help text for svc-infra CLI.
     - Prepares project env without chdir (so we can 'cd' in the command itself).
     - Tries poetry → console script → python -m svc_infra.cli_shim.
     """
-    return await cli_cmd_help(CLI_PROG)
+    return cast(dict[Any, Any], 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"
-
-
-async def svc_infra_subcmd_help(subcommand: Subcommand) -> dict:
+    # 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[Any, Any]:
     """
     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 cast(dict[Any, Any], 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 +115,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/README.md

@@ -8,6 +8,8 @@ This guide shows you how to turn on metrics + dashboards in three easy modes:
 
 It's "one button": run `svc-infra obs-up` and you're good. The CLI will read your `.env` automatically and do the right thing.
 
+> ℹ️ A complete list of observability-related environment variables lives in [Environment Reference](../../../docs/environment.md).
+
 ---
 
 ## 0) Install & instrument your app (once)

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,21 +33,66 @@ 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
+
+                    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
 
     # --- DB pool metrics (best effort) — also lazy
     if db_engines:
         try:
-            from svc_infra.obs.metrics.sqlalchemy import bind_sqlalchemy_pool_metrics  # lazy
+            from svc_infra.obs.metrics.sqlalchemy import (
+                bind_sqlalchemy_pool_metrics,
+            )  # lazy
 
             for eng in db_engines:
                 try:
@@ -51,7 +104,10 @@ def add_observability(
 
     # --- HTTP client metrics (best effort) — import lazily
     try:
-        from svc_infra.obs.metrics.http import instrument_httpx, instrument_requests  # lazy
+        from svc_infra.obs.metrics.http import (
+            instrument_httpx,
+            instrument_requests,
+        )  # lazy
 
         try:
             instrument_requests()

svc_infra/obs/cloud_dash.py

@@ -5,6 +5,7 @@ import os
 import re
 import urllib.request
 from importlib.resources import files
+from typing import Any, cast
 
 # ---------------- helpers ----------------
 
@@ -86,7 +87,7 @@ def _rewrite_rate_windows(d: dict) -> dict:
     if not win:
         return d
 
-    dd = json.loads(json.dumps(d))
+    dd = cast(dict[Any, Any], json.loads(json.dumps(d)))
     for p in dd.get("panels", []) or []:
         targets = p.get("targets") or []
         for t in targets:

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/obs/metrics/__init__.py

@@ -0,0 +1,52 @@
+"""Metrics package public API.
+
+Provides lightweight, overridable hooks for abuse heuristics so callers can
+plug in logging or a metrics backend without a hard dependency.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+# Function variables so applications/tests can replace them at runtime.
+on_rate_limit_exceeded: Callable[[str, int, int], None] | None = None
+"""
+Called when a request is rate-limited.
+Args:
+    key: identifier used for rate limiting (e.g., API key or IP)
+    limit: configured limit for the window
+    retry_after: seconds until next allowed attempt
+"""
+
+on_suspect_payload: Callable[[Optional[str], int], None] | None = None
+"""
+Called when a request exceeds the configured size limit.
+Args:
+    path: request path if available
+    size: reported content-length
+"""
+
+
+def emit_rate_limited(key: str, limit: int, retry_after: int) -> None:
+    if on_rate_limit_exceeded:
+        try:
+            on_rate_limit_exceeded(key, limit, retry_after)
+        except Exception:
+            # Never break request flow on metrics exceptions
+            pass
+
+
+def emit_suspect_payload(path: Optional[str], size: int) -> None:
+    if on_suspect_payload:
+        try:
+            on_suspect_payload(path, size)
+        except Exception:
+            pass
+
+
+__all__ = [
+    "emit_rate_limited",
+    "emit_suspect_payload",
+    "on_rate_limit_exceeded",
+    "on_suspect_payload",
+]

svc_infra/obs/metrics/asgi.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import os
 import time
-from typing import Any, Callable, Iterable, Optional
+from typing import Any, Callable, Iterable, Optional, cast
 
 from starlette.requests import Request
 from starlette.responses import PlainTextResponse, Response
@@ -34,7 +34,7 @@ def _register_default_collectors_once() -> None:
     try:
         # These imports are no-ops if already registered by the client,
         # but GCCollector typically needs explicit instantiation.
-        from prometheus_client import GCCollector  # type: ignore
+        from prometheus_client import GCCollector
 
         GCCollector()  # registers GC metrics
         _default_collectors_ready = True
@@ -97,9 +97,9 @@ def _init_metrics() -> None:
 def _route_template(req: Request) -> str:
     route = getattr(req, "scope", {}).get("route")
     if route and hasattr(route, "path_format"):
-        return route.path_format
+        return cast(str, route.path_format)
     if route and hasattr(route, "path"):
-        return route.path
+        return cast(str, route.path)
     return req.url.path or "/*unmatched*"
 
 
@@ -186,9 +186,13 @@ class PrometheusMiddleware:
                     if _http_requests_total:
                         _http_requests_total.labels(method, route_for_stats, code).inc()
                     if _http_request_duration:
-                        _http_request_duration.labels(route_for_stats, method).observe(elapsed)
+                        _http_request_duration.labels(route_for_stats, method).observe(
+                            elapsed
+                        )
                     if _http_response_size:
-                        _http_response_size.labels(route_for_stats, method).observe(bytes_sent)
+                        _http_response_size.labels(route_for_stats, method).observe(
+                            bytes_sent
+                        )
                 except Exception:
                     pass
                 try:
@@ -237,7 +241,9 @@ def metrics_endpoint():
         return handler
 
 
-def add_prometheus(app, *, path: str = "/metrics", skip_paths: Optional[Iterable[str]] = None):
+def add_prometheus(
+    app, *, path: str = "/metrics", skip_paths: Optional[Iterable[str]] = None
+):
     """Convenience for FastAPI/Starlette apps."""
     # Add middleware
     app.add_middleware(

svc_infra/obs/metrics/http.py

@@ -51,7 +51,7 @@ def instrument_requests():
             _http_client_total.labels(host, method_u, code).inc()
             _http_client_duration.labels(host, method_u).observe(elapsed)
 
-    requests.sessions.Session.request = _wrapped  # type: ignore[attr-defined]
+    setattr(requests.sessions.Session, "request", _wrapped)
 
 
 def instrument_httpx():
@@ -74,7 +74,9 @@ def instrument_httpx():
                 raise
             finally:
                 _http_client_total.labels(host, method, code).inc()
-                _http_client_duration.labels(host, method).observe(time.perf_counter() - start)
+                _http_client_duration.labels(host, method).observe(
+                    time.perf_counter() - start
+                )
 
         return _wrapped
 
@@ -91,7 +93,9 @@ def instrument_httpx():
             raise
         finally:
             _http_client_total.labels(host, method, code).inc()
-            _http_client_duration.labels(host, method).observe(time.perf_counter() - start)
+            _http_client_duration.labels(host, method).observe(
+                time.perf_counter() - start
+            )
 
-    httpx.Client.send = _wrap_sync_send(_orig_sync)  # type: ignore[assignment]
-    httpx.AsyncClient.send = _wrapped_async  # type: ignore[assignment]
+    setattr(httpx.Client, "send", _wrap_sync_send(_orig_sync))
+    setattr(httpx.AsyncClient, "send", _wrapped_async)

svc_infra/obs/metrics/sqlalchemy.py

@@ -7,7 +7,7 @@ from sqlalchemy.engine import Engine
 try:
     from sqlalchemy.ext.asyncio import AsyncEngine
 except Exception:  # optional
-    AsyncEngine = None  # type: ignore
+    AsyncEngine = None  # type: ignore[misc,assignment]
 
 from .base import counter, gauge
 
@@ -23,8 +23,12 @@ _pool_available = gauge(
     labels=["db"],
     multiprocess_mode="livesum",
 )
-_pool_checked_out_total = counter("db_pool_checkedout_total", "Total checkouts", labels=["db"])
-_pool_checked_in_total = counter("db_pool_checkedin_total", "Total checkins", labels=["db"])
+_pool_checked_out_total = counter(
+    "db_pool_checkedout_total", "Total checkouts", labels=["db"]
+)
+_pool_checked_in_total = counter(
+    "db_pool_checkedin_total", "Total checkins", labels=["db"]
+)
 
 
 def _label(labels: Optional[Mapping[str, str]]) -> str:
@@ -46,8 +50,8 @@ def bind_sqlalchemy_pool_metrics(
         # Update gauges on engine_connect as a cheap heartbeat
         pool = sync_engine.pool
         try:
-            _pool_in_use.labels(label).set(pool.checkedout())
-            _pool_available.labels(label).set(pool.size() - pool.checkedout())
+            _pool_in_use.labels(label).set(pool.checkedout())  # type: ignore[attr-defined]
+            _pool_available.labels(label).set(pool.size() - pool.checkedout())  # type: ignore[attr-defined]
         except Exception:
             pass
 
@@ -56,8 +60,8 @@ def bind_sqlalchemy_pool_metrics(
         _pool_checked_out_total.labels(label).inc()
         try:
             pool = sync_engine.pool
-            _pool_in_use.labels(label).set(pool.checkedout())
-            _pool_available.labels(label).set(pool.size() - pool.checkedout())
+            _pool_in_use.labels(label).set(pool.checkedout())  # type: ignore[attr-defined]
+            _pool_available.labels(label).set(pool.size() - pool.checkedout())  # type: ignore[attr-defined]
         except Exception:
             pass
 
@@ -66,7 +70,7 @@ def bind_sqlalchemy_pool_metrics(
         _pool_checked_in_total.labels(label).inc()
         try:
             pool = sync_engine.pool
-            _pool_in_use.labels(label).set(pool.checkedout())
-            _pool_available.labels(label).set(pool.size() - pool.checkedout())
+            _pool_in_use.labels(label).set(pool.checkedout())  # type: ignore[attr-defined]
+            _pool_available.labels(label).set(pool.size() - pool.checkedout())  # type: ignore[attr-defined]
         except Exception:
             pass

svc_infra/obs/metrics.py

@@ -0,0 +1,53 @@
+"""Lightweight metrics hooks for abuse heuristics.
+
+Intentionally minimal to avoid pulling full metrics stacks; these are no-ops by
+default but can be swapped in tests or wired to a metrics backend by overriding the
+functions.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+# Function variables so applications/tests can replace them at runtime.
+on_rate_limit_exceeded: Callable[[str, int, int], None] | None = None
+"""
+Called when a request is rate-limited.
+Args:
+    key: identifier used for rate limiting (e.g., API key or IP)
+    limit: configured limit for the window
+    retry_after: seconds until next allowed attempt
+"""
+
+on_suspect_payload: Callable[[Optional[str], int], None] | None = None
+"""
+Called when a request exceeds the configured size limit.
+Args:
+    path: request path if available
+    size: reported content-length
+"""
+
+
+def emit_rate_limited(key: str, limit: int, retry_after: int) -> None:
+    if on_rate_limit_exceeded:
+        try:
+            on_rate_limit_exceeded(key, limit, retry_after)
+        except Exception:
+            # Never break request flow on metrics exceptions
+            pass
+
+
+def emit_suspect_payload(path: Optional[str], size: int) -> None:
+    if on_suspect_payload:
+        try:
+            on_suspect_payload(path, size)
+        except Exception:
+            pass
+
+
+__all__ = [
+    "emit_rate_limited",
+    "emit_suspect_payload",
+    "on_rate_limit_exceeded",
+    "on_suspect_payload",
+]

svc_infra/obs/settings.py

@@ -14,8 +14,12 @@ class ObservabilitySettings(BaseSettings):
       - METRICS_DEFAULT_BUCKETS=comma-separated seconds (optional)
     """
 
-    METRICS_ENABLED: bool = Field(default=True, description="Enable Prometheus metrics exposure")
-    METRICS_PATH: str = Field(default="/metrics", description="HTTP path for metrics endpoint")
+    METRICS_ENABLED: bool = Field(
+        default=True, description="Enable Prometheus metrics exposure"
+    )
+    METRICS_PATH: str = Field(
+        default="/metrics", description="HTTP path for metrics endpoint"
+    )
     METRICS_DEFAULT_BUCKETS: tuple[float, ...] = Field(
         default=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 10.0),
         description="Default histogram buckets (seconds)",