fastapi-runner 0.0.0__py3-none-any.whl

fastapi_runner/__init__.py

@@ -0,0 +1,4 @@
+from importlib import metadata
+
+version = metadata.version('fastapi-runner')
+del metadata

fastapi_runner/entrypoint.py

@@ -0,0 +1,192 @@
+import contextlib
+import typing as t
+from collections import abc
+from importlib import metadata
+
+import fastapi.exceptions
+import fastapi.middleware.cors
+import pydantic
+import pydantic_settings
+
+from fastapi_runner import error_handling, errors, lifespan, middleware, types
+
+
+class ApplicationSettings(pydantic_settings.BaseSettings):
+    model_config = {'env_prefix': 'FASTAPI_RUNNER_'}
+    application: str
+    access_log: bool = True
+
+
+class CORSSettings(pydantic_settings.BaseSettings):
+    model_config = {'env_prefix': 'FASTAPI_RUNNER_CORS_'}
+    allow_credentials: bool = False
+    allow_headers: list[str] = []
+    allow_methods: list[str] = [
+        'DELETE',
+        'GET',
+        'HEAD',
+        'OPTIONS',
+        'POST',
+        'PUT',
+    ]
+    allow_origins: list[str] = []
+    allow_private_network: bool = False
+    enabled: bool = True
+    expose_headers: list[str] = []
+    max_age: int = 600
+
+
+ConfigHook = abc.Callable[[fastapi.FastAPI], None]
+LifespanGenerator = abc.Callable[[], abc.Generator[lifespan.LifespanHook]]
+
+
+def app_factory() -> fastapi.FastAPI:
+    """Configurable application factory.
+
+    Use this function with `uvicorn` as a factory to create an
+    application instance based on the `APPLICATION` environment
+    variable. It identifies the python distribution to import.
+    The distribution configures `fastapi_runner` entry points
+    named `configure` and (optionally) `lifespans` that match
+    the `ConfigHook` and `LifespanGenerator` types.
+    """
+    settings = _get_application_settings()
+    try:
+        distribution = metadata.distribution(settings.application)
+    except metadata.PackageNotFoundError:
+        raise errors.ApplicationConfigurationError(
+            f'APPLICATION={settings.application!r} does not identify an '
+            'installed Python distribution'
+        ) from None
+
+    configure, lifespan_generator = _load_hooks(distribution)
+
+    return create_app(
+        configure=configure,
+        lifespan_generator=lifespan_generator,
+        enable_access_log=settings.access_log,
+    )
+
+
+def create_app(
+    *,
+    configure: ConfigHook | None = None,
+    lifespan_generator: LifespanGenerator | None = None,
+    enable_access_log: bool = True,
+) -> fastapi.FastAPI:
+    """Create a FastAPI application instance using hooks
+
+    This method creates an application instance using the supplied
+    hooks. In addition to setting up a composable lifespan, the
+    CORS and access logging middlewares are installed and several
+    error handlers are configured.
+
+    Args:
+        configure: A hook that configures the application.
+        lifespan_generator: A generator that yields lifespan hooks.
+        enable_access_log: Enable the access logging middleware?
+
+    Returns:
+        A FastAPI application instance.
+    """
+
+    span = lifespan.Lifespan()
+    if lifespan_generator is not None:
+        for hook in lifespan_generator():
+            span.add_lifespan(hook)
+
+    app = fastapi.FastAPI(lifespan=span, telemetry={'auto_configure': False})
+
+    cors_settings = CORSSettings()
+    if cors_settings.enabled:
+        app.add_middleware(
+            fastapi.middleware.cors.CORSMiddleware,
+            allow_credentials=cors_settings.allow_credentials,
+            allow_headers=cors_settings.allow_headers,
+            allow_methods=cors_settings.allow_methods,
+            allow_origins=cors_settings.allow_origins,
+            allow_private_network=cors_settings.allow_private_network,
+            expose_headers=cors_settings.expose_headers,
+            max_age=cors_settings.max_age,
+        )
+
+    # Overrideable to customize error document creation.
+    state = t.cast('types.AppStateShape', app.state)
+    state.fastapi_runner_error_updater = None
+
+    # Add custom error handlers for specific exception
+    # types BEFORE invoking the application level configure
+    # so that the app can replace, override, whatever.
+    app.add_exception_handler(
+        fastapi.exceptions.RequestValidationError,
+        error_handling.validation_error_handler,
+    )
+
+    # Let the application configure its routes
+    if configure is not None:
+        configure(app)
+
+    # Add the problem details translator last to ensure that
+    # unexpected exceptions are translated.
+    app.add_exception_handler(
+        fastapi.exceptions.HTTPException,
+        error_handling.problem_details_translator,
+    )
+
+    # The AccessLogMiddleware should ALWAYS be added last
+    if enable_access_log:
+        app.add_middleware(
+            middleware.AccessLogMiddleware,
+            ignored_paths=('/docs', '/openapi.json', '/redoc'),
+        )
+
+    return app
+
+
+def _get_application_settings() -> ApplicationSettings:
+    """Retrieve the application settings or fail with a useful message."""
+    try:
+        return ApplicationSettings()
+    except pydantic.ValidationError as error:
+        prefix = ApplicationSettings.model_config['env_prefix']
+        missing = set[str]()
+        invalid = set[str]()
+        for e in error.errors():
+            if e['type'] == 'missing':
+                missing.add(str(e['loc'][0]))
+            else:
+                invalid.add(str(e['loc'][0]))
+        if missing:
+            names = ' '.join(f'{prefix}{name.upper()}' for name in missing)
+            raise errors.ApplicationConfigurationError(
+                f'Missing required environment variables: {names}'
+            ) from None
+        if invalid:
+            names = ' '.join(f'{prefix}{name.upper()}' for name in invalid)
+            raise errors.ApplicationConfigurationError(
+                f'Invalid environment variables: {names}'
+            ) from None
+        raise errors.ApplicationConfigurationError(
+            'Unknown error loading application settings'
+        ) from None  # pragma: no cover -- paranoia
+
+
+def _load_hooks(
+    distribution: metadata.Distribution,
+) -> tuple[ConfigHook, LifespanGenerator | None]:
+    entry_points = distribution.entry_points.select(group='fastapi_runner')
+    num_eps = len(entry_points.select(name='configure'))
+    if num_eps != 1:
+        raise ValueError(
+            f'Expected exactly one configure entrypoint in fastapi_runner'
+            f' group, but found {num_eps} in {distribution.name!r}'
+        )
+
+    configure = t.cast('ConfigHook', entry_points['configure'].load())
+    lifespan_generator: LifespanGenerator | None = None
+    with contextlib.suppress(KeyError):
+        lifespan_generator = t.cast(
+            'LifespanGenerator', entry_points['lifespans'].load()
+        )
+
+    return configure, lifespan_generator

