standard-fastapi 0.2.0__tar.gz

standard_fastapi-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Workspace-managed mounts.
+/.agents/
+/.aws/
+/.codex/
+
+# Python tooling and generated files.
+/.venv/
+/venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+/build/
+/dist/
+/.coverage
+/.coverage.*
+/htmlcov/
+/deprecated/
+/.pytest_cache/
+/.mypy_cache/
+/.ruff_cache/
+/.tox/
+
+# Documentation output.
+/.cache/
+/site/
+
+# Local secrets and environment files.
+.env
+.env.*
+!.env.example
+.kata.local.toml

standard_fastapi-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Standard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

standard_fastapi-0.2.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: standard-fastapi
+Version: 0.2.0
+Summary: FastAPI integration for the Standard Python library
+Project-URL: Documentation, https://appunni-m.github.io/python-standard/api/
+Project-URL: Repository, https://github.com/appunni-m/python-standard
+Author: Standard contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,pydantic-settings,standard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: standard==0.2.0
+Description-Content-Type: text/markdown
+
+# standard-fastapi
+
+FastAPI integration for the [`standard`](https://pypi.org/project/standard/)
+Python library. After publication, install it directly with
+`python -m pip install standard-fastapi` or use the `standard[fastapi]` extra.
+
+Define the application's settings model in `core/settings.py`:
+
+```python
+from std.config import YamlSettings
+
+
+class Settings(YamlSettings):
+    std_config_file = "settings.yaml"
+    service_name: str
+```
+
+In `main.py`, create the app and inject that settings instance once:
+
+```python
+from fastapi import Depends, FastAPI
+from app.core.settings import Settings
+from std.fastapi import settings_dependency
+
+
+def create_app() -> FastAPI:
+    settings = Settings()  # Create once in the application composition root.
+    app = FastAPI()
+    app.state.settings = settings
+    settings_dep = settings_dependency(Settings)
+
+    @app.get("/health")
+    async def health(settings: Settings = Depends(settings_dep)) -> dict[str, str]:
+        return {"service": settings.service_name}
+
+    return app
+```
+
+Create `Settings()` once in `main.py` and assign the instance to
+`app.state.settings`. The dependency returns that injected instance and never
+constructs or reloads settings.
+
+The integration includes `APIConfig` and `FastAPISetup` for app construction,
+`LifecycleManager` for injected background services, `AppTokenAuth` and
+`TokenAuthMiddleware`, health-check endpoints, request logging middleware, and
+the Pydantic Settings dependency helper. Core service lifecycle types remain
+available as `std.service` from `standard`.
+
+The core library and this package are versioned independently. The `std`
+command and core modules remain in the `standard` distribution. See the
+[API reference](https://appunni-m.github.io/python-standard/api/) for public
+signatures, behavior, and examples.

standard_fastapi-0.2.0/README.md

@@ -0,0 +1,52 @@
+# standard-fastapi
+
+FastAPI integration for the [`standard`](https://pypi.org/project/standard/)
+Python library. After publication, install it directly with
+`python -m pip install standard-fastapi` or use the `standard[fastapi]` extra.
+
+Define the application's settings model in `core/settings.py`:
+
+```python
+from std.config import YamlSettings
+
+
+class Settings(YamlSettings):
+    std_config_file = "settings.yaml"
+    service_name: str
+```
+
+In `main.py`, create the app and inject that settings instance once:
+
+```python
+from fastapi import Depends, FastAPI
+from app.core.settings import Settings
+from std.fastapi import settings_dependency
+
+
+def create_app() -> FastAPI:
+    settings = Settings()  # Create once in the application composition root.
+    app = FastAPI()
+    app.state.settings = settings
+    settings_dep = settings_dependency(Settings)
+
+    @app.get("/health")
+    async def health(settings: Settings = Depends(settings_dep)) -> dict[str, str]:
+        return {"service": settings.service_name}
+
+    return app
+```
+
+Create `Settings()` once in `main.py` and assign the instance to
+`app.state.settings`. The dependency returns that injected instance and never
+constructs or reloads settings.
+
+The integration includes `APIConfig` and `FastAPISetup` for app construction,
+`LifecycleManager` for injected background services, `AppTokenAuth` and
+`TokenAuthMiddleware`, health-check endpoints, request logging middleware, and
+the Pydantic Settings dependency helper. Core service lifecycle types remain
+available as `std.service` from `standard`.
+
+The core library and this package are versioned independently. The `std`
+command and core modules remain in the `standard` distribution. See the
+[API reference](https://appunni-m.github.io/python-standard/api/) for public
+signatures, behavior, and examples.

standard_fastapi-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.27,<2", "hatch-vcs>=0.4,<1"]
+build-backend = "hatchling.build"
+
+[project]
+name = "standard-fastapi"
+dynamic = ["version"]
+description = "FastAPI integration for the Standard Python library"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Standard contributors" }]
+keywords = ["fastapi", "pydantic-settings", "standard"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["standard==0.2.0", "fastapi>=0.115,<1"]
+urls = { Documentation = "https://appunni-m.github.io/python-standard/api/", Repository = "https://github.com/appunni-m/python-standard" }
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/std/fastapi"]
+sources = ["src"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["pyproject.toml", "README.md", "LICENSE", "src/std/fastapi"]
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = "^v(?P<version>\\d+\\.\\d+\\.\\d+(?:(?:a|b|rc)\\d+)?)$"
+
+[tool.hatch.version.raw-options]
+search_parent_directories = true

standard_fastapi-0.2.0/src/std/fastapi/__init__.py

@@ -0,0 +1,50 @@
+"""FastAPI application, authentication, health, lifecycle, and logging tools."""
+
+try:
+    import fastapi as _fastapi  # noqa: F401
+except ImportError as error:  # pragma: no cover - broken optional installation
+    raise ImportError(
+        "FastAPI integration requires the FastAPI dependency; install "
+        "`standard-fastapi` or `standard[fastapi]`. From a checkout run "
+        "`python -m pip install -e . -e packages/standard-fastapi`."
+    ) from error
+
+from std.fastapi.api import APIConfig, APIService, Environment, FastAPISetup, LifecycleManager
+from std.fastapi.auth import (
+    AppTokenAuth,
+    AppTokenConfig,
+    TokenAuthMiddleware,
+    add_api_key_security_scheme,
+    apply_token_auth_middleware,
+    setup_app_token_auth,
+    setup_token_auth,
+)
+from std.fastapi.dependencies import settings_dependency
+from std.fastapi.health import (
+    HealthCheck,
+    HealthCheckFunc,
+    HealthResponse,
+    create_health_endpoint,
+)
+from std.fastapi.logging import LoggingMiddleware
+
+__all__ = [
+    "APIConfig",
+    "APIService",
+    "AppTokenAuth",
+    "AppTokenConfig",
+    "Environment",
+    "FastAPISetup",
+    "HealthCheck",
+    "HealthCheckFunc",
+    "HealthResponse",
+    "LifecycleManager",
+    "LoggingMiddleware",
+    "TokenAuthMiddleware",
+    "add_api_key_security_scheme",
+    "apply_token_auth_middleware",
+    "create_health_endpoint",
+    "settings_dependency",
+    "setup_app_token_auth",
+    "setup_token_auth",
+]

standard_fastapi-0.2.0/src/std/fastapi/api/__init__.py

@@ -0,0 +1,8 @@
+"""FastAPI application configuration and lifecycle support."""
+
+from std.fastapi.api.config import APIConfig, Environment
+from std.fastapi.api.lifecycle import LifecycleManager
+from std.fastapi.api.service import APIService
+from std.fastapi.api.setup import FastAPISetup
+
+__all__ = ["APIConfig", "APIService", "Environment", "FastAPISetup", "LifecycleManager"]

standard_fastapi-0.2.0/src/std/fastapi/api/config.py

@@ -0,0 +1,58 @@
+"""Validated server and application metadata for FastAPI."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class Environment(StrEnum):
+    """Deployment environments supported by the FastAPI setup helper."""
+
+    DEV = "dev"
+    STAGE = "stage"
+    PROD = "prod"
+
+    def __str__(self) -> str:
+        """Return the configuration value."""
+        return self.value
+
+
+class APIConfig(BaseModel):
+    """Application metadata, server options, and CORS policy."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    enabled: bool = Field(default=True, description="Whether the API is enabled")
+    env: Environment = Field(default=Environment.DEV, description="Deployment environment")
+    title: str = Field(default="Standard API", min_length=1)
+    description: str = Field(default="API service")
+    version: str = Field(default="1.0.0", min_length=1)
+    host: str = Field(default="0.0.0.0", min_length=1)
+    port: int = Field(default=8000, ge=1, le=65535)
+    reload: bool = True
+    workers: int = Field(default=1, ge=1)
+    debug: bool = True
+    cors_origins: list[str] = Field(default_factory=lambda: ["*"])
+    cors_methods: list[str] = Field(default_factory=lambda: ["*"])
+    cors_headers: list[str] = Field(default_factory=lambda: ["*"])
+    cors_credentials: bool = True
+
+    @field_validator("host")
+    @classmethod
+    def validate_host(cls, value: str) -> str:
+        """Reject whitespace-only bind hosts."""
+        host = value.strip()
+        if not host:
+            raise ValueError("host cannot be empty")
+        return host
+
+    @field_validator("cors_origins", "cors_methods", "cors_headers")
+    @classmethod
+    def validate_cors_values(cls, values: list[str]) -> list[str]:
+        """Reject empty CORS entries and normalize surrounding whitespace."""
+        normalized = [value.strip() for value in values]
+        if any(not value for value in normalized):
+            raise ValueError("CORS entries cannot be empty")
+        return normalized

standard_fastapi-0.2.0/src/std/fastapi/api/lifecycle.py

@@ -0,0 +1,175 @@
+"""Coordinate injected background services with an ASGI application lifespan."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+
+from fastapi import FastAPI
+from std.service import BackgroundServiceProtocol, ServiceState
+
+logger = logging.getLogger(__name__)
+SetupHandler = Callable[[], Awaitable[Sequence[BackgroundServiceProtocol]]]
+
+
+class LifecycleManager:
+    """Start services in order and stop them in reverse order.
+
+    A service's stop hook is invoked even when its startup fails, allowing it
+    to release resources acquired before the failure. Shutdown attempts every
+    cleanup hook and groups errors after all services have been visited.
+    """
+
+    def __init__(
+        self,
+        services: Sequence[BackgroundServiceProtocol] = (),
+        *,
+        setup_handler: SetupHandler | None = None,
+    ) -> None:
+        """Create a manager for supplied services and an optional async factory."""
+        self._services = list(services)
+        if len({id(service) for service in self._services}) != len(self._services):
+            raise ValueError("the same service instance cannot be registered twice")
+        self._setup_handler = setup_handler
+        self._active_services: list[BackgroundServiceProtocol] = []
+        self._state = ServiceState.IDLE
+        self._lock = asyncio.Lock()
+
+    @property
+    def status(self) -> ServiceState:
+        """Return the lifecycle manager's current state."""
+        return self._state
+
+    def add_service(self, service: BackgroundServiceProtocol) -> None:
+        """Register a service before startup."""
+        if self._state in (ServiceState.STARTING, ServiceState.RUNNING, ServiceState.STOPPING):
+            raise RuntimeError("services cannot be added while the lifecycle manager is active")
+        if any(existing is service for existing in self._services):
+            raise ValueError("the same service instance cannot be registered twice")
+        self._services.append(service)
+
+    def set_setup_handler(
+        self,
+        handler: SetupHandler,
+    ) -> None:
+        """Set an async factory for services created at application startup."""
+        if self._state in (ServiceState.STARTING, ServiceState.RUNNING, ServiceState.STOPPING):
+            raise RuntimeError("the setup handler cannot change while the manager is active")
+        self._setup_handler = handler
+
+    async def start(self) -> None:
+        """Start registered and dynamically created services in order."""
+        async with self._lock:
+            if self._state is ServiceState.RUNNING:
+                return
+            if self._state in (ServiceState.STARTING, ServiceState.STOPPING):
+                raise RuntimeError(f"cannot start lifecycle manager in state {self._state}")
+
+            self._state = ServiceState.STARTING
+            started: list[BackgroundServiceProtocol] = []
+            cleanup_failures: list[BackgroundServiceProtocol] = []
+            try:
+                dynamic = await self._setup_handler() if self._setup_handler else ()
+                services = [*self._services, *dynamic]
+                if len({id(service) for service in services}) != len(services):
+                    raise ValueError("the same service instance cannot be started twice")
+
+                for service in services:
+                    try:
+                        await service.start()
+                    except BaseException as startup_error:
+                        cleanup_failures = await self._cleanup_after_start_failure(
+                            service, started, startup_error
+                        )
+                        raise
+                    started.append(service)
+            except BaseException:
+                self._active_services = list(reversed(cleanup_failures))
+                self._state = ServiceState.FAILED
+                raise
+
+            self._active_services = started
+            self._state = ServiceState.RUNNING
+            logger.info("Started %d background services", len(started))
+
+    async def stop(self) -> None:
+        """Stop every active service in reverse order, attempting all cleanups."""
+        async with self._lock:
+            if self._state in (ServiceState.IDLE, ServiceState.STOPPED):
+                return
+            if self._state is ServiceState.STOPPING:
+                return
+
+            self._state = ServiceState.STOPPING
+            errors: list[Exception] = []
+            failed_services: list[BackgroundServiceProtocol] = []
+            try:
+                for service in reversed(self._active_services):
+                    try:
+                        await service.stop()
+                    except Exception as error:
+                        errors.append(error)
+                        failed_services.append(service)
+                        logger.exception("Failed to stop background service")
+            except BaseException:
+                self._state = ServiceState.FAILED
+                raise
+
+            self._active_services = list(reversed(failed_services))
+            if errors:
+                self._state = ServiceState.FAILED
+                raise ExceptionGroup("one or more services failed to stop", errors)
+            self._state = ServiceState.STOPPED
+            logger.info("Stopped all background services")
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Run the managed services for the duration of an async context."""
+        await self.start()
+        try:
+            yield
+        finally:
+            await self.stop()
+
+    def fastapi_lifespan(
+        self,
+        setup_handler: SetupHandler | None = None,
+    ) -> Callable[[FastAPI], AbstractAsyncContextManager[None]]:
+        """Return an ASGI lifespan callable for :class:`FastAPI`."""
+        if setup_handler is not None:
+            self.set_setup_handler(setup_handler)
+
+        @asynccontextmanager
+        async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+            async with self.lifespan():
+                yield
+
+        return lifespan
+
+    async def _cleanup_after_start_failure(
+        self,
+        failed_service: BackgroundServiceProtocol,
+        started_services: list[BackgroundServiceProtocol],
+        startup_error: BaseException,
+    ) -> list[BackgroundServiceProtocol]:
+        """Clean the failing service and every earlier service in reverse order."""
+        cleanup_failures: list[BackgroundServiceProtocol] = []
+        for service in (failed_service, *reversed(started_services)):
+            try:
+                await service.stop()
+            except BaseException as cleanup_error:
+                cleanup_failures.append(service)
+                startup_error.add_note(
+                    f"cleanup failed for {type(service).__name__}: {type(cleanup_error).__name__}"
+                )
+                logger.error(
+                    "Cleanup failed for a background service after startup failure",
+                    exc_info=(
+                        type(cleanup_error),
+                        cleanup_error,
+                        cleanup_error.__traceback__,
+                    ),
+                )
+        return cleanup_failures

standard_fastapi-0.2.0/src/std/fastapi/api/service.py

@@ -0,0 +1,21 @@
+"""Base class that registers a service's routes on an injected application."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from fastapi import FastAPI
+
+
+class APIService(ABC):
+    """Attach one route group to an existing FastAPI application."""
+
+    def __init__(self, app: FastAPI, name: str | None = None) -> None:
+        """Store the app and register routes implemented by the subclass."""
+        self.app = app
+        self.name = name or type(self).__name__
+        self._setup_routes()
+
+    @abstractmethod
+    def _setup_routes(self) -> None:
+        """Register this service's routes on :attr:`app`."""

standard_fastapi-0.2.0/src/std/fastapi/api/setup.py

@@ -0,0 +1,55 @@
+"""Compose a FastAPI application from explicit configuration and services."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from std.fastapi.api.config import APIConfig, Environment
+from std.fastapi.api.lifecycle import LifecycleManager
+from std.logging import LoggingConfig, configure_logging
+from std.service import BackgroundServiceProtocol
+
+
+class FastAPISetup:
+    """Build a FastAPI app with metadata, CORS, logging, and service lifespan."""
+
+    def __init__(
+        self,
+        api_config: APIConfig,
+        log_config: LoggingConfig | Mapping[str, object] | None = None,
+        setup_handler: Callable[[], Awaitable[Sequence[BackgroundServiceProtocol]]] | None = None,
+        *,
+        services: Sequence[BackgroundServiceProtocol] = (),
+    ) -> None:
+        """Store application settings and constructed background services."""
+        self.api_config = api_config
+        self.log_config = log_config
+        self.lifecycle_manager = LifecycleManager(services, setup_handler=setup_handler)
+
+    def create_fastapi_app(self) -> FastAPI:
+        """Create a configured FastAPI instance with injected service lifespan."""
+        if self.log_config is not None:
+            environment = {
+                Environment.DEV: "development",
+                Environment.STAGE: "staging",
+                Environment.PROD: "production",
+            }[self.api_config.env]
+            configure_logging(self.log_config, environment=environment)
+
+        app = FastAPI(
+            title=self.api_config.title,
+            description=self.api_config.description,
+            version=self.api_config.version,
+            debug=self.api_config.debug,
+            lifespan=self.lifecycle_manager.fastapi_lifespan(),
+        )
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=self.api_config.cors_origins,
+            allow_credentials=self.api_config.cors_credentials,
+            allow_methods=self.api_config.cors_methods,
+            allow_headers=self.api_config.cors_headers,
+        )
+        return app

standard_fastapi-0.2.0/src/std/fastapi/auth/__init__.py

@@ -0,0 +1,21 @@
+"""Header token authentication for FastAPI dependencies and middleware."""
+
+from std.fastapi.auth.config import AppTokenConfig
+from std.fastapi.auth.middleware import (
+    AppTokenAuth,
+    TokenAuthMiddleware,
+    add_api_key_security_scheme,
+    apply_token_auth_middleware,
+    setup_app_token_auth,
+    setup_token_auth,
+)
+
+__all__ = [
+    "AppTokenAuth",
+    "AppTokenConfig",
+    "TokenAuthMiddleware",
+    "add_api_key_security_scheme",
+    "apply_token_auth_middleware",
+    "setup_app_token_auth",
+    "setup_token_auth",
+]

standard_fastapi-0.2.0/src/std/fastapi/auth/config.py

@@ -0,0 +1,53 @@
+"""Validated settings for application-token authentication."""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+_HEADER_NAME = re.compile(r"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$")
+
+
+class AppTokenConfig(BaseModel):
+    """Configure the token header, accepted application tokens, and path skips."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    header_name: str = "X-App-Token"
+    tokens: dict[str, str] = Field(default_factory=dict, repr=False)
+    enabled: bool = True
+    exclude_paths: set[str] = Field(default_factory=set)
+
+    @field_validator("header_name")
+    @classmethod
+    def validate_header_name(cls, value: str) -> str:
+        """Require a valid HTTP token header name."""
+        name = value.strip()
+        if not _HEADER_NAME.fullmatch(name):
+            raise ValueError("header_name must be a valid HTTP field name")
+        return name
+
+    @field_validator("tokens")
+    @classmethod
+    def validate_tokens(cls, tokens: dict[str, str]) -> dict[str, str]:
+        """Reject blank identities and tokens without disclosing token values."""
+        seen: set[str] = set()
+        for app_name, token in tokens.items():
+            if not app_name.strip():
+                raise ValueError("token application names cannot be empty")
+            if not token.strip():
+                raise ValueError(f"token for application {app_name!r} cannot be empty")
+            if token in seen:
+                raise ValueError("authentication tokens must be unique")
+            seen.add(token)
+        return tokens
+
+    @field_validator("exclude_paths")
+    @classmethod
+    def validate_exclude_paths(cls, paths: set[str]) -> set[str]:
+        """Require absolute request paths for exact and wildcard exclusions."""
+        normalized = {path.strip() for path in paths}
+        if any(not path.startswith("/") for path in normalized):
+            raise ValueError("excluded paths must begin with '/'")
+        return normalized

standard_fastapi-0.2.0/src/std/fastapi/auth/middleware.py

@@ -0,0 +1,165 @@
+"""API-token dependency, middleware, and OpenAPI security helpers."""
+
+import hmac
+from collections.abc import Awaitable, Callable
+from fnmatch import fnmatchcase
+from typing import Any
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.types import ASGIApp
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import JSONResponse
+from std.fastapi.auth.config import AppTokenConfig
+
+MissingTokenHandler = Callable[[Request], Awaitable[Response]]
+InvalidTokenHandler = Callable[[Request, str], Awaitable[Response]]
+
+
+class AppTokenAuth:
+    """Authenticate requests from one configured header and return the app ID."""
+
+    def __init__(self, settings: AppTokenConfig | None = None) -> None:
+        """Use the supplied configuration or the secure default configuration."""
+        self.settings = settings or AppTokenConfig()
+
+    async def __call__(self, request: Request) -> str | None:
+        """Return the matching app name or raise a 401 for a protected path."""
+        if not self.settings.enabled or self.is_path_excluded(request.url.path):
+            return None
+        token = request.headers.get(self.settings.header_name)
+        if token is None:
+            raise HTTPException(status_code=401, detail="Missing authentication token")
+        app_name = self.get_app_name(token)
+        if app_name is None:
+            raise HTTPException(status_code=401, detail="Invalid authentication token")
+        return app_name
+
+    def is_path_excluded(self, path: str) -> bool:
+        """Return whether a path matches an exact or shell-style exclusion."""
+        return any(fnmatchcase(path, pattern) for pattern in self.settings.exclude_paths)
+
+    def get_app_name(self, token: str) -> str | None:
+        """Return the identity associated with a token using constant-time checks."""
+        supplied = token.encode("utf-8")
+        matched_app: str | None = None
+        for app_name, accepted in self.settings.tokens.items():
+            if hmac.compare_digest(supplied, accepted.encode("utf-8")):
+                matched_app = app_name
+        return matched_app
+
+
+class TokenAuthMiddleware(BaseHTTPMiddleware):
+    """Require a configured API token for every non-excluded request."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        settings: AppTokenConfig | None = None,
+        on_missing_token: MissingTokenHandler | None = None,
+        on_invalid_token: InvalidTokenHandler | None = None,
+    ) -> None:
+        """Store authentication settings and optional async response handlers."""
+        super().__init__(app)
+        self.auth = AppTokenAuth(settings)
+        self.on_missing_token = on_missing_token
+        self.on_invalid_token = on_invalid_token
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        """Validate credentials, set request identity, then continue the request."""
+        settings = self.auth.settings
+        if not settings.enabled or self.auth.is_path_excluded(request.url.path):
+            return await call_next(request)
+
+        token = request.headers.get(settings.header_name)
+        if token is None:
+            if self.on_missing_token is not None:
+                return await self.on_missing_token(request)
+            return JSONResponse({"error": "Missing authentication token"}, status_code=401)
+
+        app_name = self.auth.get_app_name(token)
+        if app_name is None:
+            if self.on_invalid_token is not None:
+                return await self.on_invalid_token(request, token)
+            return JSONResponse({"error": "Invalid authentication token"}, status_code=401)
+
+        request.state.app_name = app_name
+        return await call_next(request)
+
+
+def add_api_key_security_scheme(
+    app: FastAPI,
+    header_name: str,
+    enabled: bool = True,
+) -> None:
+    """Add an API-key scheme and global security requirement to generated OpenAPI."""
+    if not enabled:
+        return
+
+    original_openapi = app.openapi
+
+    def openapi_with_api_key() -> dict[str, Any]:
+        schema = original_openapi()
+        components = schema.get("components")
+        if not isinstance(components, dict):
+            components = {}
+            schema["components"] = components
+        schemes = components.setdefault("securitySchemes", {})
+        schemes["APIKeyHeader"] = {"type": "apiKey", "in": "header", "name": header_name}
+        requirement: dict[str, list[str]] = {"APIKeyHeader": []}
+        security = schema.get("security")
+        if not isinstance(security, list):
+            security = []
+            schema["security"] = security
+        if requirement not in security:
+            security.append(requirement)
+        app.openapi_schema = schema
+        return schema
+
+    # FastAPI has no setter for this override; direct assignment fails strict mypy.
+    setattr(app, "openapi", openapi_with_api_key)  # noqa: B010
+    if app.openapi_schema is not None:
+        openapi_with_api_key()
+
+
+def setup_token_auth(
+    app: FastAPI,
+    settings: AppTokenConfig | None = None,
+) -> AppTokenAuth:
+    """Register the OpenAPI security scheme and return a dependency handler."""
+    config = settings or AppTokenConfig()
+    add_api_key_security_scheme(app, config.header_name, config.enabled)
+    return AppTokenAuth(config)
+
+
+def apply_token_auth_middleware(
+    app: FastAPI,
+    settings: AppTokenConfig | None = None,
+    on_missing_token: MissingTokenHandler | None = None,
+    on_invalid_token: InvalidTokenHandler | None = None,
+) -> None:
+    """Install token authentication middleware and document its header scheme."""
+    config = settings or AppTokenConfig()
+    add_api_key_security_scheme(app, config.header_name, config.enabled)
+    app.add_middleware(
+        TokenAuthMiddleware,
+        settings=config,
+        on_missing_token=on_missing_token,
+        on_invalid_token=on_invalid_token,
+    )
+
+
+setup_app_token_auth = setup_token_auth
+
+__all__ = [
+    "AppTokenAuth",
+    "TokenAuthMiddleware",
+    "add_api_key_security_scheme",
+    "apply_token_auth_middleware",
+    "setup_app_token_auth",
+    "setup_token_auth",
+]

standard_fastapi-0.2.0/src/std/fastapi/dependencies.py

@@ -0,0 +1,37 @@
+"""FastAPI dependencies that construct validated Pydantic Settings models."""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from pydantic_settings import BaseSettings
+
+from fastapi import HTTPException, Request
+from fastapi.params import Depends as DependsType
+
+SettingsT = TypeVar("SettingsT", bound=BaseSettings)
+
+
+def settings_dependency(settings_type: type[SettingsT]) -> DependsType:
+    """Return a dependency that retrieves main-initialized app settings.
+
+    Construct the model once in the application composition root and assign it
+    to ``app.state.settings`` before serving requests. The dependency verifies
+    its type and returns that same instance; it never constructs settings.
+    """
+    if not isinstance(settings_type, type) or not issubclass(settings_type, BaseSettings):
+        raise TypeError("settings_type must be a BaseSettings subclass")
+
+    async def get_settings(request: Request) -> SettingsT:
+        settings = getattr(request.app.state, "settings", None)
+        if not isinstance(settings, settings_type):
+            raise HTTPException(
+                status_code=500,
+                detail="Application settings were not initialized in the composition root",
+            )
+        return settings
+
+    return DependsType(get_settings)
+
+
+__all__ = ["settings_dependency"]

standard_fastapi-0.2.0/src/std/fastapi/health/__init__.py

@@ -0,0 +1,6 @@
+"""Health response models and endpoint registration."""
+
+from std.fastapi.health.endpoint import HealthCheck, HealthCheckFunc, HealthResponse
+from std.fastapi.health.endpoint import create_health_endpoint as create_health_endpoint
+
+__all__ = ["HealthCheck", "HealthCheckFunc", "HealthResponse", "create_health_endpoint"]

standard_fastapi-0.2.0/src/std/fastapi/health/endpoint.py

@@ -0,0 +1,122 @@
+"""Register a health endpoint backed by synchronous or asynchronous checks."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any, cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+HealthCheckFunc = Callable[[], Any | Awaitable[Any]]
+
+
+class HealthResponse(BaseModel):
+    """JSON response containing the overall state and individual check values."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: str = "healthy"
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class HealthCheck:
+    """Collect named checks and expose their aggregate result as an endpoint."""
+
+    def __init__(self, app: FastAPI | None = None, path: str = "/health") -> None:
+        """Create a health endpoint, optionally registering it on an app."""
+        if not path.startswith("/"):
+            raise ValueError("health endpoint path must begin with '/'")
+        self.path = path
+        self._checks: list[tuple[str, HealthCheckFunc]] = []
+        self._registered_apps: set[int] = set()
+        if app is not None:
+            self.add_to_app(app)
+
+    @property
+    def checks(self) -> tuple[tuple[str, HealthCheckFunc], ...]:
+        """Return the registered checks in execution order."""
+        return tuple(self._checks)
+
+    def add_check(self, name: str, check_func: HealthCheckFunc) -> None:
+        """Register a named synchronous or asynchronous health check."""
+        normalized_name = name.strip()
+        if not normalized_name:
+            raise ValueError("health check name cannot be empty")
+        if not callable(check_func):
+            raise TypeError("check_func must be callable")
+        if any(existing == normalized_name for existing, _ in self._checks):
+            raise ValueError(f"health check {normalized_name!r} is already registered")
+        self._checks.append((normalized_name, check_func))
+
+    def add_to_app(self, app: FastAPI, include_in_schema: bool = False) -> None:
+        """Register the health route on an app once."""
+        app_identity = id(app)
+        if app_identity in self._registered_apps:
+            raise ValueError("health endpoint is already registered on this app")
+        self._registered_apps.add(app_identity)
+
+        @app.get(
+            self.path,
+            response_model=HealthResponse,
+            include_in_schema=include_in_schema,
+            tags=["health"],
+        )
+        async def health_check() -> HealthResponse:
+            details: dict[str, Any] = {}
+            healthy = True
+            for name, check_func in self._checks:
+                try:
+                    result = await self._execute(check_func)
+                except Exception as error:
+                    logger.warning("Health check %s failed (%s)", name, type(error).__name__)
+                    result = {"status": "error", "error": type(error).__name__}
+                details[name] = result
+                if self._is_unhealthy(result):
+                    healthy = False
+            return HealthResponse(status="healthy" if healthy else "unhealthy", details=details)
+
+    async def _execute(self, check_func: HealthCheckFunc) -> Any:
+        if inspect.iscoroutinefunction(check_func):
+            result = check_func()
+        else:
+            sync_check = cast(Callable[[], Any], check_func)
+            result = await asyncio.get_running_loop().run_in_executor(None, sync_check)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    @staticmethod
+    def _is_unhealthy(result: Any) -> bool:
+        if result is False:
+            return True
+        if isinstance(result, Mapping):
+            status = result.get("status")
+            return isinstance(status, str) and status.casefold() in {
+                "error",
+                "unhealthy",
+                "down",
+            }
+        return False
+
+
+def create_health_endpoint(
+    app: FastAPI,
+    path: str = "/health",
+    include_in_schema: bool = False,
+    checks: list[tuple[str, HealthCheckFunc]] | None = None,
+) -> HealthCheck:
+    """Create a health manager, register initial checks, and attach its route."""
+    health = HealthCheck(path=path)
+    for name, check_func in checks or []:
+        health.add_check(name, check_func)
+    health.add_to_app(app, include_in_schema=include_in_schema)
+    return health
+
+
+__all__ = ["HealthCheck", "HealthCheckFunc", "HealthResponse", "create_health_endpoint"]

standard_fastapi-0.2.0/src/std/fastapi/logging/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP request logging middleware."""
+
+from std.fastapi.logging.middleware import LoggingMiddleware
+
+__all__ = ["LoggingMiddleware"]

standard_fastapi-0.2.0/src/std/fastapi/logging/middleware.py

@@ -0,0 +1,70 @@
+"""Log HTTP request, response, and timing fields without reading request bodies."""
+
+from __future__ import annotations
+
+import logging
+from time import perf_counter
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.types import ASGIApp
+
+from fastapi import Request, Response
+
+logger = logging.getLogger(__name__)
+
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """Log method, path, status, elapsed time, and optional client address."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        include_client: bool = True,
+        process_time_header: str = "X-Process-Time",
+    ) -> None:
+        """Configure client logging and the response timing header."""
+        super().__init__(app)
+        self.include_client = include_client
+        self.process_time_header = process_time_header
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        """Process a request, log its outcome, and add an elapsed-time header."""
+        start = perf_counter()
+        client = request.client.host if self.include_client and request.client else None
+        fields: dict[str, object] = {
+            "http.method": request.method,
+            "http.path": request.url.path,
+        }
+        if client is not None:
+            fields["client.address"] = client
+        logger.info("HTTP request started", extra=fields)
+
+        try:
+            response = await call_next(request)
+        except Exception:
+            duration_ms = (perf_counter() - start) * 1000
+            logger.exception(
+                "HTTP request failed",
+                extra={**fields, "http.duration_ms": round(duration_ms, 3)},
+            )
+            raise
+
+        duration_ms = (perf_counter() - start) * 1000
+        response.headers[self.process_time_header] = f"{duration_ms:.1f}ms"
+        logger.info(
+            "HTTP response finished",
+            extra={
+                **fields,
+                "http.status_code": response.status_code,
+                "http.duration_ms": round(duration_ms, 3),
+            },
+        )
+        return response
+
+
+__all__ = ["LoggingMiddleware"]