lcl-fastapi 0.1.0__py3-none-any.whl

lcl_fastapi/__init__.py

@@ -0,0 +1,8 @@
+"""Public application, configuration, logging, and request-context interfaces."""
+
+from lcl_fastapi.context import RequestContext, get_config, get_request_context
+from lcl_fastapi.logging import get_logger
+from lcl_fastapi.service import LclFastAPI
+
+# Unitless public names define the first-version import contract.
+__all__ = ["LclFastAPI", "RequestContext", "get_config", "get_logger", "get_request_context"]

lcl_fastapi/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration-driven console operations built on lclang.cli."""
+
+from lcl_fastapi.cli.main import main
+
+__all__ = ["main"]

lcl_fastapi/cli/arguments.py

@@ -0,0 +1,35 @@
+"""Preflight service CLI policy using lclang's public option parser."""
+
+from collections.abc import Sequence
+
+from lclang.cli.parser import parse_cli_params, split_argv
+
+
+def validate_arguments(arguments: Sequence[str]) -> None:
+    """Reject service overrides before lclang can construct a logger scope.
+
+    :param arguments: Full Python-style argv with an internal ``.py`` script label.
+    :raises ValueError: If the invocation supplies a forbidden configuration source or key.
+    :raises LclCliUsageError: If lclang rejects option syntax or argument arity.
+    """
+    parts = split_argv(arguments)
+    tokens = parts.tokens
+    if not tokens or tokens in (("-v",), ("--version",)):
+        return
+    option_start = next(
+        (index for index, token in enumerate(tokens) if token.startswith("-")), len(tokens)
+    )
+    command = tokens[:option_start]
+    params = parse_cli_params(parts, command or ("help",), tokens[option_start:])
+    if params.config_file_path is not None:
+        raise ValueError("-c/--config is unavailable; use -o config service.lclcfg")
+    if params.dryrun:
+        raise ValueError("dryrun is unavailable; render commands already only generate files")
+    allowed = {"config"}
+    if command in (("status",), ("logs",)):
+        allowed.add("json")
+    if command in (("nginx", "render"), ("systemd", "render")):
+        allowed.add("output")
+    unknown = params.overrides.keys() - allowed
+    if unknown:
+        raise ValueError(f"unsupported override: {', '.join(sorted(unknown))}")

lcl_fastapi/cli/commands.py

