svc-infra 0.1.598__py3-none-any.whl → 0.1.599__py3-none-any.whl

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/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",
+]

svc_infra/webhooks/__init__.py

@@ -1 +1,16 @@
 from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers only
+    from .add import add_webhooks
+
+__all__ = ["add_webhooks"]
+
+
+def __getattr__(name: str):
+    if name == "add_webhooks":
+        from .add import add_webhooks
+
+        return add_webhooks
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

svc_infra/webhooks/add.py

@@ -0,0 +1,322 @@
+from __future__ import annotations
+
+"""FastAPI integration helpers for the webhooks router.
+
+The :func:`add_webhooks` helper wires the public router into an app and makes
+sure dependency overrides share a single set of stores instead of the in-file
+defaults that create a new in-memory object per request.  Callers can:
+
+* rely on the in-memory defaults (suitable for tests / local usage);
+* configure persistent stores through environment variables; or
+* provide concrete instances / factories explicitly via keyword arguments.
+
+When queue / scheduler objects are provided the helper also wires up the
+standard outbox tick task and webhook delivery job handler so the caller only
+needs to start their existing worker loop.
+"""
+
+import json
+import logging
+import os
+from collections.abc import Callable, Mapping
+from datetime import datetime, timezone
+from typing import Any, Protocol, TypeVar, overload
+
+from fastapi import FastAPI
+
+from svc_infra.db.inbox import InboxStore, InMemoryInboxStore
+from svc_infra.db.outbox import InMemoryOutboxStore, OutboxMessage, OutboxStore
+from svc_infra.jobs.builtins.outbox_processor import make_outbox_tick
+from svc_infra.jobs.builtins.webhook_delivery import make_webhook_handler
+from svc_infra.jobs.queue import JobQueue
+from svc_infra.jobs.scheduler import InMemoryScheduler
+
+from . import router as router_module
+from .service import InMemoryWebhookSubscriptions
+
+try:  # Optional dependency – only required when redis backends are selected.
+    from redis import Redis
+except Exception:  # pragma: no cover - redis is optional in most test runs.
+    Redis = None  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+
+T = TypeVar("T")
+
+
+class _Factory(Protocol[T]):
+    def __call__(self) -> T:
+        ...
+
+
+class RedisOutboxStore(OutboxStore):
+    """Minimal Redis-backed outbox implementation used by :func:`add_webhooks`.
+
+    The implementation is intentionally lightweight – it keeps message payloads
+    in Redis hashes and a FIFO list of message identifiers.  It fulfils the
+    contract expected by :func:`make_outbox_tick` while remaining simple enough
+    for environments where a fully fledged SQL implementation is unavailable.
+    """
+
+    def __init__(self, client: "Redis", *, prefix: str = "webhooks:outbox"):
+        if Redis is None:  # pragma: no cover - defensive guard
+            raise RuntimeError("redis-py is required for RedisOutboxStore")
+        self._client = client
+        self._prefix = prefix.rstrip(":")
+
+    # Redis key helpers -------------------------------------------------
+    @property
+    def _seq_key(self) -> str:
+        return f"{self._prefix}:seq"
+
+    @property
+    def _queue_key(self) -> str:
+        return f"{self._prefix}:queue"
+
+    def _msg_key(self, msg_id: int) -> str:
+        return f"{self._prefix}:msg:{msg_id}"
+
+    # Protocol methods --------------------------------------------------
+    def enqueue(self, topic: str, payload: dict[str, Any]) -> OutboxMessage:
+        msg_id = int(self._client.incr(self._seq_key))
+        created_at = datetime.now(timezone.utc)
+        record = {
+            "id": msg_id,
+            "topic": topic,
+            "payload": json.dumps(payload),
+            "created_at": created_at.isoformat(),
+            "attempts": 0,
+            "processed_at": "",
+        }
+        self._client.hset(self._msg_key(msg_id), mapping=record)
+        self._client.rpush(self._queue_key, msg_id)
+        return OutboxMessage(id=msg_id, topic=topic, payload=payload, created_at=created_at)
+
+    def fetch_next(
+        self, *, topics: list[str] | tuple[str, ...] | set[str] | None = None
+    ) -> OutboxMessage | None:
+        allowed = set(topics) if topics else None
+        ids = self._client.lrange(self._queue_key, 0, -1)
+        for raw_id in ids:
+            msg_id = int(raw_id)
+            msg = self._client.hgetall(self._msg_key(msg_id))
+            if not msg:
+                continue
+            topic = msg.get(b"topic")
+            if topic is None:
+                continue
+            topic_str = topic.decode()
+            if allowed is not None and topic_str not in allowed:
+                continue
+            attempts = int(msg.get(b"attempts", 0))
+            processed_raw = msg.get(b"processed_at") or b""
+            if processed_raw:
+                continue
+            if attempts > 0:
+                continue
+            payload_raw = msg.get(b"payload") or b"{}"
+            payload = json.loads(payload_raw.decode())
+            created_raw = msg.get(b"created_at") or ""
+            created_at = (
+                datetime.fromisoformat(created_raw.decode()) if created_raw else datetime.now(timezone.utc)
+            )
+            return OutboxMessage(
+                id=msg_id,
+                topic=topic_str,
+                payload=payload,
+                created_at=created_at,
+                attempts=attempts,
+            )
+        return None
+
+    def mark_processed(self, msg_id: int) -> None:
+        key = self._msg_key(msg_id)
+        if not self._client.exists(key):
+            return
+        self._client.hset(key, "processed_at", datetime.now(timezone.utc).isoformat())
+
+    def mark_failed(self, msg_id: int) -> None:
+        key = self._msg_key(msg_id)
+        self._client.hincrby(key, "attempts", 1)
+
+
+class RedisInboxStore(InboxStore):
+    """Lightweight Redis dedupe store for webhook deliveries."""
+
+    def __init__(self, client: "Redis", *, prefix: str = "webhooks:inbox"):
+        if Redis is None:  # pragma: no cover - defensive guard
+            raise RuntimeError("redis-py is required for RedisInboxStore")
+        self._client = client
+        self._prefix = prefix.rstrip(":")
+
+    def _key(self, key: str) -> str:
+        return f"{self._prefix}:{key}"
+
+    def mark_if_new(self, key: str, ttl_seconds: int = 24 * 3600) -> bool:
+        return bool(self._client.set(self._key(key), 1, nx=True, ex=ttl_seconds))
+
+    def purge_expired(self) -> int:
+        # Redis takes care of expirations. We return 0 to satisfy the interface.
+        return 0
+
+    def is_marked(self, key: str) -> bool:
+        return bool(self._client.exists(self._key(key)))
+
+
+def _is_factory(obj: Any) -> bool:
+    return callable(obj) and not isinstance(obj, (str, bytes, bytearray))
+
+
+def _resolve_value(value: T | _Factory[T] | None, default_factory: _Factory[T]) -> T:
+    if value is None:
+        return default_factory()
+    if _is_factory(value):
+        return value()  # type: ignore[return-value]
+    return value  # type: ignore[return-value]
+
+
+def _build_redis_client(env: Mapping[str, str]) -> "Redis" | None:
+    if Redis is None:
+        logger.warning("Redis backend requested but redis-py is not installed; falling back to in-memory stores")
+        return None
+    url = env.get("REDIS_URL", "redis://localhost:6379/0")
+    return Redis.from_url(url)
+
+
+def _default_outbox(env: Mapping[str, str]) -> OutboxStore:
+    backend = (env.get("WEBHOOKS_OUTBOX") or "memory").lower()
+    if backend == "redis":
+        client = _build_redis_client(env)
+        if client is not None:
+            logger.info("Using Redis outbox store for webhooks")
+            return RedisOutboxStore(client)
+    elif backend == "sql":  # pragma: no cover - SQL backend is currently a placeholder
+        logger.warning(
+            "WEBHOOKS_OUTBOX=sql specified but SQL backend is not implemented; falling back to in-memory store"
+        )
+    return InMemoryOutboxStore()
+
+
+def _default_inbox(env: Mapping[str, str]) -> InboxStore:
+    backend = (env.get("WEBHOOKS_INBOX") or "memory").lower()
+    if backend == "redis":
+        client = _build_redis_client(env)
+        if client is not None:
+            logger.info("Using Redis inbox store for webhooks")
+            return RedisInboxStore(client)
+    return InMemoryInboxStore()
+
+
+def _default_subscriptions() -> InMemoryWebhookSubscriptions:
+    return InMemoryWebhookSubscriptions()
+
+
+def _subscription_lookup(subs: InMemoryWebhookSubscriptions) -> tuple[Callable[[str], str], Callable[[str], str]]:
+    def _get_url(topic: str) -> str:
+        items = subs.get_for_topic(topic)
+        if not items:
+            raise LookupError(f"No webhook subscription for topic '{topic}'")
+        return items[0].url
+
+    def _get_secret(topic: str) -> str:
+        items = subs.get_for_topic(topic)
+        if not items:
+            raise LookupError(f"No webhook subscription for topic '{topic}'")
+        return items[0].secret
+
+    return _get_url, _get_secret
+
+
+@overload
+def add_webhooks(
+    app: FastAPI,
+    *,
+    outbox: OutboxStore | _Factory[OutboxStore] | None = ...,
+    inbox: InboxStore | _Factory[InboxStore] | None = ...,
+    subscriptions: InMemoryWebhookSubscriptions | _Factory[InMemoryWebhookSubscriptions] | None = ...,
+    queue: JobQueue | None = ...,
+    scheduler: InMemoryScheduler | None = ...,
+    schedule_tick: bool = ...,
+    env: Mapping[str, str] = ...,
+) -> None:
+    ...
+
+
+def add_webhooks(
+    app: FastAPI,
+    *,
+    outbox: OutboxStore | _Factory[OutboxStore] | None = None,
+    inbox: InboxStore | _Factory[InboxStore] | None = None,
+    subscriptions: InMemoryWebhookSubscriptions | _Factory[InMemoryWebhookSubscriptions] | None = None,
+    queue: JobQueue | None = None,
+    scheduler: InMemoryScheduler | None = None,
+    schedule_tick: bool = True,
+    env: Mapping[str, str] = os.environ,
+) -> None:
+    """Attach the shared webhooks router and stores to a FastAPI app.
+
+    Parameters
+    ----------
+    app:
+        The FastAPI application to configure.
+    outbox / inbox / subscriptions:
+        Optional instances or callables returning instances to use.  When left
+        as ``None`` the helper chooses sensible defaults: in-memory stores for
+        local runs or Redis-backed stores when ``WEBHOOKS_OUTBOX`` /
+        ``WEBHOOKS_INBOX`` are set to ``"redis"`` and ``REDIS_URL`` is
+        available.
+    queue / scheduler:
+        Provide these when you want :func:`make_outbox_tick` and the webhook
+        delivery handler registered for you.  The tick task is scheduled every
+        second by default; disable that registration by passing
+        ``schedule_tick=False``.
+    env:
+        Mapping used to resolve environment-driven defaults.  Defaults to
+        :data:`os.environ` so standard environment variables Just Work.
+
+    Side effects
+    ------------
+    * ``app.include_router`` is invoked for :mod:`svc_infra.webhooks.router`.
+    * ``app.dependency_overrides`` is populated so router dependencies reuse the
+      shared stores.
+    * References are stored on ``app.state`` for further customisation:
+      ``webhooks_outbox``, ``webhooks_inbox``, ``webhooks_subscriptions``,
+      ``webhooks_outbox_tick`` (when a queue is present) and
+      ``webhooks_delivery_handler`` (when queue+inbox are present).
+    """
+
+    resolved_outbox = _resolve_value(outbox, lambda: _default_outbox(env))
+    resolved_inbox = _resolve_value(inbox, lambda: _default_inbox(env))
+    resolved_subs = _resolve_value(subscriptions, _default_subscriptions)
+
+    app.state.webhooks_outbox = resolved_outbox
+    app.state.webhooks_inbox = resolved_inbox
+    app.state.webhooks_subscriptions = resolved_subs
+
+    app.include_router(router_module.router)
+
+    app.dependency_overrides[router_module.get_outbox] = lambda: resolved_outbox
+    app.dependency_overrides[router_module.get_subs] = lambda: resolved_subs
+
+    outbox_tick = None
+    if queue is not None:
+        outbox_tick = make_outbox_tick(resolved_outbox, queue)
+        app.state.webhooks_outbox_tick = outbox_tick
+        if scheduler is not None and schedule_tick:
+            scheduler.add_task("webhooks.outbox", 1, outbox_tick)
+
+        url_lookup, secret_lookup = _subscription_lookup(resolved_subs)
+        handler = make_webhook_handler(
+            outbox=resolved_outbox,
+            inbox=resolved_inbox,
+            get_webhook_url_for_topic=url_lookup,
+            get_secret_for_topic=secret_lookup,
+        )
+        app.state.webhooks_delivery_handler = handler
+    elif scheduler is not None and schedule_tick:
+        logger.warning("Scheduler provided without queue; skipping outbox tick registration")
+
+
+__all__ = ["add_webhooks"]
+

