fastapi-m8 1.0.0__py3-none-any.whl

fastapi_m8/__init__.py

@@ -0,0 +1,64 @@
+"""
+fastapi-m8 — FastAPI application framework for m8 consumer microservices.
+
+Public surface (stable):
+
+Tier 1 — everyday service API::
+
+    from fastapi_m8 import create_app, build_auth_deps, AuthDeps
+    from fastapi_m8 import create_db_engine, DbEngine
+    from fastapi_m8 import ConsumerServiceSettings
+
+Tier 2 — health building blocks::
+
+    from fastapi_m8 import (
+        HealthStatus, HealthCheckResult, HealthCheck, HealthAggregatePolicy,
+    )
+
+Tier 3 — informational / future::
+
+    from fastapi_m8 import create_async_app, CAPABILITIES, capabilities
+    from fastapi_m8 import COMPAT_MATRIX, __version__
+"""
+
+# Tier 1
+from fastapi_m8._app import AppLifecycle, HealthConfig, create_app
+
+# Tier 3
+from fastapi_m8._async_stub import CAPABILITIES, capabilities, create_async_app
+from fastapi_m8._compat import COMPAT_MATRIX
+from fastapi_m8._deps import AuthDeps, build_auth_deps
+from fastapi_m8._engine import DbEngine, create_db_engine
+
+# Tier 2
+from fastapi_m8._health import (
+    HealthAggregatePolicy,
+    HealthCheck,
+    HealthCheckResult,
+    HealthStatus,
+)
+from fastapi_m8._version import __version__
+from fastapi_m8.config import ConsumerServiceSettings
+
+__all__ = [
+    "__version__",
+    # Tier 1
+    "create_app",
+    "HealthConfig",
+    "AppLifecycle",
+    "build_auth_deps",
+    "AuthDeps",
+    "create_db_engine",
+    "DbEngine",
+    "ConsumerServiceSettings",
+    # Tier 2
+    "HealthStatus",
+    "HealthCheckResult",
+    "HealthCheck",
+    "HealthAggregatePolicy",
+    # Tier 3
+    "create_async_app",
+    "CAPABILITIES",
+    "capabilities",
+    "COMPAT_MATRIX",
+]

fastapi_m8/_app.py

