svc-infra 0.1.600__tar.gz → 0.1.602__tar.gz

{svc_infra-0.1.600 → svc_infra-0.1.602}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.600
+Version: 0.1.602
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

{svc_infra-0.1.600 → svc_infra-0.1.602}/pyproject.toml

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

{svc_infra-0.1.600 → svc_infra-0.1.602}/src/svc_infra/api/fastapi/db/sql/add.py

@@ -10,7 +10,7 @@ from svc_infra.db.sql.management import make_crud_schemas
 from svc_infra.db.sql.repository import SqlRepository
 from svc_infra.db.sql.resource import SqlResource
 
-from .crud_router import make_crud_router_plus_sql
+from .crud_router import make_crud_router_plus_sql, make_tenant_crud_router_plus_sql
 from .health import _make_db_health_router
 from .session import dispose_session, initialize_session
 
@@ -37,18 +37,37 @@ def add_sql_resources(app: FastAPI, resources: Sequence[SqlResource]) -> None:
                 update_name=r.update_name,
             )
 
-        router = make_crud_router_plus_sql(
-            model=r.model,
-            service=svc,
-            read_schema=Read,
-            create_schema=Create,
-            update_schema=Update,
-            prefix=r.prefix,
-            tags=r.tags,
-            search_fields=r.search_fields,
-            default_ordering=r.ordering_default,
-            allowed_order_fields=r.allowed_order_fields,
-        )
+        if r.tenant_field:
+            # wrap service factory/instance through tenant router
+            def _factory():
+                return svc
+
+            router = make_tenant_crud_router_plus_sql(
+                model=r.model,
+                service_factory=_factory,
+                read_schema=Read,
+                create_schema=Create,
+                update_schema=Update,
+                prefix=r.prefix,
+                tenant_field=r.tenant_field,
+                tags=r.tags,
+                search_fields=r.search_fields,
+                default_ordering=r.ordering_default,
+                allowed_order_fields=r.allowed_order_fields,
+            )
+        else:
+            router = make_crud_router_plus_sql(
+                model=r.model,
+                service=svc,
+                read_schema=Read,
+                create_schema=Create,
+                update_schema=Update,
+                prefix=r.prefix,
+                tags=r.tags,
+                search_fields=r.search_fields,
+                default_ordering=r.ordering_default,
+                allowed_order_fields=r.allowed_order_fields,
+            )
         app.include_router(router)
 
 

svc_infra-0.1.602/src/svc_infra/api/fastapi/db/sql/crud_router.py

