supython 0.1.0__py3-none-any.whl

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"]

supython/gen/_introspect.py

@@ -0,0 +1,137 @@
+"""Shared Postgres schema introspection queries used by type generators.
+
+Both ``types_py.py`` (Python dataclasses) and ``types_ts.py`` (TypeScript
+``Database`` interface) use these functions to fetch metadata from
+``information_schema`` and ``pg_catalog``.
+"""
+
+import asyncpg
+
+
+async def _fetch_enums(
+    conn: asyncpg.Connection, schemas: list[str]
+) -> dict[tuple[str, str], list[str]]:
+    rows = await conn.fetch(
+        """
+        select n.nspname  as schema,
+               t.typname  as name,
+               e.enumlabel as label
+        from pg_type t
+        join pg_enum e       on e.enumtypid = t.oid
+        join pg_namespace n  on n.oid = t.typnamespace
+        where n.nspname = any($1::text[])
+        order by n.nspname, t.typname, e.enumsortorder
+        """,
+        list(schemas),
+    )
+    out: dict[tuple[str, str], list[str]] = {}
+    for r in rows:
+        out.setdefault((r["schema"], r["name"]), []).append(r["label"])
+    return out
+
+
+async def _fetch_tables(
+    conn: asyncpg.Connection, schemas: list[str]
+) -> list[tuple[str, str]]:
+    rows = await conn.fetch(
+        """
+        select table_schema, table_name
+        from information_schema.tables
+        where table_schema = any($1::text[])
+          and table_type in ('BASE TABLE', 'VIEW')
+        order by table_schema, table_name
+        """,
+        list(schemas),
+    )
+    return [(r["table_schema"], r["table_name"]) for r in rows]
+
+
+async def _fetch_columns(
+    conn: asyncpg.Connection, schemas: list[str]
+) -> dict[tuple[str, str], list[asyncpg.Record]]:
+    rows = await conn.fetch(
+        """
+        select c.table_schema,
+               c.table_name,
+               c.column_name,
+               c.ordinal_position,
+               c.is_nullable,
+               c.data_type,
+               c.udt_schema,
+               c.udt_name,
+               c.column_default,
+               c.is_generated,
+               c.is_identity,
+               e.data_type   as element_data_type,
+               e.udt_schema  as element_udt_schema,
+               e.udt_name    as element_udt_name
+        from information_schema.columns c
+        join information_schema.tables t
+          on t.table_catalog = c.table_catalog
+         and t.table_schema  = c.table_schema
+         and t.table_name    = c.table_name
+        left join information_schema.element_types e
+          on  e.object_catalog            = c.table_catalog
+          and e.object_schema             = c.table_schema
+          and e.object_name               = c.table_name
+          and e.object_type               = case t.table_type
+                                                when 'VIEW' then 'VIEW'
+                                                else 'TABLE'
+                                            end
+          and e.collection_type_identifier = c.dtd_identifier
+        where c.table_schema = any($1::text[])
+          and t.table_type in ('BASE TABLE', 'VIEW')
+        order by c.table_schema, c.table_name, c.ordinal_position
+        """,
+        list(schemas),
+    )
+    grouped: dict[tuple[str, str], list[asyncpg.Record]] = {}
+    for r in rows:
+        grouped.setdefault((r["table_schema"], r["table_name"]), []).append(r)
+    return grouped
+
+
+async def _fetch_relationships(
+    conn: asyncpg.Connection, schemas: list[str]
+) -> dict[tuple[str, str], list[dict[str, any]]]:  # type: ignore[no-any-return]
+    rows = await conn.fetch(
+        """
+        select
+            n.nspname as table_schema,
+            c.relname as table_name,
+            con.conname as constraint_name,
+            (
+                select array_agg(a.attname order by ord)
+                from unnest(con.conkey) with ordinality as t(attnum, ord)
+                join pg_attribute a
+                    on a.attnum = t.attnum and a.attrelid = con.conrelid
+            ) as columns,
+            ref_c.relname as foreign_table_name,
+            (
+                select array_agg(a.attname order by ord)
+                from unnest(con.confkey) with ordinality as t(attnum, ord)
+                join pg_attribute a
+                    on a.attnum = t.attnum and a.attrelid = con.confrelid
+            ) as foreign_columns
+        from pg_constraint con
+        join pg_class c on c.oid = con.conrelid
+        join pg_namespace n on n.oid = c.relnamespace
+        join pg_class ref_c on ref_c.oid = con.confrelid
+        where con.contype = 'f'
+          and n.nspname = any($1::text[])
+        order by n.nspname, c.relname, con.conname
+        """,
+        list(schemas),
+    )
+    out: dict[tuple[str, str], list[dict[str, any]]] = {}  # type: ignore[no-any-return]
+    for r in rows:
+        key = (r["table_schema"], r["table_name"])
+        out.setdefault(key, []).append(
+            {
+                "foreignKeyName": r["constraint_name"],
+                "columns": r["columns"],
+                "referencedRelation": r["foreign_table_name"],
+                "referencedColumns": r["foreign_columns"],
+            }
+        )
+    return out

