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

svc_infra/http/client.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+from svc_infra.app.env import pick
+
+
+def _parse_float_env(name: str, default: float) -> float:
+    raw = os.getenv(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+def get_default_timeout_seconds() -> float:
+    """Return default outbound HTTP client timeout in seconds.
+
+    Env var: HTTP_CLIENT_TIMEOUT_SECONDS (float)
+    Defaults: 10.0 seconds for all envs unless overridden; tweakable via pick() if needed.
+    """
+    default = pick(prod=10.0, nonprod=10.0)
+    return _parse_float_env("HTTP_CLIENT_TIMEOUT_SECONDS", default)
+
+
+def make_timeout(seconds: float | None = None) -> httpx.Timeout:
+    s = seconds if seconds is not None else get_default_timeout_seconds()
+    # Apply same timeout for connect/read/write/pool for simplicity
+    return httpx.Timeout(timeout=s)
+
+
+def new_httpx_client(
+    *,
+    timeout_seconds: Optional[float] = None,
+    headers: Optional[Dict[str, str]] = None,
+    base_url: Optional[str] = None,
+    **kwargs: Any,
+) -> httpx.Client:
+    """Create a sync httpx Client with default timeout and optional headers/base_url.
+
+    Callers can override timeout_seconds; remaining kwargs are forwarded to httpx.Client.
+    """
+    timeout = make_timeout(timeout_seconds)
+    # httpx doesn't accept base_url=None; only pass if non-None
+    client_kwargs = {"timeout": timeout, "headers": headers, **kwargs}
+    if base_url is not None:
+        client_kwargs["base_url"] = base_url
+    return httpx.Client(**client_kwargs)
+
+
+def new_async_httpx_client(
+    *,
+    timeout_seconds: Optional[float] = None,
+    headers: Optional[Dict[str, str]] = None,
+    base_url: Optional[str] = None,
+    **kwargs: Any,
+) -> httpx.AsyncClient:
+    """Create an async httpx AsyncClient with default timeout and optional headers/base_url.
+
+    Callers can override timeout_seconds; remaining kwargs are forwarded to httpx.AsyncClient.
+    """
+    timeout = make_timeout(timeout_seconds)
+    # httpx doesn't accept base_url=None; only pass if non-None
+    client_kwargs = {"timeout": timeout, "headers": headers, **kwargs}
+    if base_url is not None:
+        client_kwargs["base_url"] = base_url
+    return httpx.AsyncClient(**client_kwargs)

svc_infra/jobs/builtins/webhook_delivery.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-import httpx
+import os
 
 from svc_infra.db.inbox import InboxStore
 from svc_infra.db.outbox import OutboxStore
+from svc_infra.http import get_default_timeout_seconds, new_async_httpx_client
 from svc_infra.jobs.queue import Job
 from svc_infra.webhooks.signing import sign
 
@@ -65,7 +66,18 @@ def make_webhook_handler(
             version = delivery_payload.get("version")
         if version is not None:
             headers["X-Payload-Version"] = str(version)
-        async with httpx.AsyncClient(timeout=10) as client:
+        # Derive timeout: dedicated WEBHOOK_DELIVERY_TIMEOUT_SECONDS or default HTTP client timeout
+        timeout_seconds = None
+        env_timeout = os.getenv("WEBHOOK_DELIVERY_TIMEOUT_SECONDS")
+        if env_timeout:
+            try:
+                timeout_seconds = float(env_timeout)
+            except ValueError:
+                timeout_seconds = get_default_timeout_seconds()
+        else:
+            timeout_seconds = get_default_timeout_seconds()
+
+        async with new_async_httpx_client(timeout_seconds=timeout_seconds) as client:
             resp = await client.post(url, json=delivery_payload, headers=headers)
             if 200 <= resp.status_code < 300:
                 # record delivery and mark processed

svc_infra/jobs/queue.py

@@ -69,5 +69,13 @@ class InMemoryJobQueue:
                 job.last_error = error
                 # Exponential backoff: base * attempts
                 delay = job.backoff_seconds * max(1, job.attempts)
-                job.available_at = now + timedelta(seconds=delay)
+                if delay > 0:
+                    # Add a tiny fudge so an immediate subsequent poll in ultra-fast
+                    # environments (like our acceptance API) doesn't re-reserve the job.
+                    # This keeps tests deterministic without impacting semantics.
+                    job.available_at = now + timedelta(seconds=delay, milliseconds=250)
+                else:
+                    # When backoff is explicitly zero (e.g., unit tests forcing
+                    # immediate retry), make the job available right away.
+                    job.available_at = now
                 return

svc_infra/jobs/runner.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Awaitable, Callable, Optional
+
+from .queue import JobQueue
+
+ProcessFunc = Callable[[object], Awaitable[None]]
+
+
+class WorkerRunner:
+    """Cooperative worker loop with graceful stop.
+
+    - start(): begin polling the queue and processing jobs
+    - stop(grace_seconds): signal stop, wait up to grace for current job to finish
+    """
+
+    def __init__(self, queue: JobQueue, handler: ProcessFunc, *, poll_interval: float = 0.25):
+        self._queue = queue
+        self._handler = handler
+        self._poll_interval = poll_interval
+        self._task: Optional[asyncio.Task] = None
+        self._stopping = asyncio.Event()
+        self._inflight: Optional[asyncio.Task] = None
+
+    async def _loop(self) -> None:
+        try:
+            while not self._stopping.is_set():
+                job = self._queue.reserve_next()
+                if not job:
+                    await asyncio.sleep(self._poll_interval)
+                    continue
+
+                # Process one job; track in-flight task for stop()
+                async def _run():
+                    try:
+                        await self._handler(job)
+                    except Exception as exc:  # pragma: no cover
+                        self._queue.fail(job.id, error=str(exc))
+                        return
+                    self._queue.ack(job.id)
+
+                self._inflight = asyncio.create_task(_run())
+                try:
+                    await self._inflight
+                finally:
+                    self._inflight = None
+        finally:
+            # exiting loop
+            pass
+
+    def start(self) -> asyncio.Task:
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self._loop())
+        return self._task
+
+    async def stop(self, *, grace_seconds: float = 10.0) -> None:
+        self._stopping.set()
+        # Wait for in-flight job to complete, up to grace
+        if self._inflight is not None and not self._inflight.done():
+            try:
+                await asyncio.wait_for(self._inflight, timeout=grace_seconds)
+            except asyncio.TimeoutError:
+                # Give up; job will be retried if your queue supports visibility timeouts
+                pass
+        # Finally, wait for loop to exit (should be quick since stopping is set)
+        if self._task is not None:
+            try:
+                await asyncio.wait_for(self._task, timeout=max(0.1, self._poll_interval + 0.1))
+            except asyncio.TimeoutError:
+                # Cancel as a last resort
+                self._task.cancel()
+                with contextlib.suppress(Exception):
+                    await self._task

svc_infra/jobs/worker.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import asyncio
+import os
 from typing import Awaitable, Callable
 
 from .queue import Job, JobQueue
@@ -7,6 +9,16 @@ 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.
 
@@ -16,7 +28,11 @@ async def process_one(queue: JobQueue, handler: ProcessFunc) -> bool:
     if not job:
         return False
     try:
-        await handler(job)
+        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

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/models.py

@@ -6,7 +6,17 @@ import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Optional
 
-from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Index, String, Text, UniqueConstraint
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    text,
+)
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from svc_infra.db.sql.base import ModelBase
@@ -34,7 +44,7 @@ class AuthSession(ModelBase):
     )
 
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
 