@@ -0,0 +1,148 @@
+"""Declare the six operational commands using the supported lclang CLI surface."""
+
+import asyncio
+from pathlib import Path
+from typing import Literal
+
+from lclang.cli import CliContext, CliResult, Command, CommandGroup, ParameterDoc, cli
+
+from lcl_fastapi.cli.output import format_logs, format_status
+from lcl_fastapi.render.config import render_config
+from lcl_fastapi.render.validation import text_value
+
+
+async def config_path(context: CliContext) -> Path:
+    """Read the service file path as ordinary CLI data, never a CLI config layer.
+
+    :param context: Active lclang command invocation.
+    :returns: Absolute service configuration file path.
+    :raises ValueError: If the config parameter is not nonempty path text.
+    """
+    value = await context.frame.get("config")
+    return await asyncio.to_thread(Path(text_value(value, "config")).resolve)
+
+
+async def json_output(context: CliContext) -> bool:
+    """Resolve the explicit LCL Boolean controlling operational JSON output.
+
+    :param context: Active lclang command invocation.
+    :returns: Whether the complete result should be emitted as JSON.
+    :raises ValueError: If json is not a Boolean.
+    """
+    value = await context.frame.get("json", fallback=False)
+    if not isinstance(value, bool):
+        raise ValueError('json must be Boolean; use -o json or -o json "LCL[True]"')
+    return value
+
+
+def renderer_command(kind: Literal["nginx", "systemd"]) -> Command:
+    """Declare a render leaf that only writes the requested output file.
+
+    :param kind: Deployment artifact to render.
+    :returns: A lclang command with config and optional output parameters.
+    """
+
+    async def render_command(context: CliContext) -> CliResult:
+        """Generate deployment text and return it or write a caller-selected file.
+
+        :param context: Validated invocation with an ordinary service path parameter.
+        :returns: Rendered text or an empty success after writing a file.
+        :raises ValueError: If renderer configuration or output path is invalid.
+        :raises OSError: If reading configuration or writing the output fails.
+        """
+        result = await render_config(kind, await config_path(context))
+        output = await context.frame.get("output", fallback=None)
+        if output is None:
+            return CliResult.success(result.rstrip("\n"))
+        path = Path(text_value(output, "output"))
+        await asyncio.to_thread(path.write_text, result, encoding="utf-8", newline="\n")
+        return CliResult.success("")
+
+    return cli.command(
+        "render",
+        f"Generate {kind} configuration; never install or reload it.",
+        parameter_docs=(
+            ParameterDoc("config", str, True, "Service .lclcfg file path."),
+            ParameterDoc("output", str, False, "Output file path; omit for stdout."),
+        ),
+    )(render_command)
+
+
+def command_group(pending: list[Path]) -> CommandGroup:
+    """Create an isolated CLI command tree and a deferred server-start handoff.
+
+    :param pending: Caller-owned empty list receiving the serve configuration path.
+    :returns: Root lclang group containing only supported first-version commands.
+    """
+    config_doc = ParameterDoc("config", str, True, "Service .lclcfg file path.")
+    json_doc = ParameterDoc("json", bool, False, "Return JSON; use -o json.", False)
+
+    @cli.command("serve", "Run the service until graceful shutdown.", (config_doc,))
+    async def serve_command(context: CliContext) -> CliResult:
+        """Defer server startup until the command logger and event loop are closed.
+
+        :param context: Active command invocation.
+        :returns: Empty success after retaining the service configuration path.
+        :raises ValueError: If the config parameter is invalid.
+        """
+        pending.append(await config_path(context))
+        return CliResult.success("")
+
+    @cli.command(
+        "status", "Inspect the local service identity and workers.", (config_doc, json_doc)
+    )
+    async def status_command(context: CliContext) -> CliResult:
+        """Read a runtime snapshot using PID and process-creation identity checks.
+
+        :param context: Active command invocation.
+        :returns: Plain text or JSON runtime status.
+        :raises ValueError: If command configuration is invalid.
+        :raises OSError: If local runtime inspection fails.
+        """
+        from lcl_fastapi.runtime.common import inspect_status
+
+        result = await inspect_status(await config_path(context))
+        return CliResult.success(format_status(result, as_json=await json_output(context)))
+
+    @cli.command("logs", "List live workers' observed active log segments.", (config_doc, json_doc))
+    async def logs_command(context: CliContext) -> CliResult:
+        """Return observed log paths without querying a network endpoint.
+
+        :param context: Active command invocation.
+        :returns: Plain paths or a JSON observation snapshot.
+        :raises ValueError: If command configuration or runtime output is invalid.
+        :raises OSError: If local runtime inspection fails.
+        """
+        from lcl_fastapi.runtime.common import active_logs
+
+        result = await active_logs(await config_path(context))
+        return CliResult.success(format_logs(result, as_json=await json_output(context)))
+
+    @cli.command("stop", "Request authenticated graceful shutdown over loopback.", (config_doc,))
+    async def stop_command(context: CliContext) -> CliResult:
+        """Invoke the identity-checked local control operation.
+
+        :param context: Active command invocation.
+        :returns: Empty success after the runtime accepts the stop request.
+        :raises ValueError: If configuration or service identity is invalid.
+        :raises OSError: If the verified local service cannot be reached.
+        """
+        from lcl_fastapi.runtime.common import stop
+
+        await stop(await config_path(context))
+        return CliResult.success("")
+
+    return CommandGroup(
+        "lcl_fastapi",
+        "Local service operations; configuration comes from .lclcfg.",
+        (
+            serve_command,
+            status_command,
+            logs_command,
+            stop_command,
+            CommandGroup(
+                "nginx", "Nginx deployment file generation.", (renderer_command("nginx"),)
+            ),
+            CommandGroup("systemd", "systemd unit generation.", (renderer_command("systemd"),)),
+        ),
+    )

lcl_fastapi/cli/main.py

