svc-infra 0.1.597__tar.gz → 0.1.599__tar.gz

svc_infra-0.1.599/PKG-INFO

@@ -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.599/README.md

@@ -0,0 +1,51 @@
+# 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.597 → svc_infra-0.1.599}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.597"
+version = "0.1.599"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"
@@ -125,6 +125,7 @@ markers = [
     "ratelimit: Rate limiting and abuse protection tests",
     "concurrency: Idempotency and concurrency control tests",
     "jobs: Background jobs and scheduling tests",
+    "webhooks: Webhooks framework tests",
 ]
 filterwarnings = [
     "ignore:The `route` decorator is deprecated:DeprecationWarning:starlette.*",

{svc_infra-0.1.597 → svc_infra-0.1.599}/src/svc_infra/db/inbox.py

@@ -13,6 +13,10 @@ class InboxStore(Protocol):
         """Optional: remove expired keys, return number purged."""
         ...
 
+    def is_marked(self, key: str) -> bool:
+        """Return True if key is already marked (not expired), without modifying it."""
+        ...
+
 
 class InMemoryInboxStore:
     def __init__(self) -> None:
@@ -33,6 +37,11 @@ class InMemoryInboxStore:
             self._keys.pop(k, None)
         return len(to_del)
 
+    def is_marked(self, key: str) -> bool:
+        now = time.time()
+        exp = self._keys.get(key)
+        return bool(exp and exp > now)
+
 
 class SqlInboxStore:
     """Skeleton for a SQL-backed inbox store (dedupe table).
@@ -53,3 +62,6 @@ class SqlInboxStore:
 
     def purge_expired(self) -> int:  # pragma: no cover - skeleton
         raise NotImplementedError
+
+    def is_marked(self, key: str) -> bool:  # pragma: no cover - skeleton
+        raise NotImplementedError

svc_infra-0.1.599/src/svc_infra/jobs/builtins/webhook_delivery.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import httpx
+
+from svc_infra.db.inbox import InboxStore
+from svc_infra.db.outbox import OutboxStore
+from svc_infra.jobs.queue import Job
+from svc_infra.webhooks.signing import sign
+
+
+def make_webhook_handler(
+    *,
+    outbox: OutboxStore,
+    inbox: InboxStore,
+    get_webhook_url_for_topic,
+    get_secret_for_topic,
+    header_name: str = "X-Signature",
+):
+    """Return an async job handler to deliver webhooks.
+
+    Expected job payload shape:
+    {"outbox_id": int, "topic": str, "payload": {...}}
+    """
+
+    async def _handler(job: Job) -> None:
+        data = job.payload or {}
+        outbox_id = data.get("outbox_id")
+        topic = data.get("topic")
+        payload = data.get("payload") or {}
+        if not outbox_id or not topic:
+            # Nothing we can do; ack to avoid poison loop
+            return
+        # dedupe marker key (marked after successful delivery)
+        key = f"webhook:{outbox_id}"
+        if inbox.is_marked(key):
+            # already delivered
+            outbox.mark_processed(int(outbox_id))
+            return
+        event = payload.get("event") if isinstance(payload, dict) else None
+        subscription = payload.get("subscription") if isinstance(payload, dict) else None
+        if event is not None and subscription is not None:
+            delivery_payload = event
+            url = subscription.get("url") or get_webhook_url_for_topic(topic)
+            secret = subscription.get("secret") or get_secret_for_topic(topic)
+            subscription_id = subscription.get("id")
+        else:
+            delivery_payload = payload
+            url = get_webhook_url_for_topic(topic)
+            secret = get_secret_for_topic(topic)
+            subscription_id = None
+        sig = sign(secret, delivery_payload)
+        headers = {
+            header_name: sig,
+            "X-Event-Id": str(outbox_id),
+            "X-Topic": str(topic),
+            "X-Attempt": str(job.attempts or 1),
+            "X-Signature-Alg": "hmac-sha256",
+            "X-Signature-Version": "v1",
+        }
+        if subscription_id:
+            headers["X-Webhook-Subscription"] = str(subscription_id)
+        # include event payload version if present
+        version = None
+        if isinstance(delivery_payload, dict):
+            version = delivery_payload.get("version")
+        if version is not None:
+            headers["X-Payload-Version"] = str(version)
+        async with httpx.AsyncClient(timeout=10) as client:
+            resp = await client.post(url, json=delivery_payload, headers=headers)
+            if 200 <= resp.status_code < 300:
+                # record delivery and mark processed
+                inbox.mark_if_new(key, ttl_seconds=24 * 3600)
+                outbox.mark_processed(int(outbox_id))
+                return
+            # allow retry on non-2xx: raise to trigger fail/backoff
+            raise RuntimeError(f"webhook delivery failed: {resp.status_code}")
+
+    return _handler

{svc_infra-0.1.597 → svc_infra-0.1.599}/src/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-0.1.599/src/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-0.1.599/src/svc_infra/webhooks/__init__.py

@@ -0,0 +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}")