supython 0.5.0__py3-none-any.whl

supython/client/_storage.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ._auth import SupythonResponse
+from ._config import _parse_error_detail
+
+
+@dataclass
+class StorageError:
+    code: str
+    message: str
+    status: int
+
+
+@dataclass
+class BucketResponse:
+    id: str
+    name: str
+    owner: str | None
+    public: bool
+    file_size_limit: int | None
+    allowed_mime_types: list[str] | None
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class ObjectResponse:
+    id: str
+    bucket_id: str
+    bucket: str
+    name: str
+    owner: str
+    size: int
+    mime_type: str | None
+    etag: str | None
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class SignedUrlResponse:
+    signed_url: str
+    token: str
+    expires_at: str
+    expires_in: int
+
+
+def _make_storage_error(resp: httpx.Response) -> StorageError:
+    try:
+        body = resp.json()
+    except Exception:
+        msg = resp.text or f"HTTP {resp.status_code}"
+        return StorageError("network_error", msg, resp.status_code)
+    code, message = _parse_error_detail(body)
+    return StorageError(code, message, resp.status_code)
+
+
+def _parse_bucket(body: dict[str, Any]) -> BucketResponse:
+    return BucketResponse(
+        id=str(body["id"]),
+        name=body["name"],
+        owner=str(body["owner"]) if body.get("owner") else None,
+        public=body["public"],
+        file_size_limit=body.get("file_size_limit"),
+        allowed_mime_types=body.get("allowed_mime_types"),
+        created_at=body["created_at"],
+        updated_at=body["updated_at"],
+    )
+
+
+def _parse_object(body: dict[str, Any]) -> ObjectResponse:
+    return ObjectResponse(
+        id=str(body["id"]),
+        bucket_id=str(body["bucket_id"]),
+        bucket=body["bucket"],
+        name=body["name"],
+        owner=str(body["owner"]),
+        size=body["size"],
+        mime_type=body.get("mime_type"),
+        etag=body.get("etag"),
+        created_at=body["created_at"],
+        updated_at=body["updated_at"],
+    )
+
+
+class StorageBucket:
+    def __init__(self, client: StorageClient, bucket_name: str) -> None:
+        self._client = client
+        self._bucket_name = bucket_name
+
+    def _headers(self) -> dict[str, str]:
+        return self._client._headers()
+
+    async def upload(
+        self,
+        path: str,
+        data: bytes,
+        *,
+        content_type: str | None = None,
+    ) -> SupythonResponse[ObjectResponse]:
+        url = f"{self._client._url}/object/{self._bucket_name}/{path}"
+        files = {"file": (path, data, content_type or "application/octet-stream")}
+        try:
+            resp = await self._client._http.post(
+                url, files=files, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        return SupythonResponse(data=_parse_object(resp.json()))
+
+    async def download(self, path: str) -> SupythonResponse[bytes]:
+        url = f"{self._client._url}/object/{self._bucket_name}/{path}"
+        try:
+            resp = await self._client._http.get(url, headers=self._headers())
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        return SupythonResponse(data=resp.content)
+
+    async def remove(self, path: str) -> SupythonResponse[None]:
+        url = f"{self._client._url}/object/{self._bucket_name}/{path}"
+        try:
+            resp = await self._client._http.delete(url, headers=self._headers())
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        return SupythonResponse(data=None)
+
+    async def create_signed_url(
+        self, path: str, *, expires_in: int | None = None
+    ) -> SupythonResponse[SignedUrlResponse]:
+        url = f"{self._client._url}/object/sign/{self._bucket_name}/{path}"
+        body: dict[str, Any] = {}
+        if expires_in is not None:
+            body["expires_in"] = expires_in
+        try:
+            resp = await self._client._http.post(
+                url, json=body or None, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        data = resp.json()
+        return SupythonResponse(
+            data=SignedUrlResponse(
+                signed_url=data["signed_url"],
+                token=data["token"],
+                expires_at=data["expires_at"],
+                expires_in=data["expires_in"],
+            )
+        )
+
+    def get_public_url(self, path: str) -> str:
+        return f"{self._client._url}/object/public/{self._bucket_name}/{path}"
+
+
+class StorageClient:
+    def __init__(self, base_url: str, anon_key: str, client: Any) -> None:
+        self._url = base_url
+        self._anon_key = anon_key
+        self._client = client
+        self._http = httpx.AsyncClient()
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self._anon_key:
+            headers["apikey"] = self._anon_key
+        access_token = self._client._access_token
+        if access_token:
+            headers["Authorization"] = f"Bearer {access_token}"
+        return headers
+
+    def from_(self, bucket_name: str) -> StorageBucket:
+        return StorageBucket(self, bucket_name)
+
+    async def create_bucket(
+        self,
+        *,
+        name: str,
+        public: bool = False,
+        file_size_limit: int | None = None,
+        allowed_mime_types: list[str] | None = None,
+    ) -> SupythonResponse[BucketResponse]:
+        body: dict[str, Any] = {"name": name, "public": public}
+        if file_size_limit is not None:
+            body["file_size_limit"] = file_size_limit
+        if allowed_mime_types is not None:
+            body["allowed_mime_types"] = allowed_mime_types
+
+        try:
+            resp = await self._http.post(
+                f"{self._url}/bucket", json=body, headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        return SupythonResponse(data=_parse_bucket(resp.json()))
+
+    async def list_buckets(self) -> SupythonResponse[list[BucketResponse]]:
+        try:
+            resp = await self._http.get(f"{self._url}/bucket", headers=self._headers())
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        return SupythonResponse(data=[_parse_bucket(b) for b in resp.json()])
+
+    async def get_bucket(self, name: str) -> SupythonResponse[BucketResponse]:
+        try:
+            resp = await self._http.get(
+                f"{self._url}/bucket/{name}", headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        return SupythonResponse(data=_parse_bucket(resp.json()))
+
+    async def delete_bucket(self, name: str) -> SupythonResponse[None]:
+        try:
+            resp = await self._http.delete(
+                f"{self._url}/bucket/{name}", headers=self._headers()
+            )
+        except httpx.HTTPError as exc:
+            return SupythonResponse(error=StorageError("network_error", str(exc), 0))
+
+        if resp.status_code >= 400:
+            return SupythonResponse(error=_make_storage_error(resp))
+
+        return SupythonResponse(data=None)

supython/db.py

@@ -0,0 +1,151 @@
+import asyncio
+import json
+import logging
+import os
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+import asyncpg
+from fastapi import FastAPI
+
+from .settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+_pool: asyncpg.Pool | None = None
+
+
+async def _connection_setup(conn: asyncpg.Connection) -> None:
+    timeout_ms = get_settings().db_statement_timeout_ms
+    if timeout_ms > 0:
+        await conn.execute(f"set statement_timeout = {int(timeout_ms)}")
+
+
+async def init_pool() -> asyncpg.Pool:
+    global _pool
+    if _pool is None:
+        s = get_settings()
+        _pool = await asyncpg.create_pool(
+            s.database_url,
+            min_size=s.db_pool_min_size,
+            max_size=s.db_pool_max_size,
+            setup=_connection_setup,
+        )
+    return _pool
+
+
+async def close_pool() -> None:
+    global _pool
+    if _pool is not None:
+        await _pool.close()
+        _pool = None
+
+
+def get_pool() -> asyncpg.Pool:
+    if _pool is None:
+        raise RuntimeError("DB pool not initialised. Call init_pool() first.")
+    return _pool
+
+
+@asynccontextmanager
+async def acquire() -> AsyncGenerator[asyncpg.Connection, None]:
+    pool = get_pool()
+    async with pool.acquire() as conn:
+        yield cast(asyncpg.Connection, conn)
+
+
+@asynccontextmanager
+async def as_role(role: str, claims: dict[str, Any]) -> AsyncGenerator[asyncpg.Connection, None]:
+    """Yield a connection scoped to *role* with *claims* set as the JWT GUC.
+
+    Mirrors PostgREST's per-request role switch so that any SQL executed on
+    the yielded connection sees the same RLS verdict as a PostgREST request
+    would for the same JWT payload.
+    """
+    pool = get_pool()
+
+    allowed = get_settings().db_allowed_roles
+
+    if role not in allowed:
+        raise ValueError(f"role {role!r} not in {sorted(allowed)}")
+
+    async with pool.acquire() as conn, conn.transaction():
+        await conn.execute(f'set local role "{role}"')
+        await conn.execute(
+            "select set_config('request.jwt.claims', $1, true)",
+            json.dumps(claims),
+        )
+        yield cast(asyncpg.Connection, conn)
+
+
+@asynccontextmanager
+async def as_service_role(
+    *,
+    claims: dict[str, Any] | None = None,
+) -> AsyncGenerator[asyncpg.Connection, None]:
+    """Yield a pool connection running as ``service_role`` for the duration.
+
+    Framework-internal housekeeping primitive — distinct from :func:`as_role`,
+    which is the JWT-driven switch PostgREST mirrors. ``service_role`` bypasses
+    RLS, so the choice of role is made by internal code and never by a JWT's
+    ``role`` claim.
+
+    The optional ``claims`` argument sets ``request.jwt.claims`` on the
+    session via ``set_config('request.jwt.claims', …, true)`` so helpers
+    like ``auth.uid()`` see the caller's identity inside the block. This
+    is purely informational: ``service_role`` still bypasses RLS and
+    setting claims does not grant or restrict anything — it just makes
+    audit / stamping helpers return meaningful values during server-side
+    work performed on behalf of a specific user.
+
+    Uses ``SET LOCAL ROLE`` and ``set_config(..., true)`` inside a
+    transaction, so the role and GUC reset on ``COMMIT`` before the
+    connection returns to the pool.
+    """
+    pool = get_pool()
+    async with pool.acquire() as conn, conn.transaction():
+        await conn.execute("set local role service_role")
+        if claims is not None:
+            await conn.execute(
+                "select set_config('request.jwt.claims', $1, true)",
+                json.dumps(claims),
+            )
+        yield cast(asyncpg.Connection, conn)
+
+
+def _maybe_enable_slow_callback_warnings() -> None:
+    """Turn on asyncio debug mode if SUPYTHON_SLOW_CALLBACK_MS is set.
+
+    The CLI's ``dev`` command sets this env var; production code paths leave
+    it unset so the (non-trivial) debug overhead is not paid in prod.
+    """
+    raw = os.environ.get("SUPYTHON_SLOW_CALLBACK_MS")
+    if not raw:
+        return
+    try:
+        threshold_ms = int(raw)
+    except ValueError:
+        logger.warning("SUPYTHON_SLOW_CALLBACK_MS=%r is not an int; ignoring", raw)
+        return
+    if threshold_ms <= 0:
+        return
+    loop = asyncio.get_running_loop()
+    loop.slow_callback_duration = threshold_ms / 1000.0
+    loop.set_debug(True)
+    logger.info(
+        "asyncio debug enabled; warning on callbacks > %dms (dev mode)",
+        threshold_ms,
+    )
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    _maybe_enable_slow_callback_warnings()
+    _created_pool = _pool is None
+    await init_pool()
+    try:
+        yield
+    finally:
+        if _created_pool:
+            await close_pool()

supython/db_admin.py

@@ -0,0 +1,8 @@
+"""Database administration helpers."""
+
+import asyncpg
+
+
+async def rotate_role_password(conn: asyncpg.Connection, role: str, password: str) -> None:
+    quoted = "'" + password.replace("'", "''") + "'"
+    await conn.execute(f"alter role {role} with password {quoted}")

supython/functions/__init__.py

@@ -0,0 +1,19 @@
+"""Filesystem-loaded edge functions.
+
+Layout: every ``*.py`` under ``settings.functions_dir`` becomes a route at
+``/functions/<relative path without .py>``. See :mod:`.loader` for discovery
+rules and :mod:`.router` for the dispatcher contract.
+"""
+
+from .context import Ctx, FunctionUser, PostgrestClient, StorageClient
+from .loader import FunctionRegistry
+from .schemas import FunctionMeta
+
+__all__ = [
+    "Ctx",
+    "FunctionUser",
+    "FunctionMeta",
+    "FunctionRegistry",
+    "PostgrestClient",
+    "StorageClient",
+]

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,
+    )