@@ -0,0 +1,41 @@
+"""Run lclang CLI scopes before entering the platform's process manager."""
+
+import asyncio
+import sys
+from collections.abc import Sequence
+from importlib.metadata import version
+from pathlib import Path
+
+from lclang.cli import CliConfig, CliEntrance
+from lclang.errors import LclError
+from lclang.logger import LoggerHandlerConfig
+
+from lcl_fastapi.cli.arguments import validate_arguments
+from lcl_fastapi.cli.commands import command_group
+
+
+def main(arguments: Sequence[str] | None = None) -> int:
+    """Execute an operational command and then any deferred foreground server.
+
+    :param arguments: Tokens after the console command, or None for process argv.
+    :returns: Zero for success and a nonzero command or startup error status.
+    """
+    tokens = list(sys.argv[1:] if arguments is None else arguments)
+    full_arguments = [sys.executable, "lcl-fastapi.py", *tokens]
+    pending: list[Path] = []
+    try:
+        validate_arguments(full_arguments)
+        entrance = CliEntrance(
+            command_group(pending),
+            version=version("lcl-fastapi"),
+            cli_config=CliConfig(LoggerHandlerConfig(console={"stream": "stderr"}, file={})),
+        )
+        result = asyncio.run(entrance.run(full_arguments))
+        if result == 0 and pending:
+            from lcl_fastapi.runtime.common import serve
+
+            serve(pending[0])
+        return result
+    except (ValueError, OSError, RuntimeError, LclError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2

lcl_fastapi/cli/output.py

@@ -0,0 +1,34 @@
+"""Format local operational results without mixing diagnostics into stdout."""
+
+import json
+from collections.abc import Mapping
+
+
+def format_status(result: Mapping[str, object], *, as_json: bool) -> str:
+    """Format a runtime status snapshot for a person or a JSON consumer.
+
+    :param result: JSON-compatible runtime status fields.
+    :param as_json: Whether to emit the complete structured snapshot.
+    :returns: JSON or stable, readable field rows.
+    """
+    if as_json:
+        return json.dumps(dict(result), ensure_ascii=False, sort_keys=True)
+    return "\n".join(
+        f"{name.replace('_', ' ').title():<20} {value}" for name, value in result.items()
+    )
+
+
+def format_logs(result: Mapping[str, object], *, as_json: bool) -> str:
+    """Format active paths while retaining observation metadata in JSON mode.
+
+    :param result: Runtime snapshot with paths, observed_at, and stale fields.
+    :param as_json: Whether to include the complete observation metadata.
+    :returns: JSON or one absolute path per line.
+    :raises ValueError: If the runtime does not return a list of textual paths.
+    """
+    paths = result.get("paths")
+    if not isinstance(paths, list) or not all(isinstance(path, str) for path in paths):
+        raise ValueError("runtime log snapshot must contain a paths list of strings")
+    if as_json:
+        return json.dumps(dict(result), ensure_ascii=False, sort_keys=True)
+    return "\n".join(str(path) for path in paths)

lcl_fastapi/config.py

@@ -0,0 +1,277 @@
+"""Read trusted LCL files into validated worker and service settings."""
+
+import asyncio
+import math
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from lclang.config import Config, load_config
+from lclang.runtime import Frame
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Store validated values without retaining a configuration Frame.
+
+    :param app_name: Service name recorded in runtime state.
+    :param app_version: Downstream application's version text.
+    :param app_target: Import target in module:attribute form.
+    :param host: Loopback or all-IPv4 listener address.
+    :param port: TCP port between 1 and 65535.
+    :param workers: Configured worker count.
+    :param origin: Optional external HTTP(S) origin, never an ASGI path.
+    :param state_dir: Absolute service state directory.
+    :param pid_file: Absolute service PID file.
+    :param worker_state_dir: Absolute worker-state directory.
+    :param backlog: Pending connection queue capacity.
+    :param keep_alive_seconds: Idle HTTP connection timeout in seconds.
+    :param graceful_timeout_seconds: Graceful shutdown deadline in seconds.
+    :param health_enabled: Whether to register the default health endpoint.
+    :param health_path: Absolute health route path.
+    :param sample_interval_seconds: State and metric refresh interval in seconds.
+    :param disk_paths: Absolute filesystem paths included in health sampling.
+    :param docs_enabled: Whether to register built-in Swagger resources.
+    :param docs_path: Absolute Swagger HTML route path.
+    :param openapi_path: Absolute schema route path.
+    :param id_header: ASCII HTTP response header carrying the request ID.
+    :param worker_id_base: First allowed Snowflake worker ID.
+    :param worker_id_count: Number of allowed consecutive worker IDs.
+    """
+
+    app_name: str
+    app_version: str
+    app_target: str
+    host: str
+    port: int
+    workers: int
+    origin: str
+    state_dir: Path
+    pid_file: Path
+    worker_state_dir: Path
+    backlog: int
+    keep_alive_seconds: int
+    graceful_timeout_seconds: int
+    health_enabled: bool
+    health_path: str
+    sample_interval_seconds: float
+    disk_paths: tuple[Path, ...]
+    docs_enabled: bool
+    docs_path: str
+    openapi_path: str
+    id_header: str
+    worker_id_base: int
+    worker_id_count: int
+
+
+def text_value(value: object, name: str) -> str:
+    """Validate nonempty text without control characters.
+
+    :param value: Resolved configuration value.
+    :param name: Qualified name used in diagnostics.
+    :returns: Validated text.
+    :raises ValueError: If text is absent, empty, or contains controls.
+    """
+    if not isinstance(value, str) or not value or any(ord(char) < 32 for char in value):
+        raise ValueError(f"{name}: expected nonempty text without controls")
+    return value
+
+
+def integer_value(value: object, name: str, minimum: int, maximum: int) -> int:
+    """Validate a bounded integer without accepting Boolean values.
+
+    :param value: Resolved configuration value.
+    :param name: Qualified name used in diagnostics.
+    :param minimum: Inclusive lower bound.
+    :param maximum: Inclusive upper bound.
+    :returns: Validated integer.
+    :raises ValueError: If the value has an invalid type or exceeds a bound.
+    """
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise ValueError(f"{name}: expected an integer from {minimum} to {maximum}")
+    return value
+
+
+def origin_value(value: object) -> str:
+    """Validate external origin metadata without interpreting it as a path.
+
+    :param value: Empty text or an HTTP(S) origin.
+    :returns: Original validated origin.
+    :raises ValueError: If the value contains credentials, a path, or URL suffixes.
+    """
+    if value == "":
+        return ""
+    origin = text_value(value, "server.root_path")
+    parsed = urlsplit(origin)
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path
+        or parsed.query
+        or parsed.fragment
+        or any(char.isspace() for char in origin)
+        or "\\" in origin
+        or "?" in origin
+        or "#" in origin
+        or parsed.netloc.endswith(":")
+    ):
+        raise ValueError("server.root_path: expected an HTTP(S) origin without a path")
+    if parsed.port is not None and not 1 <= parsed.port <= 65535:
+        raise ValueError("server.root_path: invalid port")
+    return origin
+
+
+@asynccontextmanager
+async def configuration_frame(
+    config_path: Path,
+    worker_pid: int | None = None,
+) -> AsyncIterator[Frame]:
+    """Load fresh source files and own their combined LCL Frame.
+
+    :param config_path: Trusted service configuration file.
+    :param worker_pid: Actual worker PID, or None for non-worker settings inspection.
+    :returns: Async context manager yielding a caller-scoped Frame.
+    :raises LclConfigError: If a source cannot be loaded or parsed.
+    :raises ValueError: If a service defines the framework-owned worker PID.
+    """
+    defaults = await load_config(Path(__file__).parent / "static" / "defaults.lclcfg")
+    loaded = await load_config(config_path)
+    if "worker_pid" in loaded.definitions:
+        raise ValueError("worker_pid is provided by the framework")
+    combined = Config(loaded.version, loaded.root_origin, defaults.expanded + loaded.expanded)
+    values: dict[str, object] = {} if worker_pid is None else {"worker_pid": worker_pid}
+    async with combined.frame_factory().create(values=values) as frame:
+        yield frame
+
+
+async def settings_from_frame(frame: Frame, config_path: Path) -> Settings:
+    """Resolve settings while leaving logger expressions lazy.
+
+    :param frame: Caller-owned active configuration Frame.
+    :param config_path: File whose parent anchors relative filesystem values.
+    :returns: Validated detached service settings.
+    :raises ValueError: If a setting has an invalid type or combination.
+    :raises LclError: If a required value is absent or fails evaluation.
+    """
+
+    async def text(name: str) -> str:
+        """Resolve one nonempty string.
+
+        :param name: Qualified configuration key.
+        :returns: Validated string.
+        :raises ValueError: If the resolved value is not valid text.
+        """
+        return text_value(await frame.get(name), name)
+
+    async def number(name: str, minimum: int, maximum: int) -> int:
+        """Resolve one integer with explicit bounds.
+
+        :param name: Qualified configuration key.
+        :param minimum: Inclusive lower bound.
+        :param maximum: Inclusive upper bound.
+        :returns: Validated integer.
+        :raises ValueError: If the value is not a bounded integer.
+        """
+        return integer_value(await frame.get(name), name, minimum, maximum)
+
+    async def flag(name: str) -> bool:
+        """Resolve a strict Boolean.
+
+        :param name: Qualified configuration key.
+        :returns: Validated Boolean.
+        :raises ValueError: If the value is not Boolean.
+        """
+        value = await frame.get(name)
+        if not isinstance(value, bool):
+            raise ValueError(f"{name}: expected a Boolean")
+        return value
+
+    async def path(name: str) -> str:
+        """Resolve a route without query or fragment components.
+
+        :param name: Qualified route configuration key.
+        :returns: Absolute route path.
+        :raises ValueError: If the route is not an absolute path.
+        """
+        value = await text(name)
+        if not value.startswith("/") or value.startswith("//") or any(c in value for c in "?#"):
+            raise ValueError(f"{name}: expected an absolute route path")
+        return value
+
+    base = (await asyncio.to_thread(config_path.resolve)).parent
+
+    async def filesystem_path(name: str) -> Path:
+        """Resolve a configured path outside the event-loop thread.
+
+        :param name: Qualified filesystem configuration key.
+        :returns: Absolute path anchored to the configuration directory.
+        :raises ValueError: If the configured value is not text.
+        """
+        selected = base / await text(name)
+        return await asyncio.to_thread(selected.resolve)
+
+    host = await text("server.host")
+    if host not in {"127.0.0.1", "0.0.0.0"}:
+        raise ValueError("server.host: expected 127.0.0.1 or 0.0.0.0")
+    workers = await number("server.workers", 1, 1024)
+    worker_base = await number("snowflake.worker_id_base", 0, 1023)
+    worker_count = await number("snowflake.worker_id_count", workers, 1024 - worker_base)
+    interval = await frame.get("health.sample_interval_seconds")
+    if (
+        isinstance(interval, bool)
+        or not isinstance(interval, (int, float))
+        or not math.isfinite(interval)
+        or interval <= 0
+    ):
+        raise ValueError("health.sample_interval_seconds: expected a positive number")
+    disks = await frame.get("health.disk_paths")
+    if not isinstance(disks, (list, tuple)):
+        raise ValueError("health.disk_paths: expected a list of paths")
+    disk_paths = []
+    for item in disks:
+        disk_path = base / text_value(item, "health.disk_paths")
+        disk_paths.append(await asyncio.to_thread(disk_path.resolve))
+    header = await text("request.id_header")
+    if not all(char.isascii() and (char.isalnum() or char in "!#$%&'*+-.^_`|~") for char in header):
+        raise ValueError("request.id_header: expected an ASCII HTTP header name")
+    return Settings(
+        await text("app.name"),
+        await text("app.version"),
+        await text("app.target"),
+        host,
+        await number("server.port", 1, 65535),
+        workers,
+        origin_value(await frame.get("server.root_path")),
+        await filesystem_path("runtime.state_dir"),
+        await filesystem_path("runtime.pid_file"),
+        await filesystem_path("runtime.worker_state_dir"),
+        await number("server.backlog", 1, 65535),
+        await number("server.keep_alive_seconds", 0, 86400),
+        await number("server.graceful_timeout_seconds", 1, 86400),
+        await flag("health.enabled"),
+        await path("health.path"),
+        float(interval),
+        tuple(disk_paths),
+        await flag("docs.enabled"),
+        await path("docs.path"),
+        await path("docs.openapi_path"),
+        header,
+        worker_base,
+        worker_count,
+    )
+
+
+async def load_settings(config_path: Path) -> Settings:
+    """Load detached settings without initializing worker logging.
+
+    :param config_path: Trusted service configuration path.
+    :returns: Validated service settings.
+    :raises LclError: If configuration loading or evaluation fails.
+    :raises ValueError: If a setting is invalid.
+    """
+    async with configuration_frame(config_path) as frame:
+        return await settings_from_frame(frame, config_path)

lcl_fastapi/context.py

@@ -0,0 +1,50 @@
+"""Task-local request and configuration bindings for active worker scopes."""
+
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+from lclang.runtime import Frame
+
+
+@dataclass(frozen=True, slots=True)
+class RequestContext:
+    """Describe one HTTP request without mutable shared state.
+
+    :param request_id: Decimal server-generated Snowflake identifier.
+    :param method: HTTP request method.
+    :param path: Request path without query parameters.
+    :param started_ns: Monotonic start time in nanoseconds.
+    """
+
+    request_id: str
+    method: str
+    path: str
+    started_ns: int
+
+
+# Task-local bindings have no units; None means no active framework scope.
+REQUEST_CONTEXT: ContextVar[RequestContext | None] = ContextVar("lcl_request", default=None)
+CONFIG_FRAME: ContextVar[Frame | None] = ContextVar("lcl_config", default=None)
+
+
+def get_request_context() -> RequestContext | None:
+    """Read the current request binding without creating state.
+
+    :returns: Immutable request context, or None outside an HTTP request.
+    """
+    return REQUEST_CONTEXT.get()
+
+
+async def get_config(key: str) -> object:
+    """Evaluate a business setting in the current worker Frame.
+
+    :param key: Qualified LCL configuration name.
+    :returns: Value resolved by the worker's existing LCL Frame.
+    :raises RuntimeError: If called outside the worker lifespan or request scope.
+    :raises LclNameError: If the configuration name is absent.
+    :raises LclEvaluationError: If the configured expression cannot be evaluated.
+    """
+    frame = CONFIG_FRAME.get()
+    if frame is None:
+        raise RuntimeError("get_config requires an active worker lifespan or request")
+    return await frame.get(key)

lcl_fastapi/docs/__init__.py

@@ -0,0 +1 @@
+"""Offline documentation route assembly."""

lcl_fastapi/docs/swagger.py

@@ -0,0 +1,62 @@
+"""Serve Swagger HTML and assets exclusively from this application."""
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.openapi.docs import get_swagger_ui_html
+from starlette.responses import HTMLResponse, JSONResponse
+from starlette.staticfiles import StaticFiles
+
+from lcl_fastapi.config import Settings
+
+
+def swagger_page(settings: Settings) -> HTMLResponse:
+    """Produce offline Swagger HTML without a remote validator or favicon.
+
+    :param settings: Validated application documentation settings.
+    :returns: HTML referring only to local static and OpenAPI endpoints.
+    """
+    return get_swagger_ui_html(
+        openapi_url=settings.openapi_path,
+        title=f"{settings.app_name} - Swagger UI",
+        swagger_js_url="/_lcl/static/swagger/swagger-ui-bundle.js",
+        swagger_css_url="/_lcl/static/swagger/swagger-ui.css",
+        swagger_favicon_url="/_lcl/static/swagger/favicon-32x32.png",
+        swagger_ui_parameters={"validatorUrl": None},
+    )
+
+
+def register_documentation(app: FastAPI, settings: Settings) -> None:
+    """Add fallback docs routes while preserving exact business overrides.
+
+    :param app: Application whose existing routes take precedence.
+    :param settings: Worker-resolved documentation paths and enable flag.
+    """
+    if not settings.docs_enabled:
+        return
+
+    async def docs_page() -> HTMLResponse:
+        """Render the configured Swagger page.
+
+        :returns: Locally served Swagger HTML.
+        """
+        return swagger_page(settings)
+
+    async def schema_page() -> JSONResponse:
+        """Render the current application schema.
+
+        :returns: OpenAPI schema without the private shutdown endpoint.
+        """
+        return JSONResponse(app.openapi())
+
+    for path, endpoint in ((settings.docs_path, docs_page), (settings.openapi_path, schema_page)):
+        if not any(
+            getattr(route, "path", None) == path and "GET" in getattr(route, "methods", set())
+            for route in app.routes
+        ):
+            app.add_api_route(path, endpoint, methods=["GET"], include_in_schema=False)
+    app.mount(
+        "/_lcl/static/swagger",
+        StaticFiles(directory=Path(__file__).parent.parent / "static" / "swagger"),
+        name="lcl-swagger-static",
+    )

lcl_fastapi/health/__init__.py

@@ -0,0 +1 @@
+"""Cached health metrics with failure-tolerant system sampling."""