supython 0.1.0__py3-none-any.whl

supython/functions/context.py

@@ -0,0 +1,262 @@
+"""Per-request context object passed to every user function.
+
+This is the *one* module in supython that is allowed to import across feature
+packages: it composes ``storage``, ``mailer``, and ``postgrest`` into the
+``Ctx`` value that handlers receive. Functions are the edge layer — they
+exist precisely so user code can stitch sibling subsystems together — so the
+loader/dispatcher pair is the deliberate exception to the no-cross-import
+rule that applies elsewhere.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+import asyncpg
+import httpx
+
+from ..mailer import EmailBackend, EmailMessage, get_mailer
+from ..settings import Settings, get_settings
+from ..storage import service as storage_service
+from ..storage.backends import StorageBackend, get_backend
+from ..storage.schemas import ObjectResponse, SignedUrlResponse
+
+if TYPE_CHECKING:  # pragma: no cover
+    from fastapi import Request
+
+
+# ---------------------------------------------------------------------------
+# User
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FunctionUser:
+    """Caller identity decoded from the bearer token, or ``None`` for anon."""
+
+    id: UUID | None
+    email: str | None
+    role: str
+    claims: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_claims(cls, claims: dict[str, Any]) -> FunctionUser:
+        sub = claims.get("sub")
+        try:
+            uid = UUID(sub) if isinstance(sub, str) else None
+        except ValueError:
+            uid = None
+        email = claims.get("email")
+        role = claims.get("role") or "anon"
+        return cls(
+            id=uid,
+            email=email if isinstance(email, str) else None,
+            role=role if isinstance(role, str) else "anon",
+            claims=claims,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Storage facade
+# ---------------------------------------------------------------------------
+
+
+class StorageClient:
+    """Short-call-site wrapper around ``storage.service`` bound to ``ctx.db``.
+
+    All authorization still flows through the role-scoped connection — the
+    wrapper exists purely so handlers can write
+    ``await ctx.storage.upload(...)`` instead of threading ``conn`` and
+    ``backend`` by hand.
+    """
+
+    def __init__(
+        self, conn: asyncpg.Connection, backend: StorageBackend
+    ) -> None:
+        self._conn = conn
+        self._backend = backend
+
+    async def upload(
+        self,
+        *,
+        bucket: str,
+        path: str,
+        data: AsyncIterator[bytes],
+        content_type: str | None = None,
+    ) -> ObjectResponse:
+        return await storage_service.upload_object(
+            self._conn,
+            self._backend,
+            bucket_name=bucket,
+            path=path,
+            data=data,
+            content_type=content_type,
+        )
+
+    async def download(
+        self,
+        *,
+        bucket: str,
+        path: str,
+        byte_range: tuple[int, int | None] | None = None,
+    ):
+        return await storage_service.download_object(
+            self._conn,
+            self._backend,
+            bucket_name=bucket,
+            path=path,
+            byte_range=byte_range,
+        )
+
+    async def delete(self, *, bucket: str, path: str) -> None:
+        await storage_service.delete_object(
+            self._conn,
+            self._backend,
+            bucket_name=bucket,
+            path=path,
+        )
+
+    async def get_metadata(self, *, bucket: str, path: str) -> ObjectResponse:
+        return await storage_service.get_object_metadata(
+            self._conn, bucket, path
+        )
+
+    async def sign(
+        self, *, bucket: str, path: str, expires_in: int | None = None
+    ) -> SignedUrlResponse:
+        return await storage_service.issue_signed_url(
+            self._conn,
+            bucket_name=bucket,
+            path=path,
+            expires_in=expires_in,
+        )
+
+
+# ---------------------------------------------------------------------------
+# PostgREST forwarding client
+# ---------------------------------------------------------------------------
+
+
+class PostgrestClient:
+    """Request-scoped ``httpx.AsyncClient`` aimed at the configured PostgREST.
+
+    When the caller is authenticated, the bearer token is forwarded so the
+    upstream RLS verdict matches whatever ``ctx.db`` would see. For anon
+    callers no ``Authorization`` header is sent, which lets PostgREST resolve
+    the request to its ``anon`` role.
+
+    The dispatcher constructs one of these per request and ``aclose()``s it
+    in a ``finally`` block; user code should treat it like a borrowed handle.
+    """
+
+    def __init__(self, base_url: str, jwt: str | None) -> None:
+        headers: dict[str, str] = {}
+        if jwt:
+            headers["Authorization"] = f"Bearer {jwt}"
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+        )
+
+    async def get(self, url: str, **kw: Any) -> httpx.Response:
+        return await self._client.get(url, **kw)
+
+    async def post(self, url: str, **kw: Any) -> httpx.Response:
+        return await self._client.post(url, **kw)
+
+    async def patch(self, url: str, **kw: Any) -> httpx.Response:
+        return await self._client.patch(url, **kw)
+
+    async def put(self, url: str, **kw: Any) -> httpx.Response:
+        return await self._client.put(url, **kw)
+
+    async def delete(self, url: str, **kw: Any) -> httpx.Response:
+        return await self._client.delete(url, **kw)
+
+    async def request(self, method: str, url: str, **kw: Any) -> httpx.Response:
+        return await self._client.request(method, url, **kw)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+
+# ---------------------------------------------------------------------------
+# send_email kwargs wrapper
+# ---------------------------------------------------------------------------
+
+
+def _make_send_email(
+    backend: EmailBackend,
+) -> Callable[..., Awaitable[None]]:
+    """Adapt ``backend.send(EmailMessage)`` to the kwargs form handlers want.
+
+    ``await ctx.send_email(to="x@y", subject="Hi", text="...", html=None)``
+    is the documented surface; ``to`` may be a single address or a list.
+    """
+
+    async def send_email(
+        *,
+        to: str | list[str],
+        subject: str,
+        text: str,
+        html: str | None = None,
+    ) -> None:
+        recipients = [to] if isinstance(to, str) else list(to)
+        msg = EmailMessage(to=recipients, subject=subject, text=text, html=html)
+        await backend.send(msg)
+
+    return send_email
+
+
+# ---------------------------------------------------------------------------
+# Ctx
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Ctx:
+    """The ``ctx`` argument every user handler receives.
+
+    Lifetime: one HTTP request. ``db`` is a live, role-scoped connection
+    already inside ``db.as_role(...)`` — handlers can call
+    ``await ctx.db.fetchrow(...)`` directly. ``postgrest`` is closed by the
+    dispatcher in ``finally``; everything else is plain references.
+    """
+
+    db: asyncpg.Connection
+    user: FunctionUser | None
+    storage: StorageClient
+    postgrest: PostgrestClient
+    send_email: Callable[..., Awaitable[None]]
+    request: Request
+    settings: Settings
+
+
+def build_ctx(
+    *,
+    conn: asyncpg.Connection,
+    user: FunctionUser | None,
+    request: Request,
+    raw_jwt: str | None,
+    backend: StorageBackend | None = None,
+    mailer: EmailBackend | None = None,
+    settings: Settings | None = None,
+) -> Ctx:
+    """Assemble a ``Ctx`` for one request.
+
+    Kept as a free function so tests can construct a ``Ctx`` directly with
+    fakes for ``backend`` / ``mailer`` without going through the dispatcher.
+    """
+    s = settings or get_settings()
+    return Ctx(
+        db=conn,
+        user=user,
+        storage=StorageClient(conn, backend or get_backend()),
+        postgrest=PostgrestClient(s.postgrest_url, raw_jwt),
+        send_email=_make_send_email(mailer or get_mailer()),
+        request=request,
+        settings=s,
+    )

supython/functions/loader.py

@@ -0,0 +1,307 @@
+"""Discovery + hot-reload of user functions on disk.
+
+Walks ``settings.functions_dir`` and turns every valid ``*.py`` into a
+:class:`~.schemas.FunctionMeta` keyed by its route name (the relative path
+minus the ``.py`` suffix).
+
+Naming rules per path segment: ``[a-z0-9][a-z0-9_-]*``. Anything starting
+with ``_`` (e.g. ``__init__.py``, ``_helpers.py``) and ``__pycache__`` are
+ignored — handlers don't need to be importable as a package, only walkable
+as files.
+
+Each module imported under a synthetic ``supython._functions.<dotted>``
+package via ``importlib.util.spec_from_file_location`` so user code does not
+need to be on ``sys.path``. In hot-reload mode every ``get(name)`` ``stat()``s
+the file and ``importlib.reload()``s if the mtime moved — no watcher
+threads, deterministic in tests.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import inspect
+import logging
+import re
+import sys
+import time
+from collections.abc import Iterable
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from .schemas import ALLOWED_METHODS, AuthMode, FunctionMeta
+
+logger = logging.getLogger(__name__)
+
+
+_SEGMENT_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+_SYNTHETIC_PKG = "supython._functions"
+# How often a hot-reload `get()` may rescan the tree for *new* files.
+_RESCAN_DEBOUNCE_S = 1.0
+
+
+class FunctionLoadError(Exception):
+    """Raised at startup (when hot reload is off) for a malformed module."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _ensure_synthetic_pkg() -> None:
+    """Make ``supython._functions`` resolvable without it existing on disk."""
+    if _SYNTHETIC_PKG in sys.modules:
+        return
+    spec = importlib.util.spec_from_loader(_SYNTHETIC_PKG, loader=None)
+    pkg = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]
+    pkg.__path__ = []  # marks it as a package
+    sys.modules[_SYNTHETIC_PKG] = pkg
+
+
+def _route_name_for(root: Path, file: Path) -> str | None:
+    """Return the route name for ``file`` under ``root``, or None if invalid."""
+    rel = file.relative_to(root).with_suffix("")
+    parts = rel.parts
+    if not parts:
+        return None
+    for seg in parts:
+        if seg.startswith("_") or seg == "__pycache__":
+            return None
+        if not _SEGMENT_RE.match(seg):
+            return None
+    return "/".join(parts)
+
+
+def _module_name_for(name: str) -> str:
+    safe = name.replace("/", ".").replace("-", "_")
+    return f"{_SYNTHETIC_PKG}.{safe}"
+
+
+def _validate_module(mod: ModuleType, file: Path) -> tuple[list[str], AuthMode]:
+    handler = getattr(mod, "handler", None)
+    if handler is None or not inspect.iscoroutinefunction(handler):
+        raise FunctionLoadError(
+            f"{file}: must define `async def handler(req, ctx)`"
+        )
+
+    raw_methods: Any = getattr(mod, "methods", None)
+    methods: list[str]
+    if raw_methods is None:
+        methods = ["POST"]
+    else:
+        if not isinstance(raw_methods, Iterable) or isinstance(raw_methods, (str, bytes)):
+            raise FunctionLoadError(
+                f"{file}: `methods` must be a list of HTTP verbs"
+            )
+        upper = [str(m).upper() for m in raw_methods]
+        unknown = [m for m in upper if m not in ALLOWED_METHODS]
+        if unknown:
+            raise FunctionLoadError(
+                f"{file}: unsupported method(s) in `methods`: {unknown}"
+            )
+        if not upper:
+            raise FunctionLoadError(f"{file}: `methods` must not be empty")
+        methods = upper
+
+    raw_auth: Any = getattr(mod, "auth", "authenticated")
+    if raw_auth not in ("authenticated", "anon"):
+        raise FunctionLoadError(
+            f"{file}: `auth` must be 'authenticated' or 'anon', got {raw_auth!r}"
+        )
+
+    return methods, raw_auth  # type: ignore[return-value]
+
+
+def _import_file(module_name: str, file: Path) -> ModuleType:
+    spec = importlib.util.spec_from_file_location(module_name, file)
+    if spec is None or spec.loader is None:
+        raise FunctionLoadError(f"{file}: could not build import spec")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except BaseException:
+        sys.modules.pop(module_name, None)
+        raise
+    return module
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+
+class FunctionRegistry:
+    """In-process registry of discovered functions.
+
+    Construct once per app (the ``db.lifespan`` extension calls ``discover``
+    after ``init_pool``). In hot-reload mode ``get`` is the per-request entry
+    point; otherwise the snapshot taken at ``discover`` time is final.
+    """
+
+    def __init__(self, root: Path, *, hot_reload: bool = True) -> None:
+        self._root = Path(root)
+        self._hot_reload = hot_reload
+        self._metas: dict[str, FunctionMeta] = {}
+        self._last_rescan: float = 0.0
+
+    # ------------------------------------------------------------------ public
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    @property
+    def hot_reload(self) -> bool:
+        return self._hot_reload
+
+    def discover(self) -> None:
+        """Walk the tree once. Safe to call repeatedly; idempotent."""
+        _ensure_synthetic_pkg()
+        if not self._root.exists():
+            logger.info("functions: directory %s does not exist; skipping", self._root)
+            self._metas = {}
+            return
+
+        seen: set[str] = set()
+        for file in sorted(self._root.rglob("*.py")):
+            name = _route_name_for(self._root, file)
+            if name is None:
+                continue
+            seen.add(name)
+            self._load_or_skip(name, file)
+
+        # Drop entries whose files vanished between discoveries.
+        for stale in set(self._metas) - seen:
+            self._drop(stale)
+        self._last_rescan = time.monotonic()
+
+    def get(self, name: str) -> FunctionMeta | None:
+        """Return meta for ``name``, applying hot-reload if enabled.
+
+        Returns ``None`` if the function is not (or no longer) registered.
+        Validation errors during reload demote to None and log; this matches
+        dev ergonomics — a broken save shouldn't kill unrelated routes.
+        """
+        if self._hot_reload:
+            self._maybe_rescan_for_new_files()
+
+        meta = self._metas.get(name)
+        if meta is None:
+            return None
+
+        if not self._hot_reload:
+            return meta
+
+        try:
+            stat = meta.path.stat()
+        except FileNotFoundError:
+            self._drop(name)
+            return None
+
+        if stat.st_mtime > meta.mtime:
+            try:
+                self._reload(meta)
+            except FunctionLoadError as exc:
+                logger.warning("functions: reload failed for %s: %s", name, exc)
+                self._drop(name)
+                return None
+        return self._metas.get(name)
+
+    def list(self) -> list[FunctionMeta]:
+        return sorted(self._metas.values(), key=lambda m: m.name)
+
+    # ---------------------------------------------------------------- internal
+
+    def _maybe_rescan_for_new_files(self) -> None:
+        now = time.monotonic()
+        if now - self._last_rescan < _RESCAN_DEBOUNCE_S:
+            return
+        self._last_rescan = now
+        if not self._root.exists():
+            return
+        for file in self._root.rglob("*.py"):
+            name = _route_name_for(self._root, file)
+            if name is None or name in self._metas:
+                continue
+            self._load_or_skip(name, file)
+
+    def _load_or_skip(self, name: str, file: Path) -> None:
+        try:
+            self._load(name, file)
+        except FunctionLoadError as exc:
+            if self._hot_reload:
+                logger.warning("functions: skipping %s: %s", name, exc)
+                return
+            raise
+
+    def _load(self, name: str, file: Path) -> None:
+        module_name = _module_name_for(name)
+        # Drop any stale module entry so re-import from the file actually runs.
+        sys.modules.pop(module_name, None)
+        module = _import_file(module_name, file)
+        methods, auth = _validate_module(module, file)
+        self._metas[name] = FunctionMeta(
+            name=name,
+            path=file.resolve(),
+            module_name=module_name,
+            methods=methods,
+            auth=auth,
+            mtime=file.stat().st_mtime,
+            handler=module.handler,
+        )
+
+    def _reload(self, meta: FunctionMeta) -> None:
+        # importlib.reload() cannot locate modules under the synthetic package
+        # via _find_spec; always use the pop-then-reimport pattern instead.
+        sys.modules.pop(meta.module_name, None)
+        module = _import_file(meta.module_name, meta.path)
+        methods, auth = _validate_module(module, meta.path)
+        self._metas[meta.name] = FunctionMeta(
+            name=meta.name,
+            path=meta.path,
+            module_name=meta.module_name,
+            methods=methods,
+            auth=auth,
+            mtime=meta.path.stat().st_mtime,
+            handler=module.handler,
+        )
+
+    def _drop(self, name: str) -> None:
+        meta = self._metas.pop(name, None)
+        if meta is not None:
+            sys.modules.pop(meta.module_name, None)
+
+
+# ---------------------------------------------------------------------------
+# Process-wide singleton
+# ---------------------------------------------------------------------------
+
+
+_registry: FunctionRegistry | None = None
+
+
+def get_registry() -> FunctionRegistry:
+    """Return the process-wide registry (built lazily from settings)."""
+    from ..settings import get_settings
+
+    global _registry
+    if _registry is None:
+        s = get_settings()
+        _registry = FunctionRegistry(
+            Path(s.functions_dir),
+            hot_reload=s.functions_hot_reload,
+        )
+    return _registry
+
+
+def set_registry(registry: FunctionRegistry | None) -> None:
+    """Override the singleton (tests use this; lifespan calls with a fresh one)."""
+    global _registry
+    _registry = registry
+
+
+def reset_registry() -> None:
+    set_registry(None)