supython 0.5.0__py3-none-any.whl

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)

supython/functions/router.py

@@ -0,0 +1,228 @@
+"""HTTP dispatcher for filesystem-loaded functions.
+
+Single ``/functions/{name:path}`` route that:
+
+1. Looks the function up in the registry (mtime-checked when hot reload is on).
+2. Enforces ``methods`` and ``auth`` declared by the module.
+3. Body-size guards via ``settings.functions_max_body_bytes`` (the cap is on
+   what the dispatcher will eagerly buffer; handlers can still consume
+   ``request.stream()`` directly for true streaming uploads).
+4. Builds a :class:`~.context.Ctx` against a role-scoped connection from
+   ``db.as_role`` and invokes the handler.
+5. Translates the return value into a FastAPI response.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+import jwt
+from fastapi import APIRouter, HTTPException, Request, Response, status
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from .. import db, tokens
+from ..settings import get_settings
+from ..storage import service as storage_service
+from .context import FunctionUser, build_ctx
+from .loader import get_registry
+from .schemas import (
+    ERR_BODY_TOO_LARGE,
+    ERR_FUNCTION_ERROR,
+    ERR_FUNCTION_TIMEOUT,
+    ERR_INVALID_RETURN,
+    ERR_INVALID_TOKEN,
+    ERR_METHOD_NOT_ALLOWED,
+    ERR_NOT_FOUND,
+    FunctionMeta,
+)
+
+logger = logging.getLogger(__name__)
+
+
+router = APIRouter(prefix="/functions", tags=["functions"])
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _err(status_code: int, code: str, message: str) -> HTTPException:
+    return HTTPException(
+        status_code=status_code,
+        detail={"code": code, "message": message},
+    )
+
+
+def _extract_bearer(request: Request) -> str | None:
+    auth = request.headers.get("authorization")
+    if not auth or not auth.lower().startswith("bearer "):
+        return None
+    return auth.split(" ", 1)[1].strip() or None
+
+
+def _decode_or_none(raw: str | None) -> dict[str, Any] | None:
+    if raw is None:
+        return None
+    try:
+        return tokens.decode_access_token(raw)
+    except jwt.PyJWTError:
+        return None
+
+
+def _enforce_body_limit(request: Request, max_bytes: int) -> None:
+    cl = request.headers.get("content-length")
+    if cl is None:
+        return
+    try:
+        n = int(cl)
+    except ValueError:
+        return
+    if n > max_bytes:
+        raise _err(
+            status.HTTP_413_CONTENT_TOO_LARGE,
+            ERR_BODY_TOO_LARGE,
+            f"Body exceeds {max_bytes} bytes",
+        )
+
+
+def _translate(result: Any) -> Response:
+    """Map handler returns to a Response. Order matters — Response first."""
+    if isinstance(result, Response):
+        return result
+    if isinstance(result, tuple) and len(result) == 2 and isinstance(result[0], int):
+        status_code, payload = result
+        inner = _translate(payload)
+        inner.status_code = status_code
+        return inner
+    if isinstance(result, BaseModel):
+        return JSONResponse(content=result.model_dump(mode="json"))
+    if isinstance(result, (dict, list)) or result is None:
+        return JSONResponse(content=result)
+    if isinstance(result, (str, int, bool)):
+        return JSONResponse(content=result)
+    if isinstance(result, bytes):
+        return Response(content=result, media_type="application/octet-stream")
+    raise _err(
+        status.HTTP_500_INTERNAL_SERVER_ERROR,
+        ERR_INVALID_RETURN,
+        f"Handler returned unsupported type {type(result).__name__!r}",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Dispatcher
+# ---------------------------------------------------------------------------
+
+
+@router.api_route(
+    "/{name:path}",
+    methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+)
+async def dispatch(name: str, request: Request) -> Response:
+    meta = get_registry().get(name)
+    if meta is None:
+        raise _err(status.HTTP_404_NOT_FOUND, ERR_NOT_FOUND, name)
+    if request.method not in meta.methods:
+        raise _err(
+            status.HTTP_405_METHOD_NOT_ALLOWED,
+            ERR_METHOD_NOT_ALLOWED,
+            request.method,
+        )
+    return await _invoke(meta, request)
+
+
+async def _invoke(meta: FunctionMeta, request: Request) -> Response:
+    settings = get_settings()
+    _enforce_body_limit(request, settings.functions_max_body_bytes)
+
+    raw_jwt = _extract_bearer(request)
+    claims = _decode_or_none(raw_jwt)
+
+    if meta.auth == "authenticated" and (raw_jwt is None or claims is None):
+        raise _err(
+            status.HTTP_401_UNAUTHORIZED,
+            ERR_INVALID_TOKEN,
+            "Missing or invalid bearer token",
+        )
+
+    if claims is not None:
+        allowed = settings.db_allowed_roles
+        role = claims.get("role") if isinstance(claims.get("role"), str) else "anon"
+
+        if role not in allowed:
+            raise _err(
+                status.HTTP_401_UNAUTHORIZED,
+                ERR_INVALID_TOKEN,
+                f"Invalid role: {role!r}",
+            )
+        user: FunctionUser | None = FunctionUser.from_claims(claims)
+        ctx_claims = claims
+    else:
+        role = "anon"
+        user = None
+        ctx_claims = {"role": "anon"}
+
+    handler = meta.handler
+    assert handler is not None  # validated at load time
+
+    try:
+        async with db.as_role(role, ctx_claims) as conn:
+            ctx = build_ctx(
+                conn=conn,
+                user=user,
+                request=request,
+                raw_jwt=raw_jwt if meta.auth == "authenticated" or raw_jwt else None,
+                settings=settings,
+            )
+            try:
+                # wait_for wraps only the handler so a timeout cancels user
+                # code while still letting `as_role`'s transaction roll back
+                # cleanly on the way out.
+                result = await asyncio.wait_for(
+                    handler(request, ctx),
+                    timeout=settings.functions_max_handler_seconds,
+                )
+            finally:
+                try:
+                    await ctx.postgrest.aclose()
+                except Exception:
+                    logger.warning("functions: postgrest close failed for %s", meta.name, exc_info=True)
+    except HTTPException:
+        raise
+    except storage_service.StorageError as exc:
+        raise HTTPException(
+            status_code=exc.status,
+            detail={"code": exc.code, "message": exc.message},
+        ) from exc
+    except TimeoutError:
+        logger.warning(
+            "functions: handler %s exceeded %.2fs timeout",
+            meta.name,
+            settings.functions_max_handler_seconds,
+        )
+        raise _err(
+            status.HTTP_504_GATEWAY_TIMEOUT,
+            ERR_FUNCTION_TIMEOUT,
+            f"Function exceeded {settings.functions_max_handler_seconds}s",
+        ) from None
+    except (KeyboardInterrupt, SystemExit):
+        # Lifecycle signals must reach the server, never become a 500.
+        raise
+    except asyncio.CancelledError:
+        # Real client-disconnect / shutdown cancellation. wait_for converts
+        # its internal cancellation to TimeoutError above, so this branch
+        # only fires for cancellations originating outside the dispatcher.
+        raise
+    except Exception:
+        logger.warning("functions: handler %s raised", meta.name, exc_info=True)
+        raise _err(
+            status.HTTP_500_INTERNAL_SERVER_ERROR,
+            ERR_FUNCTION_ERROR,
+            "Function raised an unhandled exception",
+        ) from None
+
+    return _translate(result)

supython/functions/schemas.py

@@ -0,0 +1,50 @@
+"""Shared types for the functions subsystem.
+
+Kept dependency-free so the loader and the dispatcher can both import from
+here without cycling through ``context.py`` (which pulls in storage/mailer).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:  # pragma: no cover - only for type checking
+    from fastapi import Request
+
+    from .context import Ctx
+
+
+HandlerFn = Callable[["Request", "Ctx"], Awaitable[Any]]
+
+AuthMode = Literal["authenticated", "anon"]
+
+ALLOWED_METHODS: frozenset[str] = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})
+
+
+@dataclass
+class FunctionMeta:
+    """Everything the dispatcher needs to invoke one user function."""
+
+    name: str  # route name, e.g. "payments/webhook"
+    path: Path  # absolute file path on disk
+    module_name: str  # synthetic dotted name under supython._functions
+    methods: list[str] = field(default_factory=lambda: ["POST"])
+    auth: AuthMode = "authenticated"
+    mtime: float = 0.0
+    handler: HandlerFn | None = None
+
+
+# ---------------------------------------------------------------------------
+# Error codes used by the dispatcher (kept here so tests can import them).
+# ---------------------------------------------------------------------------
+
+ERR_NOT_FOUND = "function_not_found"
+ERR_METHOD_NOT_ALLOWED = "method_not_allowed"
+ERR_BODY_TOO_LARGE = "body_too_large"
+ERR_INVALID_TOKEN = "invalid_token"
+ERR_INVALID_RETURN = "invalid_function_return"
+ERR_FUNCTION_ERROR = "function_error"
+ERR_FUNCTION_TIMEOUT = "function_timeout"

supython/gen/__init__.py

@@ -0,0 +1,5 @@
+"""Code generation for `supython gen`."""
+from .types_py import render_types_py
+from .types_ts import render_types_ts
+
+__all__ = ["render_types_py", "render_types_ts"]