@@ -0,0 +1,292 @@
+from typing import Annotated, Any, Optional, Sequence, Type, TypeVar, cast
+
+from fastapi import APIRouter, Body, Depends, HTTPException
+from pydantic import BaseModel
+
+from svc_infra.api.fastapi.db.http import (
+    LimitOffsetParams,
+    OrderParams,
+    Page,
+    SearchParams,
+    build_order_by,
+    dep_limit_offset,
+    dep_order,
+    dep_search,
+)
+from svc_infra.api.fastapi.dual.public import public_router
+from svc_infra.db.sql.service import SqlService
+from svc_infra.db.sql.tenant import TenantSqlService
+
+from ...tenancy.context import TenantId
+from .session import SqlSessionDep
+
+CreateModel = TypeVar("CreateModel", bound=BaseModel)
+ReadModel = TypeVar("ReadModel", bound=BaseModel)
+UpdateModel = TypeVar("UpdateModel", bound=BaseModel)
+
+
+def make_crud_router_plus_sql(
+    *,
+    model: type[Any],
+    service: SqlService,
+    read_schema: Type[ReadModel],
+    create_schema: Type[CreateModel],
+    update_schema: Type[UpdateModel],
+    prefix: str,
+    tags: list[str] | None = None,
+    search_fields: Optional[Sequence[str]] = None,
+    default_ordering: Optional[str] = None,
+    allowed_order_fields: Optional[list[str]] = None,
+    mount_under_db_prefix: bool = True,
+) -> APIRouter:
+    router_prefix = ("/_sql" + prefix) if mount_under_db_prefix else prefix
+    router = public_router(
+        prefix=router_prefix,
+        tags=tags or [prefix.strip("/")],
+        redirect_slashes=False,
+    )
+
+    def _parse_ordering_to_fields(order_spec: Optional[str]) -> list[str]:
+        if not order_spec:
+            return []
+        pieces = [p.strip() for p in order_spec.split(",") if p.strip()]
+        fields: list[str] = []
+        for p in pieces:
+            name = p[1:] if p.startswith("-") else p
+            if allowed_order_fields and name not in (allowed_order_fields or []):
+                continue
+            fields.append(p)
+        return fields
+
+    # -------- LIST --------
+    @router.get(
+        "",
+        response_model=cast(Any, Page[Any]),
+        description=f"List items of type {model.__name__}",
+    )
+    async def list_items(
+        lp: Annotated[LimitOffsetParams, Depends(dep_limit_offset)],
+        op: Annotated[OrderParams, Depends(dep_order)],
+        sp: Annotated[SearchParams, Depends(dep_search)],
+        session: SqlSessionDep,  # type: ignore[name-defined]
+    ):
+        order_spec = op.order_by or default_ordering
+        order_fields = _parse_ordering_to_fields(order_spec)
+        order_by = build_order_by(model, order_fields)
+
+        if sp.q:
+            fields = [
+                f.strip()
+                for f in (sp.fields or (",".join(search_fields or []) or "")).split(",")
+                if f.strip()
+            ]
+            items = await service.search(
+                session, q=sp.q, fields=fields, limit=lp.limit, offset=lp.offset, order_by=order_by
+            )
+            total = await service.count_filtered(session, q=sp.q, fields=fields)
+        else:
+            items = await service.list(session, limit=lp.limit, offset=lp.offset, order_by=order_by)
+            total = await service.count(session)
+        return Page[read_schema].from_items(
+            total=total, items=items, limit=lp.limit, offset=lp.offset
+        )
+
+    # -------- GET by id --------
+    @router.get(
+        "/{item_id}",
+        response_model=cast(Any, Any),
+        description=f"Get item of type {model.__name__}",
+    )
+    async def get_item(item_id: Any, session: SqlSessionDep):  # type: ignore[name-defined]
+        row = await service.get(session, item_id)
+        if not row:
+            raise HTTPException(404, "Not found")
+        return row
+
+    # -------- CREATE --------
+    @router.post(
+        "",
+        response_model=cast(Any, Any),
+        status_code=201,
+        description=f"Create item of type {model.__name__}",
+    )
+    async def create_item(
+        session: SqlSessionDep,  # type: ignore[name-defined]
+        payload: Any = Body(...),
+    ):
+        if isinstance(payload, BaseModel):
+            data = payload.model_dump(exclude_unset=True)
+        elif isinstance(payload, dict):
+            data = payload
+        else:
+            raise HTTPException(422, "invalid_payload")
+        return await service.create(session, data)
+
+    # -------- UPDATE --------
+    @router.patch(
+        "/{item_id}",
+        response_model=cast(Any, Any),
+        description=f"Update item of type {model.__name__}",
+    )
+    async def update_item(
+        item_id: Any,
+        session: SqlSessionDep,  # type: ignore[name-defined]
+        payload: Any = Body(...),
+    ):
+        if isinstance(payload, BaseModel):
+            data = payload.model_dump(exclude_unset=True)
+        elif isinstance(payload, dict):
+            data = payload
+        else:
+            raise HTTPException(422, "invalid_payload")
+        row = await service.update(session, item_id, data)
+        if not row:
+            raise HTTPException(404, "Not found")
+        return row
+
+    # -------- DELETE --------
+    @router.delete(
+        "/{item_id}", status_code=204, description=f"Delete item of type {model.__name__}"
+    )
+    async def delete_item(item_id: Any, session: SqlSessionDep):  # type: ignore[name-defined]
+        ok = await service.delete(session, item_id)
+        if not ok:
+            raise HTTPException(404, "Not found")
+        return
+
+    return router
+
+
+def make_tenant_crud_router_plus_sql(
+    *,
+    model: type[Any],
+    service_factory: callable,  # factory that returns a SqlService (will be wrapped)
+    read_schema: Type[ReadModel],
+    create_schema: Type[CreateModel],
+    update_schema: Type[UpdateModel],
+    prefix: str,
+    tenant_field: str = "tenant_id",
+    tags: list[str] | None = None,
+    search_fields: Optional[Sequence[str]] = None,
+    default_ordering: Optional[str] = None,
+    allowed_order_fields: Optional[list[str]] = None,
+    mount_under_db_prefix: bool = True,
+) -> APIRouter:
+    """Like make_crud_router_plus_sql, but requires TenantId and scopes all operations."""
+    router_prefix = ("/_sql" + prefix) if mount_under_db_prefix else prefix
+    router = public_router(
+        prefix=router_prefix,
+        tags=tags or [prefix.strip("/")],
+        redirect_slashes=False,
+    )
+
+    def _parse_ordering_to_fields(order_spec: Optional[str]) -> list[str]:
+        if not order_spec:
+            return []
+        pieces = [p.strip() for p in order_spec.split(",") if p.strip()]
+        fields: list[str] = []
+        for p in pieces:
+            name = p[1:] if p.startswith("-") else p
+            if allowed_order_fields and name not in (allowed_order_fields or []):
+                continue
+            fields.append(p)
+        return fields
+
+    # create per-request service with tenant scoping
+    async def _svc(session: SqlSessionDep, tenant_id: TenantId):  # type: ignore[name-defined]
+        base = service_factory  # consumer-provided factory or instance
+        svc = base  # assume already a SqlService by default
+        if callable(base):
+            svc = base  # the consumer likely closed over repo
+            # if callable returns a service, call it now
+            try:
+                svc = base()  # type: ignore[misc]
+            except TypeError:
+                svc = base  # already instance
+        if not isinstance(svc, TenantSqlService):
+            svc = TenantSqlService(getattr(svc, "repo", svc), tenant_id=tenant_id, tenant_field=tenant_field)  # type: ignore[arg-type]
+        return svc  # type: ignore[return-value]
+
+    @router.get("", response_model=cast(Any, Page[Any]))
+    async def list_items(
+        lp: Annotated[LimitOffsetParams, Depends(dep_limit_offset)],
+        op: Annotated[OrderParams, Depends(dep_order)],
+        sp: Annotated[SearchParams, Depends(dep_search)],
+        session: SqlSessionDep,  # type: ignore[name-defined]
+        tenant_id: TenantId,
+    ):
+        svc = await _svc(session, tenant_id)
+        order_spec = op.order_by or default_ordering
+        order_fields = _parse_ordering_to_fields(order_spec)
+        order_by = build_order_by(model, order_fields)
+        if sp.q:
+            fields = [
+                f.strip()
+                for f in (sp.fields or (",".join(search_fields or []) or "")).split(",")
+                if f.strip()
+            ]
+            items = await svc.search(
+                session, q=sp.q, fields=fields, limit=lp.limit, offset=lp.offset, order_by=order_by
+            )
+            total = await svc.count_filtered(session, q=sp.q, fields=fields)
+        else:
+            items = await svc.list(session, limit=lp.limit, offset=lp.offset, order_by=order_by)
+            total = await svc.count(session)
+        return Page[read_schema].from_items(
+            total=total, items=items, limit=lp.limit, offset=lp.offset
+        )
+
+    @router.get("/{item_id}", response_model=cast(Any, Any))
+    async def get_item(item_id: Any, session: SqlSessionDep, tenant_id: TenantId):  # type: ignore[name-defined]
+        svc = await _svc(session, tenant_id)
+        row = await svc.get(session, item_id)
+        if not row:
+            raise HTTPException(404, "Not found")
+        return row
+
+    @router.post("", response_model=cast(Any, Any), status_code=201)
+    async def create_item(
+        session: SqlSessionDep,  # type: ignore[name-defined]
+        tenant_id: TenantId,
+        payload: Any = Body(...),
+    ):
+        svc = await _svc(session, tenant_id)
+        if isinstance(payload, BaseModel):
+            data = payload.model_dump(exclude_unset=True)
+        elif isinstance(payload, dict):
+            data = payload
+        else:
+            raise HTTPException(422, "invalid_payload")
+        return await svc.create(session, data)
+
+    @router.patch("/{item_id}", response_model=cast(Any, Any))
+    async def update_item(
+        item_id: Any,
+        session: SqlSessionDep,  # type: ignore[name-defined]
+        tenant_id: TenantId,
+        payload: Any = Body(...),
+    ):
+        svc = await _svc(session, tenant_id)
+        if isinstance(payload, BaseModel):
+            data = payload.model_dump(exclude_unset=True)
+        elif isinstance(payload, dict):
+            data = payload
+        else:
+            raise HTTPException(422, "invalid_payload")
+        row = await svc.update(session, item_id, data)
+        if not row:
+            raise HTTPException(404, "Not found")
+        return row
+
+    @router.delete("/{item_id}", status_code=204)
+    async def delete_item(item_id: Any, session: SqlSessionDep, tenant_id: TenantId):  # type: ignore[name-defined]
+        svc = await _svc(session, tenant_id)
+        ok = await svc.delete(session, item_id)
+        if not ok:
+            raise HTTPException(404, "Not found")
+        return
+
+    return router
+
+
+__all__ = ["make_crud_router_plus_sql", "make_tenant_crud_router_plus_sql"]

