svc-infra 0.1.506__py3-none-any.whl → 0.1.654__py3-none-any.whl

svc_infra/jobs/worker.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Awaitable, Callable
+
+from .queue import Job, JobQueue
+
+ProcessFunc = Callable[[Job], Awaitable[None]]
+
+
+def _get_job_timeout_seconds() -> float | None:
+    raw = os.getenv("JOB_DEFAULT_TIMEOUT_SECONDS")
+    if not raw:
+        return None
+    try:
+        return float(raw)
+    except ValueError:
+        return None
+
+
+async def process_one(queue: JobQueue, handler: ProcessFunc) -> bool:
+    """Reserve a job, process with handler, ack on success or fail with backoff.
+
+    Returns True if a job was processed (success or fail), False if no job was available.
+    """
+    job = queue.reserve_next()
+    if not job:
+        return False
+    try:
+        timeout = _get_job_timeout_seconds()
+        if timeout and timeout > 0:
+            await asyncio.wait_for(handler(job), timeout=timeout)
+        else:
+            await handler(job)
+    except Exception as exc:  # pragma: no cover - exercise in tests by raising
+        queue.fail(job.id, error=str(exc))
+        return True
+    queue.ack(job.id)
+    return True

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

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+"""
+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 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.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+"""
+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 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/security/add.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from typing import Iterable
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.sessions import SessionMiddleware
+
+from svc_infra.security.headers import SECURE_DEFAULTS, SecurityHeadersMiddleware
+
+DEFAULT_SESSION_SECRET = "svc-dev-secret-change-me"
+
+
+def _parse_bool(value: str | None) -> bool | None:
+    if value is None:
+        return None
+    lowered = value.strip().lower()
+    if lowered in {"1", "true", "yes", "on"}:
+        return True
+    if lowered in {"0", "false", "no", "off"}:
+        return False
+    return None
+
+
+def _normalize_origins(value: Iterable[str] | str | None) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        parts = [p.strip() for p in value.split(",")]
+    else:
+        parts = [str(v).strip() for v in value]
+    return [p for p in parts if p]
+
+
+def _resolve_cors_origins(
+    provided: Iterable[str] | str | None,
+    env: Mapping[str, str],
+) -> list[str]:
+    if provided is not None:
+        return _normalize_origins(provided)
+    return _normalize_origins(env.get("CORS_ALLOW_ORIGINS"))
+
+
+def _resolve_allow_credentials(
+    allow_credentials: bool,
+    env: Mapping[str, str],
+) -> bool:
+    env_value = _parse_bool(env.get("CORS_ALLOW_CREDENTIALS"))
+    if env_value is None:
+        return allow_credentials
+    # Allow explicit overrides via function arguments.
+    if allow_credentials is not True:
+        return allow_credentials
+    return env_value
+
+
+def _configure_cors(
+    app: FastAPI,
+    *,
+    cors_origins: Iterable[str] | str | None,
+    allow_credentials: bool,
+    env: Mapping[str, str],
+) -> None:
+    origins = _resolve_cors_origins(cors_origins, env)
+    if not origins:
+        return
+
+    allow_methods = _normalize_origins(env.get("CORS_ALLOW_METHODS")) or ["*"]
+    allow_headers = _normalize_origins(env.get("CORS_ALLOW_HEADERS")) or ["*"]
+
+    credentials = _resolve_allow_credentials(allow_credentials, env)
+
+    wildcard_origins = "*" in origins
+
+    cors_kwargs: dict[str, object] = {
+        "allow_credentials": credentials,
+        "allow_methods": allow_methods,
+        "allow_headers": allow_headers,
+        "allow_origins": ["*"] if wildcard_origins else origins,
+    }
+    origin_regex = env.get("CORS_ALLOW_ORIGIN_REGEX")
+    if wildcard_origins:
+        cors_kwargs["allow_origin_regex"] = origin_regex or ".*"
+    else:
+        if origin_regex:
+            cors_kwargs["allow_origin_regex"] = origin_regex
+
+    app.add_middleware(CORSMiddleware, **cors_kwargs)
+
+
+def _configure_security_headers(
+    app: FastAPI,
+    *,
+    overrides: dict[str, str] | None,
+    enable_hsts_preload: bool | None,
+) -> None:
+    merged_overrides = dict(overrides or {})
+    if enable_hsts_preload is not None:
+        current = merged_overrides.get(
+            "Strict-Transport-Security",
+            SECURE_DEFAULTS["Strict-Transport-Security"],
+        )
+        directives = [p.strip() for p in current.split(";") if p.strip()]
+        directives = [d for d in directives if d.lower() != "preload"]
+        if enable_hsts_preload:
+            directives.append("preload")
+        merged_overrides["Strict-Transport-Security"] = "; ".join(directives)
+
+    app.add_middleware(SecurityHeadersMiddleware, overrides=merged_overrides)
+
+
+def _should_add_session_middleware(app: FastAPI) -> bool:
+    return not any(m.cls is SessionMiddleware for m in app.user_middleware)
+
+
+def _configure_session_middleware(
+    app: FastAPI,
+    *,
+    env: Mapping[str, str],
+    install: bool,
+    secret_key: str | None,
+    session_cookie: str,
+    max_age: int,
+    same_site: str,
+    https_only: bool | None,
+) -> None:
+    if not install or not _should_add_session_middleware(app):
+        return
+
+    secret = secret_key or env.get("SESSION_SECRET") or DEFAULT_SESSION_SECRET
+    https_env = _parse_bool(env.get("SESSION_COOKIE_SECURE"))
+    effective_https_only = (
+        https_only if https_only is not None else (https_env if https_env is not None else False)
+    )
+    same_site_env = env.get("SESSION_COOKIE_SAMESITE")
+    same_site_value = same_site_env.strip() if same_site_env else same_site
+
+    max_age_env = env.get("SESSION_COOKIE_MAX_AGE_SECONDS")
+    try:
+        max_age_value = int(max_age_env) if max_age_env is not None else max_age
+    except ValueError:
+        max_age_value = max_age
+
+    session_cookie_env = env.get("SESSION_COOKIE_NAME")
+    session_cookie_value = session_cookie_env.strip() if session_cookie_env else session_cookie
+
+    app.add_middleware(
+        SessionMiddleware,
+        secret_key=secret,
+        session_cookie=session_cookie_value,
+        max_age=max_age_value,
+        same_site=same_site_value,
+        https_only=effective_https_only,
+    )
+
+
+def add_security(
+    app: FastAPI,
+    *,
+    cors_origins: Iterable[str] | str | None = None,
+    headers_overrides: dict[str, str] | None = None,
+    allow_credentials: bool = True,
+    env: Mapping[str, str] = os.environ,
+    enable_hsts_preload: bool | None = None,
+    install_session_middleware: bool = False,
+    session_secret_key: str | None = None,
+    session_cookie_name: str = "svc_session",
+    session_cookie_max_age_seconds: int = 4 * 3600,
+    session_cookie_samesite: str = "lax",
+    session_cookie_https_only: bool | None = None,
+) -> None:
+    """Install security middlewares with svc-infra defaults."""
+
+    _configure_security_headers(
+        app,
+        overrides=headers_overrides,
+        enable_hsts_preload=enable_hsts_preload,
+    )
+    _configure_cors(
+        app,
+        cors_origins=cors_origins,
+        allow_credentials=allow_credentials,
+        env=env,
+    )
+    _configure_session_middleware(
+        app,
+        env=env,
+        install=install_session_middleware,
+        secret_key=session_secret_key,
+        session_cookie=session_cookie_name,
+        max_age=session_cookie_max_age_seconds,
+        same_site=session_cookie_samesite,
+        https_only=session_cookie_https_only,
+    )
+
+
+__all__ = [
+    "add_security",
+]