python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/api/__init__.py

@@ -1,9 +1,24 @@
 """
-FastAPI building blocks: handlers, routers and responses.
+FastAPI building blocks: an application, its lifespan, handlers, routers and responses.
 """
 
+from corekit.api.application import Application
 from corekit.api.handler import BaseHandler
+from corekit.api.lifespan import Lifespan, LifespanStep
+from corekit.api.middleware import MiddlewareLayer, MiddlewareStack
 from corekit.api.responses import SSEResponse
-from corekit.api.routers import SimpleRouter, SmartRouter
+from corekit.api.routers import CatchAllRouter, SimpleRouter, SmartRouter, router_registry
 
-__all__ = ["BaseHandler", "SSEResponse", "SimpleRouter", "SmartRouter"]
+__all__ = [
+    "Application",
+    "BaseHandler",
+    "CatchAllRouter",
+    "Lifespan",
+    "LifespanStep",
+    "MiddlewareLayer",
+    "MiddlewareStack",
+    "SSEResponse",
+    "SimpleRouter",
+    "SmartRouter",
+    "router_registry",
+]

corekit/api/application.py

@@ -0,0 +1,275 @@
+"""
+A FastAPI application that can find its own routers.
+
+``Application`` is a plain ``FastAPI`` subclass: every constructor argument,
+including ``lifespan``, is passed straight through and behaves exactly as it
+does upstream. What it adds is a short, explicit set of assembly steps::
+
+    from corekit.api import Application
+    from app.backend import routers
+
+    app = Application(lifespan=lifespan)
+    app.discover_routers(routers)
+    app.add_cors_middleware(allow_origins=ORIGINS, allow_credentials=True)
+    app.mount_static("/assets", "frontend/dist/assets")
+
+Nothing happens that is not written down. No middleware is installed by
+default -- middleware order is a security property, so it stays the caller's
+decision -- and every step logs what it did.
+"""
+
+import importlib
+import pkgutil
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Sequence
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from corekit.api.middleware import MiddlewareStack
+from corekit.api.routers import CatchAllRouter, SimpleRouter, router_registry
+from corekit.exceptions import CoreHTTPException
+from corekit.observability.loggable import Loggable
+
+__all__ = ["Application"]
+
+
+def _origin_in_package(router: SimpleRouter, package_name: str) -> bool:
+    """
+    Whether this router was constructed by ``package_name`` or a submodule.
+    """
+    origin = router._origin_module
+    return origin == package_name or origin.startswith(f"{package_name}.")
+
+
+async def _core_http_exception_handler(request: Any, exc: CoreHTTPException) -> JSONResponse:
+    """
+    The same body FastAPI returns for ``HTTPException``.
+    """
+    headers = getattr(exc, "headers", None)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail}, headers=headers)
+
+
+class Application(FastAPI, Loggable):
+    """
+    ``FastAPI`` plus router discovery, middleware helpers and static mounting.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Accepts every ``FastAPI`` argument and forwards it unchanged.
+        """
+        FastAPI.__init__(self, *args, **kwargs)
+        Loggable.__init__(self)
+        self._register_http_exception_handler()
+
+    # ─── Routers ──────────────────────────────────────────────────────────
+
+    def discover_routers(self, package: ModuleType) -> list[SimpleRouter]:
+        """
+        Import every module under ``package`` and mount the routers it defines.
+
+        Importing a module is what constructs its routers, so discovery is a
+        walk over ``package`` that lets each one register itself. Only routers
+        constructed inside that package are mounted: the registry is
+        process-wide, and an unclaimed router from some other import must not
+        ride along. A router that was included into another router is skipped
+        -- its parent already owns it -- and any ``CatchAllRouter`` is mounted
+        last.
+
+        Args:
+            package: The imported package to search, e.g. ``app.backend.routers``.
+                Passing the module itself rather than a string keeps the
+                reference something an IDE can follow.
+
+        Returns:
+            The routers that were mounted, in mount order.
+
+        Raises:
+            ValueError: If the walk finds no routers. Calling this method is an
+                explicit statement that routers live in ``package``; finding
+                none there means the wrong package was passed, and an app that
+                silently serves nothing is worse than one that refuses to start.
+        """
+        name = package.__name__
+        self.info(f"Discovering routers in {name}")
+
+        self._warn_on_unimportable_dirs(package)
+
+        scanned = self._import_submodules(package)
+        # unclaimed is every top-level router in the process. Mounting that
+        # list would include routers built by some other package that happens
+        # to be imported. Origin is where the instance was constructed, which
+        # is the scanned package for a router that belongs here.
+        mountable = [router for router in router_registry.unclaimed if _origin_in_package(router, name)]
+        if not mountable:
+            raise ValueError(
+                f"No routers found in '{name}' (scanned {scanned} modules). "
+                f"Check that the package is correct and that its modules build "
+                f"a SimpleRouter or SmartRouter at import time."
+            )
+
+        in_package = [router for router in router_registry if _origin_in_package(router, name)]
+        claimed = len(in_package) - len(mountable)
+        self.info(f"  scanned {scanned} modules, found {len(in_package)} routers")
+        if claimed > 0:
+            plural = "s" if claimed != 1 else ""
+            self.info(f"  skipped {claimed} sub-router{plural} (already included by a parent)")
+
+        for router in mountable:
+            self._mount_router(router)
+
+        self.info(f"Mounted {len(mountable)} routers")
+        return mountable
+
+    def _mount_router(self, router: SimpleRouter) -> None:
+        """
+        Include one router and log what it contributes.
+        """
+        prefix = router.prefix or "/"
+        kind = type(router).__name__
+        detail = ""
+        if router.dependencies:
+            names = [getattr(d.dependency, "__name__", "?") for d in router.dependencies]
+            detail = f"  deps={names}"
+        if isinstance(router, CatchAllRouter):
+            detail += "  (last)"
+
+        router.include(self)
+        self.info(f"  + {prefix:<24} {router._origin_module:<40} {kind}{detail}")
+
+    def _warn_on_unimportable_dirs(self, package: ModuleType) -> None:
+        """
+        Warn about directories the walk will silently skip.
+
+        ``pkgutil.walk_packages`` only descends into directories that are
+        packages, so one missing ``__init__.py`` hides every router beneath it
+        with no error. An explicit import still works, which is why this can sit
+        unnoticed until discovery is the thing doing the importing.
+        """
+        for root in package.__path__:
+            for child in sorted(Path(root).iterdir()):
+                if not child.is_dir() or child.name == "__pycache__":
+                    continue
+                if (child / "__init__.py").exists():
+                    continue
+                if not any(child.rglob("*.py")):
+                    continue
+                self.warning(
+                    f"  ! {child} has .py files but no __init__.py, so it is not a package "
+                    f"and everything under it will be skipped"
+                )
+
+    @staticmethod
+    def _import_submodules(package: ModuleType) -> int:
+        """
+        Import every submodule of ``package`` recursively, returning the count.
+        """
+        count = 0
+        for info in pkgutil.walk_packages(package.__path__, package.__name__ + "."):
+            importlib.import_module(info.name)
+            count += 1
+        return count
+
+    # ─── Middleware ───────────────────────────────────────────────────────
+    #
+    # Middleware is an onion: add_middleware prepends, so the last one added
+    # runs outermost. That ordering is a security property -- proxy headers
+    # must be trusted before a host check reads them -- so these helpers cut
+    # the boilerplate without ever choosing the order for you.
+    #
+    # Only middleware that ships with FastAPI or Starlette gets a helper here.
+    # ProxyHeadersMiddleware belongs to uvicorn, which corekit does not depend
+    # on, so add it directly:
+    #
+    #     from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
+    #     app.add_middleware(ProxyHeadersMiddleware, trusted_hosts="*")
+
+    def add_cors_middleware(
+        self,
+        allow_origins: Sequence[str],
+        allow_credentials: bool = True,
+        allow_methods: Sequence[str] = ("*",),
+        allow_headers: Sequence[str] = ("*",),
+        **kwargs: Any,
+    ) -> None:
+        """
+        Add CORS. ``allow_origins`` is required: browsers reject a wildcard
+        combined with credentials, so there is no safe default to pick.
+        """
+        self.add_middleware(
+            CORSMiddleware,
+            allow_origins=list(allow_origins),
+            allow_credentials=allow_credentials,
+            allow_methods=list(allow_methods),
+            allow_headers=list(allow_headers),
+            **kwargs,
+        )
+        self.info(f"  + CORSMiddleware(allow_origins={list(allow_origins)}, allow_credentials={allow_credentials})")
+
+    def add_trusted_host_middleware(self, allowed_hosts: Sequence[str], **kwargs: Any) -> None:
+        """
+        Reject requests whose Host header is not in ``allowed_hosts``.
+        """
+        self.add_middleware(TrustedHostMiddleware, allowed_hosts=list(allowed_hosts), **kwargs)
+        self.info(f"  + TrustedHostMiddleware(allowed_hosts={list(allowed_hosts)})")
+
+    def add_middleware_stack(self, stack: "MiddlewareStack") -> None:
+        """
+        Install a declared stack, outermost layer first.
+
+        ``add_middleware`` prepends, so adding in declaration order would build
+        the onion inside out. The layers are applied in reverse here, which is
+        what lets the stack be *written* in the order a request meets them --
+        the order you need to read to check that, say, proxy headers are
+        trusted before a host check consults them.
+        """
+        if not len(stack):
+            self.warning("  ! middleware stack is empty; nothing installed")
+            return
+
+        self.info(f"Installing {len(stack)} middleware layers (outermost first)")
+        for layer in reversed(stack.layers):
+            self.add_middleware(layer.middleware_class, **layer.options)
+        for position, layer in enumerate(stack.layers, start=1):
+            self.info(f"  {position}. {layer.describe()}")
+
+    # ─── Static files ─────────────────────────────────────────────────────
+
+    def mount_static(self, url_path: str, directory: str | Path, name: str | None = None, **kwargs: Any) -> bool:
+        """
+        Serve ``directory`` at ``url_path`` if it exists.
+
+        A missing directory is normal, not an error: a front end that has not
+        been built yet is the usual case in development, where a dev server
+        serves those assets instead.
+
+        Returns:
+            True if the directory existed and was mounted.
+        """
+        path = Path(directory)
+        if not path.is_dir():
+            self.info(f"  - static {url_path} not mounted ({path} does not exist)")
+            return False
+
+        self.mount(url_path, StaticFiles(directory=str(path), **kwargs), name=name or url_path.strip("/"))
+        self.info(f"  + static {url_path:<24} -> {path}")
+        return True
+
+    def _register_http_exception_handler(self) -> None:
+        """
+        Handle the library's HTTP exceptions the same way FastAPI handles its own.
+
+        ``CoreHTTPException`` is already an ``HTTPException``, so Starlette
+        would answer it. Registering the type explicitly keeps that response
+        -- ``{"detail": ...}`` only, never ``message`` or ``error`` -- even
+        if a later change in lookup order would otherwise miss the subclass.
+        A handler the caller already installed is left in place.
+        """
+        if CoreHTTPException in self.exception_handlers:
+            return
+        self.add_exception_handler(CoreHTTPException, _core_http_exception_handler)