fastapi_runner/error_handling.py

@@ -0,0 +1,141 @@
+import collections
+import functools
+import inspect
+import typing as t
+from collections import abc
+
+import fastapi.exceptions
+
+from fastapi_runner import errors, types
+
+
+class ValidationErrorShape(t.TypedDict, total=False):
+    """The shape of `fastapi.exceptions.ValidationError.errors()`"""
+
+    type: t.Required[str]
+    loc: t.Required[abc.Sequence[str]]
+    msg: t.Required[str]
+
+
+def _ensure_declared_exception_type[T: Exception, R](
+    exc: Exception, handler: abc.Callable[[fastapi.Request, T], R]
+) -> t.TypeGuard[T]:
+    """Type guard that ensures the exc type matches the handler.
+
+    This is used in `typesafe_error_handler` to adapt the exception
+    parameter in the FastAPI error handler to the precise type.
+    """
+    params = tuple(inspect.signature(handler).parameters)
+    exception_param = params[1]
+    expected = t.get_type_hints(handler)[exception_param]
+    return (
+        isinstance(expected, type)
+        and issubclass(expected, Exception)
+        and isinstance(exc, expected)
+    )
+
+
+def typesafe_error_handler[T: Exception, RT](
+    handler: abc.Callable[[fastapi.Request, T], RT],
+) -> abc.Callable[[fastapi.Request, Exception], RT]:
+    """Adapt a type-safe error handler to a generic error hook.
+
+    FastAPI uses a generic `Exception` in exception handlers
+    even though the precise type is specified in the
+    `add_exception_handler` call. This decorator exposes the
+    more generic parameter type while ensuring that the precise
+    type is checked at runtime before calling the handler.
+
+    Args:
+        handler: The error handler function to adapt.
+
+    Returns:
+        A wrapper function that accepts an `Exception` and
+        type narrows *before* calling `handler`.
+
+    """
+
+    @functools.wraps(handler)
+    def wrapper(request: fastapi.Request, exc: Exception) -> RT:
+        if _ensure_declared_exception_type(exc, handler):
+            return handler(request, exc)
+        raise TypeError(f'Expected {T.__name__}, got {exc.__class__.__name__}')
+
+    return wrapper
+
+
+@typesafe_error_handler
+def problem_details_translator(
+    request: fastapi.Request, exc: fastapi.exceptions.HTTPException
+) -> fastapi.Response:
+    """Translate HTTP exceptions to Problem Details bodies.
+
+    The response shape matches `types.ProblemDetailBody` with the
+    default status and title coming from `exc` properties.
+    Applications should define the `fastapi_runner_error_updater`
+    attribute on the state as a callable that updates the error
+    body to match application expectations.
+
+    """
+    error_body: types.ProblemDetailBody
+    if isinstance(exc, errors.ProblemDetailError):
+        error_body = exc.body
+    else:
+        error_body = types.ProblemDetailBody.model_validate(
+            {
+                'status': exc.status_code,
+                'title': exc.detail,
+            }
+        )
+
+    app_state = t.cast('types.AppStateShape', request.app.state)
+    if app_state.fastapi_runner_error_updater is not None:
+        app_state.fastapi_runner_error_updater(request, exc, error_body)
+
+    return fastapi.Response(
+        media_type='application/problem+json',
+        status_code=exc.status_code,
+        content=error_body.model_dump_json(),
+    )
+
+
+@typesafe_error_handler
+def validation_error_handler(
+    request: fastapi.Request, exc: fastapi.exceptions.ValidationException
+) -> fastapi.Response:
+    """Customize validation error handling.
+
+    Maps validation errors to the `errors` response body field.
+    It is a mapping from the error type to a list of error locations
+    where the type can be any string. The standard values are
+    defined by the `pydantic_core.ErrorType` literal type. However,
+    a `pydantic_core.PydanticCustomError` exception can be raised
+    to set the error type to an arbitrary string.
+
+    The application error update hook can be used to further
+    customize the error response body.
+
+    """
+    error_body = types.ValidationErrorBody.model_validate(
+        {
+            'status': 422,
+            'title': 'Validation Error',
+            'errors': {},
+        }
+    )
+
+    errors: dict[str, list[str]] = collections.defaultdict(list[str])
+    err: ValidationErrorShape
+    for err in exc.errors():
+        errors[err['type']].append('.'.join(err['loc']))
+    error_body.errors.update(errors)
+
+    app_state = t.cast('types.AppStateShape', request.app.state)
+    if app_state.fastapi_runner_error_updater is not None:
+        app_state.fastapi_runner_error_updater(request, exc, error_body)
+
+    return fastapi.Response(
+        media_type='application/problem+json',
+        status_code=error_body.status,
+        content=error_body.model_dump_json(),
+    )