svc_infra-0.1.602/src/svc_infra/api/fastapi/dependencies/ratelimit.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import time
+from typing import Callable, Optional
+
+from fastapi import HTTPException
+from starlette.requests import Request
+
+from svc_infra.api.fastapi.middleware.ratelimit_store import InMemoryRateLimitStore, RateLimitStore
+
+try:
+    from svc_infra.api.fastapi.tenancy.context import resolve_tenant_id as _resolve_tenant_id
+except Exception:  # pragma: no cover - minimal builds
+    _resolve_tenant_id = None  # type: ignore
+from svc_infra.obs.metrics import emit_rate_limited
+
+
+class RateLimiter:
+    def __init__(
+        self,
+        *,
+        limit: int,
+        window: int = 60,
+        key_fn: Callable = lambda r: "global",
+        limit_resolver: Optional[Callable[[Request, Optional[str]], Optional[int]]] = None,
+        scope_by_tenant: bool = False,
+        store: RateLimitStore | None = None,
+    ):
+        self.limit = limit
+        self.window = window
+        self.key_fn = key_fn
+        self._limit_resolver = limit_resolver
+        self.scope_by_tenant = scope_by_tenant
+        self.store = store or InMemoryRateLimitStore(limit=limit)
+
+    async def __call__(self, request: Request):
+        # Try resolving tenant when asked
+        tenant_id = None
+        if self.scope_by_tenant or self._limit_resolver:
+            try:
+                if _resolve_tenant_id is not None:
+                    tenant_id = await _resolve_tenant_id(request)
+            except Exception:
+                tenant_id = None
+
+        key = self.key_fn(request)
+        if self.scope_by_tenant and tenant_id:
+            key = f"{key}:tenant:{tenant_id}"
+
+        eff_limit = self.limit
+        if self._limit_resolver:
+            try:
+                v = self._limit_resolver(request, tenant_id)
+                eff_limit = int(v) if v is not None else self.limit
+            except Exception:
+                eff_limit = self.limit
+
+        count, store_limit, reset = self.store.incr(str(key), self.window)
+        if count > eff_limit:
+            retry = max(0, reset - int(time.time()))
+            try:
+                emit_rate_limited(str(key), eff_limit, retry)
+            except Exception:
+                pass
+            raise HTTPException(
+                status_code=429, detail="Rate limit exceeded", headers={"Retry-After": str(retry)}
+            )
+
+
+__all__ = ["RateLimiter"]
+
+
+def rate_limiter(
+    *,
+    limit: int,
+    window: int = 60,
+    key_fn: Callable = lambda r: "global",
+    limit_resolver: Optional[Callable[[Request, Optional[str]], Optional[int]]] = None,
+    scope_by_tenant: bool = False,
+    store: RateLimitStore | None = None,
+):
+    store_ = store or InMemoryRateLimitStore(limit=limit)
+
+    async def dep(request: Request):
+        tenant_id = None
+        if scope_by_tenant or limit_resolver:
+            try:
+                if _resolve_tenant_id is not None:
+                    tenant_id = await _resolve_tenant_id(request)
+            except Exception:
+                tenant_id = None
+
+        key = key_fn(request)
+        if scope_by_tenant and tenant_id:
+            key = f"{key}:tenant:{tenant_id}"
+
+        eff_limit = limit
+        if limit_resolver:
+            try:
+                v = limit_resolver(request, tenant_id)
+                eff_limit = int(v) if v is not None else limit
+            except Exception:
+                eff_limit = limit
+
+        count, _store_limit, reset = store_.incr(str(key), window)
+        if count > eff_limit:
+            retry = max(0, reset - int(time.time()))
+            try:
+                emit_rate_limited(str(key), eff_limit, retry)
+            except Exception:
+                pass
+            raise HTTPException(
+                status_code=429, detail="Rate limit exceeded", headers={"Retry-After": str(retry)}
+            )
+
+    return dep