@@ -54,7 +64,7 @@ class RefreshToken(ModelBase):
     expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), index=True)
 
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
     __table_args__ = (UniqueConstraint("token_hash", name="uq_refresh_token_hash"),)
@@ -126,7 +136,7 @@ class Organization(ModelBase):
     slug: Mapped[Optional[str]] = mapped_column(String(64), index=True)
     tenant_id: Mapped[Optional[str]] = mapped_column(String(64), index=True)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
 
@@ -139,7 +149,7 @@ class Team(ModelBase):
     )
     name: Mapped[str] = mapped_column(String(128), nullable=False)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
 
 
@@ -155,7 +165,7 @@ class OrganizationMembership(ModelBase):
     )
     role: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
     deactivated_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
 
@@ -177,7 +187,7 @@ class OrganizationInvitation(ModelBase):
         GUID(), ForeignKey("users.id", ondelete="SET NULL"), index=True
     )
     created_at = mapped_column(
-        DateTime(timezone=True), server_default="CURRENT_TIMESTAMP", nullable=False
+        DateTime(timezone=True), server_default=text("CURRENT_TIMESTAMP"), nullable=False
     )
     last_sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
     resend_count: Mapped[int] = mapped_column(default=0)
@@ -185,6 +195,11 @@ class OrganizationInvitation(ModelBase):
     revoked_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True))
 
 
+# ------------------------ OAuth Provider Accounts -----------------------------
+# MOVED to svc_infra.security.oauth_models for opt-in OAuth support
+# Projects that enable OAuth should import ProviderAccount from there
+
+
 # ------------------------ Utilities -------------------------------------------
 
 
@@ -238,6 +253,11 @@ __all__ = [
     "FailedAuthAttempt",
     "RolePermission",
     "AuditLog",
+    "Organization",
+    "Team",
+    "OrganizationMembership",
+    "OrganizationInvitation",
+    # ProviderAccount moved to svc_infra.security.oauth_models (opt-in)
     "generate_refresh_token",
     "hash_refresh_token",
     "compute_audit_hash",