fastapi_runner/errors.py

@@ -0,0 +1,27 @@
+import fastapi
+
+from fastapi_runner import types
+
+
+class ApplicationConfigurationError(RuntimeError):
+    pass
+
+
+class ProblemDetailError(fastapi.HTTPException):
+    def __init__(
+        self,
+        status_code: int,
+        *,
+        title: str,
+        type: str,  # noqa: A002 -- using type to ensure it is not in `body`
+        **body: object,
+    ) -> None:
+        super().__init__(status_code=status_code, detail=title)
+        self.body = types.ProblemDetailBody.model_validate(
+            {
+                'type': type,
+                'title': title,
+                'status': status_code,
+                **body,
+            }
+        )

fastapi_runner/lifespan.py

@@ -0,0 +1,125 @@
+import contextlib
+import http
+import inspect
+import logging
+import types
+import typing as t
+from collections import abc
+
+import fastapi
+
+ConfigHook = abc.Callable[[fastapi.FastAPI], None]
+LifespanState = dict[str, object]
+
+
+class _CMReturning[T](t.Protocol):
+    async def __aenter__(self) -> T: ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        exc_traceback: types.TracebackType | None,
+        /,
+    ) -> bool | None: ...
+
+
+type LifespanHook = (
+    abc.Callable[[fastapi.FastAPI], _CMReturning[object | None]]
+    | abc.Callable[[], _CMReturning[object | None]]
+)
+type TypedLifespanHook[T] = (
+    abc.Callable[[fastapi.FastAPI], _CMReturning[T]]
+    | abc.Callable[[], _CMReturning[T]]
+)
+
+
+class Lifespan(dict[LifespanHook, object | None]):
+    def __init__(self) -> None:
+        super().__init__()
+        self._called = False
+        self._lifespans: list[LifespanHook] = []
+
+    def add_lifespan(self, hook: LifespanHook) -> None:
+        if self._called:
+            raise RuntimeError(
+                'Cannot add lifespan after __call__ has been invoked'
+            )
+        self._lifespans.append(hook)
+
+    def get_state[T](self, hook: TypedLifespanHook[T]) -> T:
+        try:
+            return t.cast('T', self[hook])
+        except KeyError:
+            raise fastapi.HTTPException(
+                status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR,
+                detail=f'Unmet lifespan dependency: {hook!r}',
+            ) from None
+
+    def __call__(
+        self, app: fastapi.FastAPI
+    ) -> contextlib.AbstractAsyncContextManager[LifespanState]:
+        self._called = True
+
+        @contextlib.asynccontextmanager
+        async def cm() -> abc.AsyncGenerator[dict[str, object]]:
+            async with contextlib.AsyncExitStack() as stack:
+                for hook in self._lifespans:
+                    if hook not in self:
+                        self[hook] = await stack.enter_async_context(
+                            _invoke_hook(hook, app)
+                        )
+                yield {'lifespan_data': self}
+
+        return cm()
+
+
+def _get_lifespan(request: fastapi.Request) -> Lifespan:
+    try:
+        lifespan = request.state.lifespan_data
+    except (AttributeError, ValueError):
+        logger = logging.getLogger(__package__).getChild('_get_lifespan')
+        logger.exception('Lifespan is not available in %r', set(request.state))
+        raise fastapi.HTTPException(
+            status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR,
+            detail='Lifespan not available',
+        ) from None
+
+    if not isinstance(lifespan, Lifespan):
+        raise fastapi.HTTPException(
+            status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR,
+            detail=f'Unexpected lifespan type: {type(lifespan)}',
+        )
+
+    return lifespan
+
+
+type LifespanMap = t.Annotated[Lifespan, fastapi.Depends(_get_lifespan)]
+
+
+class _HookWithoutApp[T](t.Protocol):
+    def __call__(self) -> _CMReturning[T]: ...
+
+
+class _HookWithApp[T](t.Protocol):
+    def __call__(self, app: fastapi.FastAPI, /) -> _CMReturning[T]: ...
+
+
+def _invoke_hook[T](
+    hook: _HookWithoutApp[T] | _HookWithApp[T],
+    app: fastapi.FastAPI,
+) -> _CMReturning[T]:
+    params = tuple(
+        inspect.signature(
+            hook,
+            eval_str=False,
+        ).parameters.values()
+    )
+    if not params:
+        return t.cast('_HookWithoutApp[T]', hook)()
+    if len(params) == 1 and params[0].kind in (
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+    ):
+        return t.cast('_HookWithApp[T]', hook)(app)
+    raise TypeError(f'Invalid lifespan hook signature: {hook!r}')