svc_infra-0.1.602/src/svc_infra/api/fastapi/docs/add.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI
+
+
+def add_docs(
+    app: FastAPI,
+    *,
+    redoc_url: str = "/redoc",
+    swagger_url: str = "/docs",
+    openapi_url: str = "/openapi.json",
+    export_openapi_to: Optional[str] = None,
+) -> None:
+    """Enable docs endpoints and optionally export OpenAPI schema to disk on startup."""
+    # Configure FastAPI docs URLs
+    app.docs_url = swagger_url
+    app.redoc_url = redoc_url
+    app.openapi_url = openapi_url
+
+    if export_openapi_to:
+        export_path = Path(export_openapi_to)
+
+        @app.on_event("startup")
+        async def _export_spec() -> None:  # noqa: ANN202
+            spec = app.openapi()
+            export_path.parent.mkdir(parents=True, exist_ok=True)
+            export_path.write_text(json.dumps(spec, indent=2))
+
+
+def add_sdk_generation_stub(
+    app: FastAPI,
+    *,
+    on_generate: Optional[callable] = None,
+    openapi_path: str = "/openapi.json",
+) -> None:
+    """Hook to add an SDK generation stub.
+
+    Provide `on_generate()` to run generation (e.g., openapi-generator). This is a stub only; we
+    don't ship a hard dependency. If `on_generate` is provided, we expose `/_docs/generate-sdk`.
+    """
+    from svc_infra.api.fastapi.dual.public import public_router
+
+    if not on_generate:
+        return
+
+    router = public_router(prefix="/_docs", include_in_schema=False)
+
+    @router.post("/generate-sdk")
+    async def _generate() -> dict:  # noqa: ANN201
+        on_generate()
+        return {"status": "ok"}
+
+    app.include_router(router)
+
+
+__all__ = ["add_docs", "add_sdk_generation_stub"]