svc_infra-0.1.599.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.3
+Name: svc-infra
+Version: 0.1.599
+Summary: Infrastructure for building and deploying prod-ready services
+License: MIT
+Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
+Author: Ali Khatami
+Author-email: aliikhatami94@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Provides-Extra: duckdb
+Provides-Extra: metrics
+Provides-Extra: mssql
+Provides-Extra: mysql
+Provides-Extra: pg
+Provides-Extra: pg2
+Provides-Extra: redshift
+Provides-Extra: snowflake
+Provides-Extra: sqlite
+Requires-Dist: adyen (>=13.4.0,<14.0.0)
+Requires-Dist: ai-infra (>=0.1.63,<0.2.0)
+Requires-Dist: aiosqlite (>=0.20.0,<0.21.0) ; extra == "sqlite"
+Requires-Dist: alembic (>=1.13.2,<2.0.0)
+Requires-Dist: asyncpg (>=0.30.0,<0.31.0) ; extra == "pg"
+Requires-Dist: authlib (>=1.6.2,<2.0.0)
+Requires-Dist: cashews[redis] (>=7.4.1,<8.0.0)
+Requires-Dist: duckdb (>=1.1.3,<2.0.0) ; extra == "duckdb"
+Requires-Dist: email-validator (>=2.2.0,<3.0.0)
+Requires-Dist: fastapi (>=0.116.1,<0.117.0)
+Requires-Dist: fastapi-users-db-sqlalchemy (>=7.0.0,<8.0.0)
+Requires-Dist: fastapi-users[oauth] (>=14.0.1,<15.0.0)
+Requires-Dist: greenlet (>=3,<4)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: httpx-oauth (>=0.16.1,<0.17.0)
+Requires-Dist: itsdangerous (>=2.2.0,<3.0.0)
+Requires-Dist: mcp (>=1.13.0,<2.0.0)
+Requires-Dist: motor (>=3.7.1,<4.0.0)
+Requires-Dist: mysqlclient (>=2.2.4,<3.0.0) ; extra == "mysql"
+Requires-Dist: opentelemetry-exporter-otlp (>=1.36.0,<2.0.0)
+Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.57b0,<0.58)
+Requires-Dist: opentelemetry-instrumentation-httpx (>=0.57b0,<0.58)
+Requires-Dist: opentelemetry-instrumentation-requests (>=0.57b0,<0.58)
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy (>=0.57b0,<0.58)
+Requires-Dist: opentelemetry-propagator-b3 (>=1.36.0,<2.0.0)
+Requires-Dist: opentelemetry-sdk (>=1.36.0,<2.0.0)
+Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
+Requires-Dist: pre-commit (>=4.3.0,<5.0.0)
+Requires-Dist: prometheus-client (>=0.22.1,<0.23.0) ; extra == "metrics"
+Requires-Dist: psycopg2-binary (>=2.9.10,<3.0.0) ; extra == "pg2"
+Requires-Dist: psycopg[binary] (>=3.2.10,<4.0.0) ; extra == "pg"
+Requires-Dist: pydantic-settings (>=2.10.1,<3.0.0)
+Requires-Dist: pymysql (>=1.1.1,<2.0.0) ; extra == "mysql"
+Requires-Dist: pyodbc (>=5.1.0,<6.0.0) ; extra == "mssql"
+Requires-Dist: pyotp (>=2.9.0,<3.0.0)
+Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
+Requires-Dist: redis (>=6.4.0,<7.0.0)
+Requires-Dist: redshift-connector (>=2.0.918,<3.0.0) ; extra == "redshift"
+Requires-Dist: snowflake-connector-python (>=3.12.0,<4.0.0) ; extra == "snowflake"
+Requires-Dist: sqlalchemy[asyncio] (>=2.0.43,<3.0.0)
+Requires-Dist: stripe (>=13.0.1,<14.0.0)
+Requires-Dist: typer (>=0.16.1,<0.17.0)
+Project-URL: Documentation, https://github.com/your-org/svc-infra#readme
+Project-URL: Homepage, https://github.com/your-org/svc-infra
+Project-URL: Issues, https://github.com/your-org/svc-infra/issues
+Project-URL: Repository, https://github.com/your-org/svc-infra
+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/)
+
+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 |
+| --- | --- | --- |
+| 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) |
+
+## Minimal FastAPI bootstrap
+
+```python
+from fastapi import Depends
+from svc_infra.api.fastapi.ease import easy_service_app
+from svc_infra.api.fastapi.db.sql.add import add_sql_db
+from svc_infra.cache import init_cache
+from svc_infra.jobs.easy import easy_jobs
+from svc_infra.webhooks.fastapi import require_signature
+
+app = easy_service_app(name="Billing", release="1.2.3")
+add_sql_db(app)              # reads SQL_URL / DB_* envs
+init_cache()                 # honors CACHE_PREFIX / CACHE_VERSION
+queue, scheduler = easy_jobs()  # switches via JOBS_DRIVER / REDIS_URL
+
+@app.post("/webhooks/billing")
+async def handle_webhook(payload = Depends(require_signature(lambda: ["current", "next"]))):
+    queue.enqueue("process-billing-webhook", payload)
+    return {"status": "queued"}
+```
+
+## Environment switches
+
+- **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】
+- **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】
+