fastapi_runner/middleware.py

@@ -0,0 +1,153 @@
+import contextlib
+import inspect
+import logging
+import time
+import typing as t
+from collections import abc
+
+import starlette.types
+
+_DISABLE_ACCESS_LOG_ATTR = '_fastapi_runner_disable_access_log'
+
+
+type _Handler[**P, R] = abc.Callable[P, R]
+
+
+def disable_access_log[**P, R](handler: _Handler[P, R]) -> _Handler[P, R]:
+    setattr(handler, _DISABLE_ACCESS_LOG_ATTR, True)
+    return handler
+
+
+class _LogData(t.TypedDict):
+    status_code: int | str
+    bytes_sent: int
+    user_agent: str
+    client: str
+    method: str
+    path: str
+    http_version: str
+    duration: t.NotRequired[str]
+
+
+class _AccessLogState:
+    def __init__(self, scope: starlette.types.Scope) -> None:
+        self.start_time = time.monotonic_ns()
+        self.access_log_disabled = (
+            _is_access_log_disabled(scope) if 'endpoint' in scope else False
+        )
+        self._resolved_access_log_disabled = 'endpoint' in scope
+        self.data: _LogData = {
+            'status_code': '-',
+            'bytes_sent': 0,
+            'user_agent': '-',
+            'client': '-',
+            'method': scope['method'],
+            'path': scope['path'],
+            'http_version': scope['http_version'],
+        }
+        if client := scope.get('client', None):
+            host: str = client[0]
+            port: int = client[1]
+            if ':' in host:
+                host = f'[{host}]'
+
+            self.data['client'] = f'{host}:{port}'
+
+        if headers := scope.get('headers', None):
+            for name, value in headers:
+                if name.lower() == b'user-agent':
+                    self.data['user_agent'] = value.decode()
+
+    @property
+    def status_code(self) -> int | str:
+        return self.data['status_code']
+
+    def set_status_code(self, status: int) -> None:
+        self.data['status_code'] = status
+
+    def increment_bytes_sent(self, value: int) -> None:
+        self.data['bytes_sent'] += value
+
+    def finish(self, scope: starlette.types.Scope) -> None:
+        time_ms = (time.monotonic_ns() - self.start_time) * 1e-6
+        self.data['duration'] = f'{time_ms:.3f} ms'
+        if not self._resolved_access_log_disabled:
+            self.access_log_disabled = _is_access_log_disabled(scope)
+            self._resolved_access_log_disabled = True
+
+
+class AccessLogMiddleware:
+    def __init__(
+        self,
+        app: starlette.types.ASGIApp,
+        *,
+        ignored_paths: abc.Collection[str] = (),
+    ) -> None:
+        self.app = app
+        self.ignored_paths = frozenset(ignored_paths)
+
+    async def __call__(
+        self,
+        scope: starlette.types.Scope,
+        receive: starlette.types.Receive,
+        send: starlette.types.Send,
+    ) -> None:
+        if scope['type'] != 'http' or scope['path'] in self.ignored_paths:
+            await self.app(scope, receive, send)
+            return
+
+        async with _message_logger(scope) as state:
+
+            async def _send(message: starlette.types.Message) -> None:
+                if message['type'] == 'http.response.start':
+                    state.set_status_code(message['status'])
+                elif message['type'] == 'http.response.body':
+                    state.increment_bytes_sent(len(message.get('body', b'')))
+                await send(message)
+
+            await self.app(scope, receive, _send)
+
+
+def _is_access_log_disabled(scope: starlette.types.Scope) -> bool:
+    endpoint = scope.get('endpoint', None)
+    if endpoint is None:
+        return False
+
+    candidates = [endpoint]
+    with contextlib.suppress(AttributeError):
+        candidates.append(endpoint.__func__)
+
+    for candidate in candidates:
+        if getattr(candidate, _DISABLE_ACCESS_LOG_ATTR, False):
+            return True
+        if getattr(inspect.unwrap(candidate), _DISABLE_ACCESS_LOG_ATTR, False):
+            return True
+
+    return False
+
+
+@contextlib.asynccontextmanager
+async def _message_logger(
+    scope: starlette.types.Scope,
+) -> abc.AsyncGenerator[_AccessLogState]:
+    state = _AccessLogState(scope)
+    try:
+        yield state
+    finally:
+        state.finish(scope)
+        if not state.access_log_disabled:
+            match state.status_code:
+                case int():
+                    if state.status_code >= 500:  # noqa: PLR2004
+                        log_level = logging.ERROR
+                    elif state.status_code >= 400:  # noqa: PLR2004
+                        log_level = logging.WARNING
+                    else:
+                        log_level = logging.INFO
+                case str():
+                    log_level = logging.ERROR
+                case _:
+                    t.assert_never(state.status_code)
+
+            logger = logging.getLogger('api-runner.access')
+            logger.log(log_level, '', extra=state.data)