{svc_infra-0.1.600 → svc_infra-0.1.602}/src/svc_infra/api/fastapi/middleware/ratelimit.py

@@ -7,6 +7,12 @@ from svc_infra.obs.metrics import emit_rate_limited
 
 from .ratelimit_store import InMemoryRateLimitStore, RateLimitStore
 
+try:
+    # Optional import: tenancy may not be enabled in all apps
+    from svc_infra.api.fastapi.tenancy.context import resolve_tenant_id as _resolve_tenant_id
+except Exception:  # pragma: no cover - fallback for minimal builds
+    _resolve_tenant_id = None  # type: ignore
+
 
 class SimpleRateLimitMiddleware(BaseHTTPMiddleware):
     def __init__(
@@ -15,18 +21,52 @@ class SimpleRateLimitMiddleware(BaseHTTPMiddleware):
         limit: int = 120,
         window: int = 60,
         key_fn=None,
+        *,
+        # When provided, dynamically computes a limit for the current request (e.g. per-tenant quotas)
+        # Signature: (request: Request, tenant_id: Optional[str]) -> int | None
+        limit_resolver=None,
+        # If True, automatically scopes the bucket key by tenant id when available
+        scope_by_tenant: bool = False,
         store: RateLimitStore | None = None,
     ):
         super().__init__(app)
         self.limit, self.window = limit, window
         self.key_fn = key_fn or (lambda r: r.headers.get("X-API-Key") or r.client.host)