{svc_infra-0.1.598.dist-info → svc_infra-0.1.599.dist-info}/RECORD

@@ -204,7 +204,7 @@ svc_infra/jobs/scheduler.py,sha256=dTUEEyEuTVHNmJT8wPdMu4YjnTN7R_YW67gtCKpqC7M,1
 svc_infra/jobs/worker.py,sha256=T2A575_mnieJHPOYU_FseubLA_HQf9pB4CkRgzRJBHU,694
 svc_infra/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/mcp/svc_infra_mcp.py,sha256=NmBY7AM3_pnHAumE-eM5Njr8kpb7Gh1-fjcZAEammiI,1927
-svc_infra/obs/README.md,sha256=wOABJUOhuj0ftGt24ZfuChlFNJTYvYq4KM_rcRIdWRU,7884
+svc_infra/obs/README.md,sha256=pmd6AyFZW3GCCi0sr3uTHrPj5KgAI8rrXw8QPkrf1R8,8021
 svc_infra/obs/__init__.py,sha256=t5DgkiuuhHnfAHChzYqCI1-Fpr68iQ0A1nHOLFIlAuM,75
 svc_infra/obs/add.py,sha256=j8Nsv6k7mGM7tGFIoCxgSpFNV93G_WmtSbCIBohHRT4,2026
 svc_infra/obs/cloud_dash.py,sha256=1rg6NO9kjhN3zCugfBqDxkTN5nQqjQRC5ye2gFxb6g4,4329