supython/gen/types_py.py

@@ -0,0 +1,270 @@
+"""Render a typed ``types.py`` from Postgres schema introspection.
+
+Public entry point: :func:`render_types_py`. The returned string is the full
+contents of a self-contained Python module with one ``StrEnum`` per Postgres
+enum and one ``@dataclass`` + matching ``TypedDict`` per table or view in the
+selected schemas.
+
+The generator opens its own asyncpg connection and closes it before returning;
+it does not depend on the supython service running.
+"""
+
+import keyword
+import re
+from datetime import UTC, datetime
+
+import asyncpg
+
+from ..settings import get_settings
+from ._introspect import _fetch_columns, _fetch_enums, _fetch_tables
+
+_SIMPLE_MAP: dict[str, tuple[str, str | None]] = {
+    "text": ("str", None),
+    "varchar": ("str", None),
+    "bpchar": ("str", None),
+    "char": ("str", None),
+    "citext": ("str", None),
+    "name": ("str", None),
+    "int2": ("int", None),
+    "int4": ("int", None),
+    "int8": ("int", None),
+    "float4": ("float", None),
+    "float8": ("float", None),
+    "numeric": ("Decimal", "Decimal"),
+    "money": ("Decimal", "Decimal"),
+    "bool": ("bool", None),
+    "uuid": ("UUID", "UUID"),
+    "timestamptz": ("datetime", "datetime"),
+    "timestamp": ("datetime", "datetime"),
+    "date": ("date", "date"),
+    "time": ("time", "time"),
+    "timetz": ("time", "time"),
+    "interval": ("timedelta", "timedelta"),
+    "bytea": ("bytes", None),
+    "json": ("dict[str, Any]", "Any"),
+    "jsonb": ("dict[str, Any]", "Any"),
+    "inet": ("str", None),
+    "cidr": ("str", None),
+    "macaddr": ("str", None),
+    "tsvector": ("str", None),
+    "tsquery": ("str", None),
+    "bit": ("str", None),
+    "varbit": ("str", None),
+    "oid": ("int", None),
+}
+
+
+def _safe_col_name(name: str) -> str:
+    if keyword.iskeyword(name) or keyword.issoftkeyword(name):
+        return f"{name}_"
+    return name
+
+
+async def render_types_py(schemas: list[str]) -> str:
+    """Connect to ``DATABASE_URL`` and return a rendered ``types.py`` module."""
+    s = get_settings()
+    conn = await asyncpg.connect(s.database_url)
+    try:
+        enums = await _fetch_enums(conn, schemas)
+        tables = await _fetch_tables(conn, schemas)
+        columns = await _fetch_columns(conn, schemas)
+    finally:
+        await conn.close()
+    return _render(schemas, enums, tables, columns)
+
+
+
+def _class_name(schema: str, table: str, schemas: list[str]) -> str:
+    base = "".join(part.capitalize() for part in re.split(r"[_\-]", table) if part)
+    if not base:
+        base = "Table"
+    if schema == "public" or len(schemas) == 1:
+        return base
+    return f"{schema.capitalize()}{base}"
+
+
+def _safe_enum_attr(label: str) -> str:
+    s = re.sub(r"[^A-Za-z0-9_]", "_", label).upper()
+    if not s or s[0].isdigit():
+        s = "_" + s
+    return s
+
+
+def _pg_to_py(
+    udt_schema: str,
+    udt_name: str,
+    data_type: str,
+    element: tuple[str, str, str] | None,
+    enum_classes: dict[tuple[str, str], str],
+    imports: set[str],
+) -> tuple[str, str | None]:
+    """Return (annotation, unmapped_comment_or_None)."""
+    if data_type == "ARRAY" and element is not None:
+        elem_ann, elem_unmapped = _pg_to_py(
+            element[1], element[2], element[0], None, enum_classes, imports
+        )
+        return f"list[{elem_ann}]", elem_unmapped
+
+    if data_type == "USER-DEFINED" and (udt_schema, udt_name) in enum_classes:
+        return enum_classes[(udt_schema, udt_name)], None
+
+    if udt_name in _SIMPLE_MAP:
+        ann, imp = _SIMPLE_MAP[udt_name]
+        if imp:
+            imports.add(imp)
+        return ann, None
+
+    imports.add("Any")
+    return "Any", f"unmapped: {udt_schema}.{udt_name}"
+
+
+def _render(
+    schemas: list[str],
+    enums: dict[tuple[str, str], list[str]],
+    tables: list[tuple[str, str]],
+    columns: dict[tuple[str, str], list[asyncpg.Record]],
+) -> str:
+    imports: set[str] = set()
+
+    enum_classes: dict[tuple[str, str], str] = {
+        (schema, name): _class_name(schema, name, schemas)
+        for (schema, name) in enums
+    }
+
+    body: list[str] = []
+
+    for (schema, name), labels in sorted(enums.items()):
+        cls = enum_classes[(schema, name)]
+        body.append("")
+        body.append(f"# --- enum {schema}.{name} {'-' * (60 - len(schema) - len(name))}")
+        body.append("")
+        body.append(f"class {cls}(StrEnum):")
+        for lbl in labels:
+            body.append(f"    {_safe_enum_attr(lbl)} = {lbl!r}")
+
+    has_table = False
+    for schema, table in tables:
+        cols = columns.get((schema, table), [])
+        if not cols:
+            continue
+        has_table = True
+        cls = _class_name(schema, table, schemas)
+
+        rendered_cols: list[tuple[str, str, bool, str | None]] = []
+        for c in cols:
+            element = None
+            if c["element_data_type"]:
+                element = (
+                    c["element_data_type"],
+                    c["element_udt_schema"],
+                    c["element_udt_name"],
+                )
+            ann, unmapped = _pg_to_py(
+                c["udt_schema"],
+                c["udt_name"],
+                c["data_type"],
+                element,
+                enum_classes,
+                imports,
+            )
+            nullable = c["is_nullable"] == "YES"
+            col_name = _safe_col_name(c["column_name"])
+            rendered_cols.append((col_name, ann, nullable, unmapped))
+
+        body.append("")
+        body.append(f"# --- {schema}.{table} {'-' * (64 - len(schema) - len(table))}")
+        body.append("")
+        body.append("@dataclass(kw_only=True, slots=True)")
+        body.append(f"class {cls}:")
+        for col_name, ann, nullable, unmapped in rendered_cols:
+            line = (
+                f"    {col_name}: {ann} | None = None"
+                if nullable
+                else f"    {col_name}: {ann}"
+            )
+            if unmapped:
+                line += f"  # {unmapped}"
+            body.append(line)
+
+        body.append("")
+        body.append("    @classmethod")
+        body.append(f'    def from_record(cls, record: "object") -> "{cls}":')
+        body.append("        fields = cls.__dataclass_fields__")
+        body.append(
+            "        return cls(**{f: v for f, v in record.items() if f in fields})"
+        )
+
+        has_kw = any(
+            _safe_col_name(c["column_name"]) != c["column_name"]
+            for c in cols
+        )
+        if has_kw:
+            _emit_typeddict_functional(body, cls, rendered_cols)
+        else:
+            _emit_typeddict_class(body, cls, rendered_cols)
+
+    header: list[str] = []
+    header.append('"""Generated by `supython gen types --lang py`. Do not edit.')
+    header.append("")
+    header.append(f"Schemas: {', '.join(schemas)}")
+    header.append(f"Generated at: {datetime.now(UTC).isoformat()}")
+    header.append('"""')
+
+    import_lines: list[str] = []
+    if has_table:
+        import_lines.append("from dataclasses import dataclass")
+
+    datetime_syms = sorted(
+        {i for i in imports if i in {"datetime", "date", "time", "timedelta"}}
+    )
+    if datetime_syms:
+        import_lines.append(f"from datetime import {', '.join(datetime_syms)}")
+    if "Decimal" in imports:
+        import_lines.append("from decimal import Decimal")
+    if enums:
+        import_lines.append("from enum import StrEnum")
+    typing_syms: set[str] = set()
+    if "Any" in imports:
+        typing_syms.add("Any")
+    if has_table:
+        typing_syms.add("TypedDict")
+    if typing_syms:
+        import_lines.append(f"from typing import {', '.join(sorted(typing_syms))}")
+    if "UUID" in imports:
+        import_lines.append("from uuid import UUID")
+
+    parts: list[str] = []
+    parts.extend(header)
+    if import_lines:
+        parts.append("")
+        parts.extend(import_lines)
+    parts.extend(body)
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def _emit_typeddict_class(
+    body: list[str],
+    cls: str,
+    rendered_cols: list[tuple[str, str, bool, str | None]],
+) -> None:
+    body.append("")
+    body.append(f"class {cls}Row(TypedDict):")
+    for col_name, ann, nullable, _ in rendered_cols:
+        body.append(
+            f"    {col_name}: {ann} | None" if nullable else f"    {col_name}: {ann}"
+        )
+
+
+def _emit_typeddict_functional(
+    body: list[str],
+    cls: str,
+    rendered_cols: list[tuple[str, str, bool, str | None]],
+) -> None:
+    body.append(f"{cls}Row = TypedDict(\"{cls}Row\", {{")
+    for col_name, ann, nullable, _ in rendered_cols:
+        ann_str = f"{ann} | None" if nullable else ann
+        body.append(f'    "{col_name}": {ann_str},')
+    body.append("})")
+
+
+__all__ = ["render_types_py"]