corekit/api/lifespan.py

@@ -0,0 +1,233 @@
+"""
+Startup and shutdown steps, collected into one object.
+
+``Lifespan`` holds a list of steps and hands FastAPI a single lifespan. Each
+step contributes startup work, shutdown work, or both::
+
+    lifespan = Lifespan()
+    lifespan.add("yap", startup=yap_manager.startup, shutdown=yap_manager.shutdown)
+    lifespan.add("rq", startup=schedule_all_tasks)
+
+    app = Application(lifespan=lifespan)
+
+Steps start in the order added and shut down in reverse, the way nested
+``with`` blocks unwind. If one fails on the way up, the steps that already
+started are still torn down -- so a half-built application never leaks the
+resources it did manage to acquire.
+
+Two guarantees hold for a shutdown hook, so that writing one needs no
+defensive boilerplate:
+
+* It is called only if its own startup completed. A step that failed on the
+  way up does not have its shutdown run, so the hook may assume the state its
+  startup builds. Where that is wrong -- a startup that acquires something
+  before it can fail -- pass ``always_shutdown=True`` and handle partial state.
+* A hook that raises cannot stop the unwind. The failure is logged and the
+  remaining steps still shut down.
+
+Sync and async callables both work; a sync one is called directly, which is
+fine for the fast bookkeeping that startup usually is. Anything slow enough to
+block the event loop should be async, or should hand off to a thread itself.
+"""
+
+import inspect
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Awaitable, Callable
+
+from corekit.observability.loggable import Loggable
+
+__all__ = ["Lifespan", "LifespanStep"]
+
+Hook = Callable[[], Any | Awaitable[Any]]
+
+
+@dataclass
+class LifespanStep:
+    """
+    One named unit of startup and/or shutdown work.
+
+    ``started`` records whether this step's startup ran to completion. It is
+    what lets the unwind tell a fully-started step from one that failed partway,
+    and it is set by ``Lifespan``, not by the caller.
+    """
+
+    name: str
+    startup: Hook | None = None
+    shutdown: Hook | None = None
+    tags: tuple[str, ...] = field(default_factory=tuple)
+    always_shutdown: bool = False
+    started: bool = field(default=False, init=False)
+
+    def __post_init__(self) -> None:
+        if self.startup is None and self.shutdown is None:
+            raise ValueError(f"Lifespan step '{self.name}' does nothing: give it a startup, a shutdown, or both.")
+
+    @property
+    def needs_shutdown(self) -> bool:
+        """
+        Whether the unwind should call this step's shutdown.
+
+        A step with no startup has nothing to half-do, so its shutdown always
+        runs. Otherwise the shutdown runs only if the startup completed --
+        unless the step opted into ``always_shutdown``, which is for a startup
+        that acquires something before it can fail.
+        """
+        if self.shutdown is None:
+            return False
+        if self.startup is None or self.always_shutdown:
+            return True
+        return self.started
+
+
+class Lifespan(Loggable):
+    """
+    A composable application lifespan.
+
+    Pass the instance straight to ``Application(lifespan=...)``: ``__call__`` is
+    the async context manager FastAPI expects, so no wrapper is needed.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._steps: list[LifespanStep] = []
+
+    def add(
+        self,
+        name: str,
+        startup: Hook | None = None,
+        shutdown: Hook | None = None,
+        tags: tuple[str, ...] = (),
+        always_shutdown: bool = False,
+    ) -> "Lifespan":
+        """
+        Append a step. Returns self, so calls can be chained.
+
+        Args:
+            name: Shown in logs and in errors. Make it recognisable at 3am.
+            startup: Called on the way up, in the order steps were added.
+            shutdown: Called on the way down, in reverse order. Called only if
+                ``startup`` completed, so it can assume what ``startup`` builds.
+            tags: Labels used by ``for_tags``. Untagged steps always run; a
+                tagged step runs only when one of its tags is selected. With
+                no filter, every step runs.
+            always_shutdown: Call ``shutdown`` even when ``startup`` raised.
+                For a startup that acquires something before it can fail -- a
+                connection opened, then a handshake that throws. The hook then
+                has to cope with partial state, which is why it is not default.
+        """
+        self._steps.append(
+            LifespanStep(
+                name=name,
+                startup=startup,
+                shutdown=shutdown,
+                tags=tags,
+                always_shutdown=always_shutdown,
+            )
+        )
+        return self
+
+    def __len__(self) -> int:
+        return len(self._steps)
+
+    def __iter__(self) -> Any:
+        return iter(self._steps)
+
+    @property
+    def steps(self) -> list[LifespanStep]:
+        """The registered steps, in the order they will start."""
+        return list(self._steps)
+
+    def for_tags(self, *tags: str) -> "Lifespan":
+        """
+        A lifespan that runs the steps matching ``tags``, plus untagged ones.
+
+        An untagged step is ordinary startup and always runs. A tagged step
+        runs only when the caller asked for one of its tags, so a label is a
+        filter rather than decoration. No tags means every step, which is
+        what ``__call__`` does.
+        """
+        if not tags:
+            return self
+
+        wanted = set(tags)
+        selected = Lifespan()
+        for step in self._steps:
+            if not step.tags or wanted.intersection(step.tags):
+                selected._steps.append(step)
+        return selected
+
+    @asynccontextmanager
+    async def __call__(self, app: Any = None) -> AsyncIterator[None]:
+        """
+        Run every startup, yield to the application, then run every shutdown.
+
+        Args:
+            app: The application, passed by FastAPI and not otherwise used.
+        """
+        async with AsyncExitStack() as stack:
+            for step in self._steps:
+                await self._enter(stack, step)
+            self.info(f"Startup complete ({len(self._steps)} steps)")
+            yield
+
+    async def _enter(self, stack: AsyncExitStack, step: LifespanStep) -> None:
+        """
+        Run one step's startup, having first armed its shutdown for the unwind.
+
+        The callback is pushed *before* the startup runs, because a startup that
+        throws halfway has already left the exit stack behind it -- pushing
+        afterwards would mean a failed boot never unwinds at all.
+
+        Whether that armed callback actually calls the hook is decided later, by
+        ``needs_shutdown``. So the default is the safe one in both directions: a
+        shutdown hook is never handed a step that did not finish starting, and
+        the steps that did finish are always torn down.
+        """
+        stack.push_async_callback(self._run_shutdown, step)
+
+        if step.startup is not None:
+            label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+            self.info(f"  ^ {label}")
+            try:
+                await self._maybe_await(step.startup)
+            except Exception:
+                self.exception(f"Startup step '{step.name}' failed; shutting down the steps that started")
+                raise
+
+        step.started = True
+
+    async def _run_shutdown(self, step: LifespanStep) -> None:
+        """
+        Run one step's shutdown, if it should run, logging rather than raising.
+
+        Skipped for a step whose startup did not complete, so a hook can assume
+        the state its own startup builds. A step that acquires something before
+        it can fail sets ``always_shutdown`` and takes on that check itself.
+
+        Failures are logged and swallowed: a shutdown that raised would abandon
+        every step below it, so one noisy subsystem cannot stop the rest from
+        closing cleanly.
+        """
+        if not step.needs_shutdown:
+            if step.shutdown is not None:
+                self.warning(f"  - {step.name} (skipped: startup did not complete)")
+            return
+
+        label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+        self.info(f"  v {label}")
+        try:
+            await self._maybe_await(step.shutdown)
+        except Exception:
+            self.exception(f"Shutdown step '{step.name}' failed; continuing with the rest")
+
+    @staticmethod
+    async def _maybe_await(hook: Hook | None) -> None:
+        """
+        Call ``hook``, awaiting it if it returns an awaitable.
+        """
+        if hook is None:
+            return
+        result = hook()
+        if inspect.isawaitable(result):
+            await result

corekit/api/middleware.py

@@ -0,0 +1,93 @@
+"""
+Declared middleware stacks.
+
+Middleware is an onion, and the order of the layers is a security property: a
+host check that reads a client address before the proxy-header layer has
+rewritten it is checking the proxy, not the client. So middleware is *not*
+auto-discovered the way routers are. A router registers itself at import and
+order between routers does not matter; if import order decided your security
+layering, moving an import could silently open a hole.
+
+Instead, a stack is declared in one place, outermost first -- the order a
+request actually meets them::
+
+    stack = (
+        MiddlewareStack()
+        .add(ProxyHeadersMiddleware, trusted_hosts="*")
+        .add(TrustedHostMiddleware, allowed_hosts=HOSTS)
+        .add(CORSMiddleware, allow_origins=ORIGINS, allow_credentials=True)
+    )
+    app.add_middleware_stack(stack)
+
+Reading top to bottom gives the order a request travels, which is the property
+you need to check when reviewing it.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from corekit.registry import OrderedRegistry
+
+__all__ = ["MiddlewareLayer", "MiddlewareStack"]
+
+
+@dataclass
+class MiddlewareLayer:
+    """
+    One middleware class and the keyword arguments it is built with.
+    """
+
+    middleware_class: type
+    options: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def name(self) -> str:
+        """
+        The middleware class name, for logging.
+        """
+        return self.middleware_class.__name__
+
+    def describe(self) -> str:
+        """
+        Render the layer as ``Name(key=value, ...)`` for a log line.
+        """
+        if not self.options:
+            return f"{self.name}()"
+        rendered = ", ".join(f"{key}={value!r}" for key, value in self.options.items())
+        return f"{self.name}({rendered})"
+
+
+class MiddlewareStack(OrderedRegistry[MiddlewareLayer]):
+    """
+    An ordered set of middleware layers, declared outermost first.
+
+    Outermost first means the order a request meets them on the way in, and the
+    reverse of the order a response passes them on the way out. This is the
+    opposite of Starlette's ``add_middleware``, which prepends -- so the same
+    stack written for that API reads backwards. Declaring it in request order
+    is what makes a review of the ordering possible.
+
+    Ordering with duplicates allowed is exactly what ``OrderedRegistry``
+    provides, so the collection behaviour is inherited; ``add`` is the
+    middleware-shaped way to build an entry.
+    """
+
+    def add(self, middleware_class: type, **options: Any) -> "MiddlewareStack":
+        """
+        Append a layer, inside every layer added before it. Chainable.
+        """
+        self.register(MiddlewareLayer(middleware_class, options))
+        return self
+
+    @property
+    def layers(self) -> list[MiddlewareLayer]:
+        """
+        The layers, outermost first. Reads better than ``entries`` at a call site.
+        """
+        return self.entries
+
+    def __repr__(self) -> str:
+        """
+        Return a formal representation naming the layers in order.
+        """
+        return f"{type(self).__name__}({[layer.name for layer in self]})"