@@ -250,6 +250,7 @@ svc_infra/obs/templates/sidecars/railway/README.md,sha256=3tFBJPKvmxjg3FjtfGYLwB
 svc_infra/obs/templates/sidecars/railway/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 svc_infra/obs/templates/sidecars/railway/agent.yaml,sha256=hYv35yG92XEP_4joMFmMcVTD-4fG_zHitmChjreUJh4,516
 svc_infra/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+svc_infra/security/add.py,sha256=VrGPDUSXnGX3caNXi4BbqNllSQ5YGsZzBtKESWXDJzA,6114
 svc_infra/security/audit.py,sha256=r_OrXAz5uIa2o5nVD-8lsWqzggRGDKfp2sWd8URlz-E,4355
 svc_infra/security/audit_service.py,sha256=Xd5V7Iz6PS4YpxmLyJypnaqr8poaaleKwAI2uFF7y1A,2351
 svc_infra/security/headers.py,sha256=1VkAe-IWzPYfHxeZAnv9QwtzD7fP9NBTJw3mflW17bQ,1461
@@ -263,12 +264,13 @@ svc_infra/security/permissions.py,sha256=fQm7-OcJJkWsScDcjS2gwmqaW93zQqltaHRl6bv
 svc_infra/security/session.py,sha256=JkClqoZ-Moo9yqHzCREXMVSpzyjbn2Zh6zCjtWO93Ik,2848
 svc_infra/security/signed_cookies.py,sha256=2t61BgjsBaTzU46bt7IUJo7lwDRE9_eS4vmAQXJ8mlY,2219
 svc_infra/utils.py,sha256=VX1yjTx61-YvAymyRhGy18DhybiVdPddiYD_FlKTbJU,952