fastapi_runner/types.py

@@ -0,0 +1,26 @@
+import typing as t
+from collections import abc
+
+import fastapi
+import pydantic
+
+
+class ProblemDetailBody(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra='allow')
+    type: str = 'about:blank'
+    title: str
+    status: int
+    detail: t.Annotated[
+        str | None, pydantic.Field(exclude_if=lambda x: x is None)
+    ] = None
+
+
+class ValidationErrorBody(ProblemDetailBody):
+    errors: dict[str, list[str]] = {}
+
+
+class AppStateShape(t.Protocol):
+    fastapi_runner_error_updater: (
+        abc.Callable[[fastapi.Request, Exception, ProblemDetailBody], None]
+        | None
+    )

fastapi_runner-0.0.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: fastapi-runner
+Version: 0.0.0
+Summary: Production-ready uvicorn runner for FastAPI applications
+Author-email: Dave Shawley <daveshawley@gmail.com>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi~=0.143.0
+Requires-Dist: pydantic-settings~=2.14
+Requires-Dist: pydantic~=2.13
+Description-Content-Type: text/markdown
+
+# fastapi-runner
+
+`fastapi-runner` provides shared FastAPI application setup and a Uvicorn
+application factory. It keeps cross-cutting behavior in a reusable library
+while the application package owns its routes and application-specific
+lifecycle hooks.
+
+This package is a member of the repository's uv workspace, but it is otherwise
+freestanding: its package metadata, source tree, tests, and README are all
+under this directory. It can be built as its own source distribution and wheel
+for a future PyPI release.
+
+## Application discovery
+
+`app_factory()` selects an installed application using the `FASTAPI_RUNNER_APPLICATION`
+environment variable. The value is a Python distribution name, not a module
+path. That distribution must define exactly one `configure` entry point in the
+`fastapi_runner` group and may define a `lifespans` entry point.
+
+For example, an application package can declare:
+
+```toml
+[project.entry-points.fastapi_runner]
+configure = "my_app.app:configure"
+lifespans = "my_app.app:lifespans"
+```
+
+The hooks are called as follows:
+
+- `configure(app)` registers routes and other application-specific behavior.
+- `lifespans()` yields async context-manager hooks for startup and shutdown.
+- Each lifespan hook may accept no arguments or the `FastAPI` application.
+
+Run the generic factory with Uvicorn:
+
+```console
+FASTAPI_RUNNER_APPLICATION=my-app uvicorn \
+  --factory fastapi_runner.entrypoint:app_factory
+```
+
+The distribution named by `FASTAPI_RUNNER_APPLICATION` and `fastapi-runner` must both be
+installed in the environment.
+
+## Creating an application directly
+
+Applications and tests that do not need distribution-based discovery can use
+`create_app()` directly:
+
+```python
+from collections import abc
+
+import fastapi
+import fastapi_runner.entrypoint
+import fastapi_runner.lifespan
+
+
+def configure(app: fastapi.FastAPI) -> None:
+    """Add application-specific behavior."""
+
+
+def lifespans() -> abc.Generator[fastapi_runner.lifespan.LifespanHook]:
+    """Yield the application lifespan hooks."""
+
+
+app = fastapi_runner.entrypoint.create_app(
+    configure=configure,
+    lifespan_generator=lifespans,
+)
+```
+
+Both entry points install the same shared application behavior:
+
+- CORS middleware configured through the `FASTAPI_RUNNER_CORS_` environment prefix;
+- problem-detail responses for HTTP and validation errors;
+- an application state hook for customizing problem-detail bodies;
+- access logging, with the documentation routes excluded by default; and
+- a composable lifespan for application startup and shutdown hooks.
+
+Applications can use `fastapi_runner.lifespan.LifespanMap` as a FastAPI
+dependency to retrieve the value returned by a registered lifespan hook:
+
+```python
+import contextlib
+import typing as t
+
+import fastapi
+
+from fastapi_runner.lifespan import LifespanMap
+
+
+class State:
+    """State that is maintained for the application lifetime."""
+
+
+@contextlib.asynccontextmanager
+async def state_lifespan() -> t.AsyncGenerator[State]:
+    yield State()
+
+
+def get_state(*, lifespan: LifespanMap) -> t.Any:
+    return lifespan.get_state(state_lifespan)
+
+
+def status(*, state: t.Annotated[State, fastapi.Depends(get_state)]) -> State:
+    return state
+```
+
+The application may raise `fastapi_runner.errors.ProblemDetailError` when it
+needs to provide a complete problem-detail document. The default error
+handlers also allow an application to update the generated body through the
+`fastapi_runner_error_updater` callback on `app.state`.
+
+Use `fastapi_runner.middleware.disable_access_log` on an endpoint when its
+requests should not produce an access-log record.
+
+## Deployment
+
+The `dave-shawley/fastapi-builder` image is a suitable base image for deploying
+applications built using `fastapi-runner`. The _packaging/Dockerfile_ contains
+a multi-stage build that uses `fastapi-runner` to build the application and then
+copies the resulting artifacts into a minimal image. You should use a similar
+approach when deploying your application.
+
+The included Dockerfile also includes support for running the application with
+opentelemetry enabled though you will need to configure the exporter. I use
+opentelemetry-instrument to automatically instrument the application process.
+You simply need to include additional instrumentation libraries like
+[opentelemetry-instrumentation-psycopg] and the instrument command will pick it
+up and instrument the process.
+
+[opentelemetry-instrumentation-psycopg]: https://pypi.org/project/opentelemetry-instrumentation-psycopg/
+
+### Logging
+
+The default logging configuration is based on the [Common Logging Format](https://en.wikipedia.org/wiki/Common_Log_Format).
+The `fastapi_runner.middleware.AccessLogMiddleware` uses the logger named
+`api-runner.access` to log access records. I decided to push the field configuration
+into the logging configuration (see packaging/log-config.json) though I may change
+that in the future depending on ergonomics. The current implemention creates a log
+record with he following custom fields that are accessed using `%(name)s` in the
+format record.
+
+| Field              | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `%(bytes_sent)s`   | Number of bytes sent in the response              |
+| `%(client)s`       | Formatted client address                          |
+| `%(duration)s`     | Formatted duration of the request in milliseconds |
+| `%(http_version)s` | HTTP version                                      |
+| `%(method)s`       | HTTP request method                               |
+| `%(path)s`         | Request path                                      |
+| `%(status_code)s`  | Numeric status code or `-`                        |
+| `%(user_agent)s`   | User agent string or `-`                          |
+
+The formatted lines as configured by _packaging/log-config.json_ look like:
+
+```
+2026-10-08 11:44:26,328 WARNING api-runner.access: 192.168.215.1:52540 - "GET /missing HTTP/1.1" 404 22
+```
+
+I moved the date out of the log message so that it fits into the general log format.
+You can customize the message format to fit your needs by adjusting the formatter
+attached to the `api-runner.access` logger.
+
+The `FASTAPI_RUNNER_ACCESS_LOG` environment variable can be set to `no` to disable
+access logging. There is currently no way to change the access logger name.
+
+## Development
+
+From the repository root, the shared justfile provides the normal development
+commands:
+
+```console
+just test
+just analyze
+just format
+```
+
+Run only this library's tests directly when iterating on the package:
+
+```console
+uv run --package fastapi-runner pytest libraries/fastapi-runner/tests -q
+```
+
+Build its release artifacts from the repository root:
+
+```console
+uv build --package=fastapi-runner --sdist --wheel --clear
+```
+
+The artifacts are placed in the repository's `dist/` directory. Publishing is
+intentionally separate from the development recipes so each library can adopt
+its own release and PyPI workflow.

fastapi_runner-0.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastapi_runner/__init__.py,sha256=87LBqRGgVHzvmVx2uJgk56ZhaBOzvDSBRfEt4nuOVoM,90
+fastapi_runner/entrypoint.py,sha256=gNYELyrhB25xUEsmLZYJ0Z1eMgSUUfYzHYA6PzmNGos,6567
+fastapi_runner/error_handling.py,sha256=8oqmo47Dbd5VkV4Mn2d_o3goMbJui0Bt-mww155msaY,4673
+fastapi_runner/errors.py,sha256=K8H6vU64rs5Ik4hKEdrA-5XH_FPC1tcnCFjdjbP1arE,654
+fastapi_runner/lifespan.py,sha256=S3XQmih7kg44du5zDa3A9fXxclsCFQd3fHzt7U4cLq0,3731
+fastapi_runner/middleware.py,sha256=BeocDHSgR3rF8TUs5qQ3Ru_hSinVGkvnib_4ry9oUcQ,4760
+fastapi_runner/types.py,sha256=L3KJ_XCffLztpM3G_oCYcCCI1xLo5qj9tVO6MkwtybA,600
+fastapi_runner-0.0.0.dist-info/METADATA,sha256=x7LYRa-WOCkTF39M5ah3E9EwWziUOZ_GAO4-wv2ro7I,7942
+fastapi_runner-0.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fastapi_runner-0.0.0.dist-info/RECORD,,

fastapi_runner-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any