@@ -0,0 +1,344 @@
+"""
+App factory for fastapi-m8 consumer services.
+
+``create_app`` wires CORS, optional metrics middleware, the health endpoint,
+OpenAPI schema, and a managed lifespan (startup validators + graceful teardown).
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import secrets
+import time
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import anyio
+from fastapi import APIRouter, FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from fastapi_m8._compat import _COMPAT_STATE, _assert_compat
+from fastapi_m8._health import (
+    DEFAULT_TIMEOUT,
+    HealthAggregatePolicy,
+    HealthCheck,
+    HealthCheckResult,
+    HealthStatus,
+    aggregate,
+    run_check,
+)
+from fastapi_m8._version import __version__
+
+if TYPE_CHECKING:
+    from fastapi_m8._deps import AuthDeps
+    from fastapi_m8._engine import DbEngine
+    from fastapi_m8.config import ConsumerServiceSettings
+
+logger = logging.getLogger(__name__)
+
+StartupValidator = Callable[[], Awaitable[None]]
+
+_CORS_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+_CORS_HEADERS = ["Authorization", "Content-Type", "X-Requested-With"]
+
+
+@dataclass
+class HealthConfig:
+    """
+    Configuration for the health endpoint.
+
+    Attributes
+    ----------
+    checks
+        List of health-check callables returning HealthCheckResult.
+    timeout
+        Per-check timeout in seconds.
+    policy
+        LENIENT (default) or STRICT aggregate policy.
+    detail_public
+        If True, expose per-check detail to everyone.
+    detail_authorizer
+        Override the default X-Internal-Token gate.
+    cache_ttl
+        Seconds to cache health-check results.
+
+    """
+
+    checks: list[HealthCheck] | None = None
+    timeout: float = DEFAULT_TIMEOUT
+    policy: HealthAggregatePolicy = field(
+        default_factory=lambda: HealthAggregatePolicy.LENIENT
+    )
+    detail_public: bool = False
+    detail_authorizer: Callable[[Request], bool | Awaitable[bool]] | None = None
+    cache_ttl: float = 2.0
+
+
+@dataclass
+class AppLifecycle:
+    """
+    App lifecycle configuration.
+
+    Attributes
+    ----------
+    auth_deps
+        AuthDeps instance for token validation teardown.
+    db_engine
+        DbEngine instance to dispose on shutdown.
+    startup_validators
+        Async callables run before traffic; a raise aborts lifespan.
+    configure
+        Receives the fully-wired app for static additions.
+    lifespan_extras
+        Async context manager run inside the managed lifespan.
+
+    """
+
+    auth_deps: AuthDeps | None = None
+    db_engine: DbEngine | None = None
+    startup_validators: list[StartupValidator] | None = None
+    configure: Callable[[FastAPI], None] | None = None
+    lifespan_extras: Callable | None = None
+
+
+def _mark_ready(app: FastAPI) -> None:
+    app.state.service_ready = True
+    app.state.ready_since = time.monotonic()
+
+
+def _build_lifespan(
+    auth_deps: AuthDeps | None,
+    db_engine: DbEngine | None,
+    startup_validators: list[StartupValidator] | None,
+    lifespan_extras: Callable | None,
+) -> Callable:
+    """Return an asynccontextmanager lifespan for the app."""
+
+    async def _run_startup() -> None:
+        for v in startup_validators or []:
+            await v()
+
+    async def _teardown() -> None:
+        if auth_deps is not None:
+            await auth_deps.close()
+        if db_engine is not None:
+            db_engine.dispose()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:  # type: ignore[misc]
+        await _run_startup()
+        if lifespan_extras is not None:
+            async with lifespan_extras(app):
+                _mark_ready(app)
+                yield
+        else:
+            _mark_ready(app)
+            yield
+        await _teardown()
+
+    return lifespan
+
+
+def _add_metrics_middleware(app: FastAPI, settings: ConsumerServiceSettings) -> None:
+    if not settings.METRICS_ENABLED:
+        return
+    try:
+        from auth_sdk_m8.observability.middleware import (  # noqa: PLC0415
+            MetricsMiddleware,
+        )
+
+        app.add_middleware(MetricsMiddleware)
+    except ImportError:  # pragma: no cover — only fires without [observability] extra
+        logger.warning(
+            "METRICS_ENABLED but auth-sdk-m8[observability] missing; skipping"
+        )
+
+
+def _build_default_authorizer(
+    settings: ConsumerServiceSettings,
+) -> Callable[[Request], bool]:
+    """Return a token authorizer closed over the private API secret."""
+    sec = settings.PRIVATE_API_SECRET
+
+    def _authorizer(request: Request) -> bool:
+        if not sec:
+            return False
+        return secrets.compare_digest(
+            request.headers.get("X-Internal-Token", ""),
+            sec.get_secret_value(),
+        )
+
+    return _authorizer
+
+
+async def _gather_health_results(
+    app: FastAPI,
+    checks: list[HealthCheck],
+    timeout: float,
+    policy: HealthAggregatePolicy,
+    cache_ttl: float,
+) -> tuple[list[HealthCheckResult], HealthStatus, int]:
+    """Run all health checks with caching; return results, status, HTTP code."""
+    cache = app.state.health_cache
+    if cache and (time.monotonic() - cache[0]) < cache_ttl:
+        return cache[1], cache[2], cache[3]
+    results: list[HealthCheckResult] = [None] * len(checks)  # type: ignore[list-item]
+
+    async def _run_one(idx: int, check: HealthCheck) -> None:
+        results[idx] = await run_check(check, timeout=timeout)
+
+    async with anyio.create_task_group() as tg:
+        for i, c in enumerate(checks):
+            tg.start_soon(_run_one, i, c)
+    overall = aggregate(results, policy)
+    code = 503 if overall is HealthStatus.FAIL else 200
+    app.state.health_cache = (time.monotonic(), results, overall, code)
+    return results, overall, code
+
+
+def _build_health_body(
+    results: list[HealthCheckResult],
+    service_name: str | None,
+    service_version: str | None,
+) -> dict[str, Any]:
+    """Return the detailed health response body."""
+    return {
+        "checks": [r.model_dump() for r in results],
+        "service": service_name,
+        "version": service_version,
+        "fastapi_m8": __version__,
+        "auth_sdk_m8": _COMPAT_STATE.get("auth_version"),
+    }
+
+
+def _openapi_config(
+    settings: ConsumerServiceSettings,
+    service_name: str | None,
+    service_version: str | None,
+) -> dict[str, Any]:
+    """Build FastAPI constructor kwargs for title, version, and OpenAPI URLs."""
+    return {
+        "title": service_name or settings.PROJECT_NAME,
+        "version": service_version or "0.0.0",
+        "openapi_url": (
+            f"{settings.API_PREFIX}/openapi.json" if settings.SET_OPEN_API else None
+        ),
+        "docs_url": f"{settings.API_PREFIX}/docs" if settings.SET_DOCS else None,
+        "redoc_url": f"{settings.API_PREFIX}/redoc" if settings.SET_REDOC else None,
+        "generate_unique_id_function": lambda r: f"{r.tags[0]}-{r.name}",
+    }
+
+
+def _init_app_state(app: FastAPI) -> None:
+    app.state.service_ready = False
+    app.state.ready_since = None
+    app.state.health_cache = None
+
+
+def _add_cors_middleware(app: FastAPI, settings: ConsumerServiceSettings) -> None:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.ALLOWED_ORIGINS,
+        allow_credentials=True,
+        allow_methods=_CORS_METHODS,
+        allow_headers=_CORS_HEADERS,
+        max_age=3600,
+    )
+
+
+def _register_health_route(
+    app: FastAPI,
+    api_prefix: str,
+    checks: list[HealthCheck],
+    config: HealthConfig,
+    authorize: Callable[[Request], bool | Awaitable[bool]],
+    service_name: str | None,
+    service_version: str | None,
+) -> None:
+    """Register the /health/ endpoint on the app."""
+
+    async def _is_authorized(request: Request) -> bool:
+        res = authorize(request)
+        return await res if inspect.isawaitable(res) else bool(res)
+
+    @app.get(f"{api_prefix}/health/", include_in_schema=False, tags=["health"])
+    async def health(request: Request) -> JSONResponse:
+        if not request.app.state.service_ready:
+            return JSONResponse(
+                {"status": "initializing", "ready": False}, status_code=503
+            )
+        results, overall, code = await _gather_health_results(
+            app, checks, config.timeout, config.policy, config.cache_ttl
+        )
+        logger.debug("health: %s (%d checks)", overall.value, len(results))
+        body: dict[str, Any] = {"status": overall.value}
+        if config.detail_public or await _is_authorized(request):
+            body |= _build_health_body(results, service_name, service_version)
+        return JSONResponse(body, status_code=code)
+
+
+def create_app(
+    settings: ConsumerServiceSettings,
+    router: APIRouter,
+    *,
+    service_name: str | None = None,
+    service_version: str | None = None,
+    health: HealthConfig | None = None,
+    lifecycle: AppLifecycle | None = None,
+) -> FastAPI:
+    """
+    Wire and return a consumer FastAPI app.
+
+    Parameters
+    ----------
+    settings
+        Service settings (a ConsumerServiceSettings subclass).
+    router
+        The domain APIRouter to include.
+    service_name
+        Human-readable service name (falls back to settings.PROJECT_NAME).
+    service_version
+        Semantic version string for this service.
+    health
+        Health endpoint config; defaults to HealthConfig().
+    lifecycle
+        Lifecycle config (auth, engine, validators); defaults to AppLifecycle().
+
+    Returns
+    -------
+    FastAPI
+        A fully configured instance.
+
+    """
+    _assert_compat()
+    h = health or HealthConfig()
+    lc = lifecycle or AppLifecycle()
+    checks = list(h.checks or [])
+    app = FastAPI(
+        lifespan=_build_lifespan(
+            lc.auth_deps, lc.db_engine, lc.startup_validators, lc.lifespan_extras
+        ),
+        **_openapi_config(settings, service_name, service_version),
+    )
+    _init_app_state(app)
+    _add_cors_middleware(app, settings)
+    _add_metrics_middleware(app, settings)
+    authorize = h.detail_authorizer or _build_default_authorizer(settings)
+    _register_health_route(
+        app, settings.API_PREFIX, checks, h, authorize, service_name, service_version
+    )
+    app.include_router(router)
+    logger.info(
+        "fastapi-m8 %s svc=%s v=%s sdk=%s",
+        __version__,
+        service_name,
+        service_version,
+        _COMPAT_STATE.get("auth_version"),
+    )
+    if lc.configure is not None:
+        lc.configure(app)
+    return app

fastapi_m8/_async_stub.py

@@ -0,0 +1,40 @@
+"""Async app stub — reserves the async interface for fastapi-m8 v2.0.0."""
+
+from __future__ import annotations
+
+from typing import Any
+
+CAPABILITIES: dict[str, bool] = {
+    "async": False,
+    "plugin_system": False,
+    "trace_context": False,
+    "db_optional": True,
+    "health_detail_gating": True,
+}
+
+
+def capabilities() -> dict[str, bool]:
+    """
+    Return a copy of the capability flags.
+
+    Use this to introspect what the installed version supports before
+    calling optional APIs.
+    """
+    return CAPABILITIES.copy()
+
+
+def create_async_app(*args: Any, **kwargs: Any) -> Any:
+    """
+    Placeholder — async app support is planned for fastapi-m8 v2.0.0.
+
+    Raises
+    ------
+    NotImplementedError
+        Always. Check ``capabilities()['async']`` first.
+
+    """
+    raise NotImplementedError(
+        "Async app support is planned for fastapi-m8 v2.0.0. "
+        "Check CAPABILITIES['async']. "
+        "Track: github.com/EliSerra/fa-auth-m8/issues/1"
+    )

fastapi_m8/_compat.py

@@ -0,0 +1,60 @@
+"""
+Runtime compatibility guard between fastapi-m8 and auth-sdk-m8.
+
+``_assert_compat()`` is called from ``create_app()`` and ``build_auth_deps()``
+once per process (thread-safe via ``_lock``).
+"""
+
+import importlib.metadata as md
+import logging
+import threading
+
+from packaging.specifiers import SpecifierSet
+
+from fastapi_m8._version import __version__
+
+logger = logging.getLogger(__name__)
+
+# Declarative pairing: fastapi-m8 minor → required version ranges.
+# Add future dependencies here without touching any other code.
+COMPAT_MATRIX: dict[str, dict[str, str]] = {
+    "1.0": {"auth-sdk-m8": ">=0.7.0,<0.8.0"},
+}
+
+_EXTRAS = "[config,security,fastapi,observability]"
+_lock = threading.Lock()
+_COMPAT_STATE: dict[str, object] = {"checked": False, "auth_version": None}
+
+
+def _assert_compat() -> None:
+    """
+    Check installed dependency versions against COMPAT_MATRIX.
+
+    Raises
+    ------
+    RuntimeError
+        If a required dependency is outside its specified range.
+
+    """
+    with _lock:
+        if _COMPAT_STATE["checked"]:
+            return
+        minor = ".".join(__version__.split(".")[:2])
+        reqs = COMPAT_MATRIX.get(minor, {})
+        for dist, spec in reqs.items():
+            found = md.version(dist)
+            if found not in SpecifierSet(spec):
+                logger.error(
+                    "fastapi-m8 %s needs %s%s (found %s)",
+                    __version__,
+                    dist,
+                    spec,
+                    found,
+                )
+                raise RuntimeError(
+                    f"fastapi-m8 {__version__} requires {dist}{spec} "
+                    f"(found {found}). "
+                    f"Run: pip install '{dist}{_EXTRAS}{spec}'"
+                )
+        auth_v = md.version("auth-sdk-m8")
+        _COMPAT_STATE.update(checked=True, auth_version=auth_v)

fastapi_m8/_deps.py

@@ -0,0 +1,186 @@
+"""
+Auth dependency builder for fastapi-m8 services.
+
+Call ``build_auth_deps(settings)`` **once** per service in ``core/deps.py``
+and share the resulting ``AuthDeps`` instance everywhere.  A second call
+builds a second validator and revocation client — there is no implicit cache.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Annotated, Any
+
+from auth_sdk_m8.core.exceptions import InvalidToken
+from auth_sdk_m8.schemas.base import RoleType
+from auth_sdk_m8.schemas.user import UserModel
+from auth_sdk_m8.security import ValidationHooks, build_access_validator
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+
+from fastapi_m8._compat import _assert_compat
+from fastapi_m8._revocation import RemoteRevocationClient, RevocationCheckError
+
+if TYPE_CHECKING:
+    from fastapi_m8.config import ConsumerServiceSettings
+
+_logger = logging.getLogger(__name__)
+
+_FORBIDDEN = status.HTTP_403_FORBIDDEN
+_UNAVAILABLE = status.HTTP_503_SERVICE_UNAVAILABLE
+_NO_PRIVILEGES = "The user doesn't have enough privileges"
+
+
+def _validate_access_token(validator: Any, token: str) -> Any:
+    try:
+        return validator.validate_access_token(token)
+    except InvalidToken as ex:
+        raise HTTPException(
+            status_code=_FORBIDDEN,
+            detail="Could not validate credentials.",
+        ) from ex
+
+
+async def _check_token_revocation(
+    revocation_client: RemoteRevocationClient | None, jti: str
+) -> None:
+    if revocation_client is None:
+        return
+    try:
+        if await revocation_client.is_revoked(jti):
+            raise HTTPException(
+                status_code=_FORBIDDEN,
+                detail="Token has been revoked.",
+            )
+    except RevocationCheckError as ex:
+        raise HTTPException(
+            status_code=_UNAVAILABLE,
+            detail="Token revocation check unavailable.",
+        ) from ex
+
+
+def _build_active_user(payload: Any) -> UserModel:
+    payload_dict = payload.model_dump(exclude={"exp", "jti", "type", "sub"})
+    payload_dict["id"] = payload.sub
+    user = UserModel(**payload_dict)
+    if not user.is_active:
+        raise HTTPException(status_code=_FORBIDDEN, detail="Inactive user")
+    return user
+
+
+def _require_role(current_user: UserModel, role_limit: RoleType) -> None:
+    if not RoleType.is_valid_role_auth(
+        current_role=current_user.role,
+        role_limit=role_limit,
+    ):
+        raise HTTPException(status_code=_FORBIDDEN, detail=_NO_PRIVILEGES)
+
+
+class _LoggingHooks:
+    """Emit structured log lines for every token validation outcome."""
+
+    def on_success(self, *, jti: str, sub: str, token_type: str) -> None:
+        _logger.debug("auth.ok type=%s sub=%s jti=%s", token_type, sub, jti)
+
+    def on_failure(self, *, reason: str, token_type: str) -> None:
+        _logger.warning("auth.fail type=%s reason=%s", token_type, reason)
+
+
+@dataclass(frozen=True)
+class AuthDeps:
+    """
+    Frozen container for all auth-related FastAPI dependencies.
+
+    Attributes
+    ----------
+    get_current_user
+        Dependency function — returns the authenticated user.
+    CurrentUser
+        ``Annotated[UserModel, Depends(get_current_user)]``.
+    get_current_active_admin
+        Dependency that additionally checks ADMIN role.
+    get_current_active_superuser
+        Checks SUPERADMIN role.
+    revocation_client
+        The revocation client, or None for stateless mode.
+
+    """
+
+    get_current_user: Callable
+    CurrentUser: Any
+    get_current_active_admin: Callable
+    get_current_active_superuser: Callable
+    revocation_client: RemoteRevocationClient | None
+
+    async def close(self) -> None:
+        """Teardown owner: close the revocation client (and future clients)."""
+        if self.revocation_client is not None:
+            await self.revocation_client.close()
+
+
+def build_auth_deps(settings: ConsumerServiceSettings) -> AuthDeps:
+    """
+    Build the auth dependency set from service settings.
+
+    Call once at module load in ``core/deps.py``.  A second call creates a
+    second validator and revocation client without sharing state.
+
+    Parameters
+    ----------
+    settings
+        A ``ConsumerServiceSettings`` instance.
+
+    Returns
+    -------
+    AuthDeps
+        Frozen dataclass with all auth dependencies.
+
+    """
+    _assert_compat()
+
+    hooks: ValidationHooks = _LoggingHooks()  # type: ignore[assignment]
+    validator = build_access_validator(settings, hooks)
+
+    revocation_client: RemoteRevocationClient | None = None
+    if settings.is_stateful and settings.AUTH_SERVICE_ROLE == "consumer":
+        revocation_client = RemoteRevocationClient(
+            introspection_url=str(settings.INTROSPECTION_URL),
+            private_api_secret=settings.PRIVATE_API_SECRET.get_secret_value(),  # type: ignore[union-attr]
+        )
+
+    reusable_oauth2 = OAuth2PasswordBearer(
+        tokenUrl=f"{settings.AUTH_PREFIX}/login/access-token"
+    )
+    TokenDep = Annotated[str, Depends(reusable_oauth2)]
+
+    async def get_current_user(token: TokenDep) -> UserModel:
+        """Extract and validate the current user from the JWT access token."""
+        payload = _validate_access_token(validator, token)
+        await _check_token_revocation(revocation_client, payload.jti)
+        return _build_active_user(payload)
+
+    CurrentUser = Annotated[UserModel, Depends(get_current_user)]
+
+    def get_current_active_admin(current_user: CurrentUser) -> UserModel:  # type: ignore[valid-type]
+        """Verify at least ADMIN role."""
+        _require_role(current_user, RoleType.ADMIN)
+        return current_user
+
+    def get_current_active_superuser(
+        current_user: CurrentUser,  # type: ignore[valid-type]
+    ) -> UserModel:
+        """Verify SUPERADMIN role."""
+        if not current_user.is_superuser:
+            raise HTTPException(status_code=_FORBIDDEN, detail=_NO_PRIVILEGES)
+        _require_role(current_user, RoleType.SUPERADMIN)
+        return current_user
+
+    return AuthDeps(
+        get_current_user=get_current_user,
+        CurrentUser=CurrentUser,
+        get_current_active_admin=get_current_active_admin,
+        get_current_active_superuser=get_current_active_superuser,
+        revocation_client=revocation_client,
+    )