-svc_infra/webhooks/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+svc_infra/webhooks/__init__.py,sha256=fvPhbFoS6whoT67DWp43pL3m1o-et104vwqxunCUAPA,398
+svc_infra/webhooks/add.py,sha256=u9Spfwg0ztQmXg7uXP1sZ9-_qwnagnW4UnV9HvQtPwc,12191
 svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA,1101
 svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
 svc_infra/webhooks/service.py,sha256=hWgiJRXKBwKunJOx91C7EcLUkotDtD3Xp0RT6vj2IC0,1797
 svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
-svc_infra-0.1.598.dist-info/METADATA,sha256=OwFbEqh9yMLpWr5rcN3Bp0M_ywJypISbUxabiMuQZY8,3527
-svc_infra-0.1.598.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-svc_infra-0.1.598.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
-svc_infra-0.1.598.dist-info/RECORD,,
+svc_infra-0.1.599.dist-info/METADATA,sha256=dIULp2nBSVBybFpHOi0m0LEZRZe0dYUTYZPJYve8i1w,7839
+svc_infra-0.1.599.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.599.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.599.dist-info/RECORD,,

svc_infra-0.1.598.dist-info/METADATA

@@ -1,80 +0,0 @@
-Metadata-Version: 2.3
-Name: svc-infra
-Version: 0.1.598
-Summary: Infrastructure for building and deploying prod-ready services
-License: MIT
-Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
-Author: Ali Khatami
-Author-email: aliikhatami94@gmail.com
-Requires-Python: >=3.11,<4.0
-Classifier: Development Status :: 4 - Beta
-Classifier: Framework :: FastAPI
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Typing :: Typed
-Provides-Extra: duckdb
-Provides-Extra: metrics
-Provides-Extra: mssql
-Provides-Extra: mysql
-Provides-Extra: pg
-Provides-Extra: pg2
-Provides-Extra: redshift
-Provides-Extra: snowflake
-Provides-Extra: sqlite
-Requires-Dist: adyen (>=13.4.0,<14.0.0)
-Requires-Dist: ai-infra (>=0.1.63,<0.2.0)
-Requires-Dist: aiosqlite (>=0.20.0,<0.21.0) ; extra == "sqlite"
-Requires-Dist: alembic (>=1.13.2,<2.0.0)
-Requires-Dist: asyncpg (>=0.30.0,<0.31.0) ; extra == "pg"
-Requires-Dist: authlib (>=1.6.2,<2.0.0)
-Requires-Dist: cashews[redis] (>=7.4.1,<8.0.0)
-Requires-Dist: duckdb (>=1.1.3,<2.0.0) ; extra == "duckdb"
-Requires-Dist: email-validator (>=2.2.0,<3.0.0)
-Requires-Dist: fastapi (>=0.116.1,<0.117.0)
-Requires-Dist: fastapi-users-db-sqlalchemy (>=7.0.0,<8.0.0)
-Requires-Dist: fastapi-users[oauth] (>=14.0.1,<15.0.0)
-Requires-Dist: greenlet (>=3,<4)
-Requires-Dist: httpx (>=0.28.1,<0.29.0)
-Requires-Dist: httpx-oauth (>=0.16.1,<0.17.0)
-Requires-Dist: itsdangerous (>=2.2.0,<3.0.0)
-Requires-Dist: mcp (>=1.13.0,<2.0.0)
-Requires-Dist: motor (>=3.7.1,<4.0.0)
-Requires-Dist: mysqlclient (>=2.2.4,<3.0.0) ; extra == "mysql"
-Requires-Dist: opentelemetry-exporter-otlp (>=1.36.0,<2.0.0)
-Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.57b0,<0.58)
-Requires-Dist: opentelemetry-instrumentation-httpx (>=0.57b0,<0.58)
-Requires-Dist: opentelemetry-instrumentation-requests (>=0.57b0,<0.58)
-Requires-Dist: opentelemetry-instrumentation-sqlalchemy (>=0.57b0,<0.58)
-Requires-Dist: opentelemetry-propagator-b3 (>=1.36.0,<2.0.0)
-Requires-Dist: opentelemetry-sdk (>=1.36.0,<2.0.0)
-Requires-Dist: passlib[bcrypt] (>=1.7.4,<2.0.0)
-Requires-Dist: pre-commit (>=4.3.0,<5.0.0)
-Requires-Dist: prometheus-client (>=0.22.1,<0.23.0) ; extra == "metrics"
-Requires-Dist: psycopg2-binary (>=2.9.10,<3.0.0) ; extra == "pg2"
-Requires-Dist: psycopg[binary] (>=3.2.10,<4.0.0) ; extra == "pg"
-Requires-Dist: pydantic-settings (>=2.10.1,<3.0.0)
-Requires-Dist: pymysql (>=1.1.1,<2.0.0) ; extra == "mysql"
-Requires-Dist: pyodbc (>=5.1.0,<6.0.0) ; extra == "mssql"
-Requires-Dist: pyotp (>=2.9.0,<3.0.0)
-Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
-Requires-Dist: redis (>=6.4.0,<7.0.0)
-Requires-Dist: redshift-connector (>=2.0.918,<3.0.0) ; extra == "redshift"
-Requires-Dist: snowflake-connector-python (>=3.12.0,<4.0.0) ; extra == "snowflake"
-Requires-Dist: sqlalchemy[asyncio] (>=2.0.43,<3.0.0)
-Requires-Dist: stripe (>=13.0.1,<14.0.0)
-Requires-Dist: typer (>=0.16.1,<0.17.0)
-Project-URL: Documentation, https://github.com/your-org/svc-infra#readme
-Project-URL: Homepage, https://github.com/your-org/svc-infra
-Project-URL: Issues, https://github.com/your-org/svc-infra/issues
-Project-URL: Repository, https://github.com/your-org/svc-infra
-Description-Content-Type: text/markdown
-
-# svc-infra
-
-Will add description later.
-