+        self._limit_resolver = limit_resolver
+        self.scope_by_tenant = scope_by_tenant
         self.store = store or InMemoryRateLimitStore(limit=limit)
 
     async def dispatch(self, request, call_next):
+        # Resolve tenant when possible
+        tenant_id = None
+        if self.scope_by_tenant or self._limit_resolver:
+            try:
+                if _resolve_tenant_id is not None:
+                    tenant_id = await _resolve_tenant_id(request)
+            except Exception:
+                tenant_id = None
+
         key = self.key_fn(request)
+        if self.scope_by_tenant and tenant_id:
+            key = f"{key}:tenant:{tenant_id}"
+
+        # Allow dynamic limit overrides
+        eff_limit = self.limit
+        if self._limit_resolver:
+            try:
+                v = self._limit_resolver(request, tenant_id)
+                eff_limit = int(v) if v is not None else self.limit
+            except Exception:
+                eff_limit = self.limit
+
         now = int(time.time())
         # Increment counter in store
-        count, limit, reset = self.store.incr(str(key), self.window)
+        # Update store limit if it differs; stores capture configured limit internally
+        # For in-memory store, we can temporarily adjust per-request by swapping a new store instance
+        # but to keep API simple, we reuse store and clamp by eff_limit below.
+        count, store_limit, reset = self.store.incr(str(key), self.window)
+        # Enforce the effective limit selected for this request
+        limit = eff_limit
         remaining = max(0, limit - count)
 
         if remaining < 0:  # defensive clamp

svc_infra-0.1.602/src/svc_infra/api/fastapi/ops/add.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+from typing import Callable
+
+from fastapi import FastAPI, HTTPException, Request
+from starlette.responses import JSONResponse
+
+
+def add_probes(
+    app: FastAPI,
+    *,
+    prefix: str = "/_ops",
+    include_in_schema: bool = False,
+) -> None:
+    """Mount basic liveness/readiness/startup probes under prefix."""
+    from svc_infra.api.fastapi.dual.public import public_router
+
+    router = public_router(prefix=prefix, tags=["ops"], include_in_schema=include_in_schema)
+
+    @router.get("/live")
+    async def live() -> JSONResponse:  # noqa: D401, ANN201
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/ready")
+    async def ready() -> JSONResponse:  # noqa: D401, ANN201
+        # In the future, add checks (DB ping, cache ping) via DI hooks.
+        return JSONResponse({"status": "ok"})
+
+    @router.get("/startup")
+    async def startup_probe() -> JSONResponse:  # noqa: D401, ANN201
+        return JSONResponse({"status": "ok"})
+
+    app.include_router(router)
+
+
+def add_maintenance_mode(app: FastAPI, *, env_var: str = "MAINTENANCE_MODE") -> None:
+    """Enable a simple maintenance gate controlled by an env var.
+
+    When MAINTENANCE_MODE is truthy, all non-GET requests return 503.
+    """
+
+    @app.middleware("http")
+    async def _maintenance_gate(request: Request, call_next):  # noqa: ANN001, ANN202
+        flag = str(os.getenv(env_var, "")).lower() in {"1", "true", "yes", "on"}
+        if flag and request.method not in {"GET", "HEAD", "OPTIONS"}:
+            return JSONResponse({"detail": "maintenance"}, status_code=503)
+        return await call_next(request)
+
+
+def circuit_breaker_dependency(limit: int = 100, window_seconds: int = 60) -> Callable:
+    """Return a dependency that can trip rejective errors based on external metrics.
+
+    This is a placeholder; callers can swap with a provider that tracks failures and opens the
+    breaker. Here, we read an env var to simulate an open breaker.
+    """
+
+    async def _dep(_: Request) -> None:  # noqa: D401, ANN202
+        if str(os.getenv("CIRCUIT_OPEN", "")).lower() in {"1", "true", "yes", "on"}:
+            raise HTTPException(status_code=503, detail="circuit open")
+
+    return _dep
+
+
+__all__ = ["add_probes", "add_maintenance_mode", "circuit_breaker_dependency"]