supython 0.5.0__py3-none-any.whl

supython/realtime/protocol.py

@@ -0,0 +1,234 @@
+"""Transport-agnostic Phoenix Channels v1 protocol helpers.
+
+The realtime websocket endpoint speaks the Phoenix channels 5-tuple wire
+format used by Supabase Realtime v2 (``vsn=1.0.0``):
+
+    [join_ref, ref, topic, event, payload]
+
+This module owns the framing contract (encode/decode, envelope validation),
+the monotonic ref counter the server uses to tag its own pushes, and a
+re-armable heartbeat timer used to detect silent client disconnects.
+
+Everything here is pure: no Starlette, FastAPI, or ``WebSocket`` imports.
+The WebSocket route in :mod:`supython.realtime.websocket` wires these
+primitives to the actual transport.
+"""
+
+import asyncio
+import itertools
+import json
+import time
+from collections.abc import Callable
+from typing import Any, Final
+
+from pydantic import ValidationError
+
+from .schemas import Frame
+
+# ---------------------------------------------------------------------------
+# Constants — Phoenix/Supabase Realtime vocabulary
+# ---------------------------------------------------------------------------
+
+# Connection-level topic used by the SDKs for heartbeats.
+TOPIC_PHOENIX: Final[str] = "phoenix"
+
+# Channel lifecycle events (topic = ``realtime:<name>``).
+EVENT_PHX_JOIN: Final[str] = "phx_join"
+EVENT_PHX_LEAVE: Final[str] = "phx_leave"
+EVENT_PHX_REPLY: Final[str] = "phx_reply"
+EVENT_PHX_CLOSE: Final[str] = "phx_close"
+EVENT_PHX_ERROR: Final[str] = "phx_error"
+
+# In-channel events.
+EVENT_HEARTBEAT: Final[str] = "heartbeat"
+EVENT_ACCESS_TOKEN: Final[str] = "access_token"
+EVENT_BROADCAST: Final[str] = "broadcast"
+EVENT_PRESENCE: Final[str] = "presence"
+EVENT_PRESENCE_STATE: Final[str] = "presence_state"
+EVENT_PRESENCE_DIFF: Final[str] = "presence_diff"
+EVENT_POSTGRES_CHANGES: Final[str] = "postgres_changes"
+
+# phx_reply status values.
+STATUS_OK: Final[str] = "ok"
+STATUS_ERROR: Final[str] = "error"
+
+
+# ---------------------------------------------------------------------------
+# Encode / decode
+# ---------------------------------------------------------------------------
+
+
+class ProtocolError(ValueError):
+    """Raised for any frame that is not a well-formed Phoenix 5-tuple."""
+
+
+def encode(frame: Frame) -> str:
+    """Serialize a :class:`Frame` to the compact JSON string sent over the wire."""
+    return json.dumps(frame.model_dump(mode="json"), separators=(",", ":"))
+
+
+def decode(raw: str | bytes | bytearray) -> Frame:
+    """Parse a raw text frame into a validated :class:`Frame`.
+
+    Binary frames (``vsn=2.0.0``) are intentionally unsupported in v0.4; the
+    client is expected to negotiate JSON via ``?vsn=1.0.0``.
+    """
+    if isinstance(raw, (bytes, bytearray)):
+        try:
+            raw = raw.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise ProtocolError("Frame payload is not valid UTF-8.") from exc
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ProtocolError(f"Frame is not valid JSON: {exc.msg}") from exc
+
+    if not isinstance(data, list):
+        raise ProtocolError(
+            f"Frame must be a JSON array, got {type(data).__name__}."
+        )
+    if len(data) != 5:
+        raise ProtocolError(
+            f"Frame must have exactly 5 elements [join_ref, ref, topic, event, payload], got {len(data)}."
+        )
+
+    try:
+        return Frame.model_validate(data)
+    except ValidationError as exc:
+        raise ProtocolError(f"Frame failed validation: {exc}") from exc
+
+
+# ---------------------------------------------------------------------------
+# Convenience builders
+# ---------------------------------------------------------------------------
+
+
+def make_reply(
+    *,
+    join_ref: str | None,
+    ref: str | None,
+    topic: str,
+    status: str = STATUS_OK,
+    response: dict[str, Any] | None = None,
+) -> Frame:
+    """Build a ``phx_reply`` frame.
+
+    ``ref`` echoes the originating request's ``ref`` so the client can
+    correlate.  ``response`` defaults to ``{}`` which matches how the
+    Supabase SDK parses an ack.
+    """
+    return Frame.build(
+        join_ref=join_ref,
+        ref=ref,
+        topic=topic,
+        event=EVENT_PHX_REPLY,
+        payload={"status": status, "response": response or {}},
+    )
+
+
+def make_server_push(
+    *,
+    topic: str,
+    event: str,
+    payload: dict[str, Any],
+) -> Frame:
+    """Build a server-initiated push (``join_ref`` and ``ref`` are ``null``)."""
+    return Frame.build(
+        join_ref=None,
+        ref=None,
+        topic=topic,
+        event=event,
+        payload=payload,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Ref counter
+# ---------------------------------------------------------------------------
+
+
+class RefCounter:
+    """Monotonic per-connection ref generator.
+
+    Refs are emitted as strings because the Phoenix wire format treats them
+    opaquely and the JS SDK occasionally sends non-numeric refs.  Starting
+    at 1 matches the convention used by the Supabase SDK for the first
+    join.
+    """
+
+    __slots__ = ("_counter",)
+
+    def __init__(self, start: int = 1) -> None:
+        self._counter: itertools.count[int] = itertools.count(start)
+
+    def next(self) -> str:
+        return str(next(self._counter))
+
+
+# ---------------------------------------------------------------------------
+# Heartbeat timer
+# ---------------------------------------------------------------------------
+
+
+Clock = Callable[[], float]
+
+
+class HeartbeatTimeout:
+    """Re-armable inactivity timer.
+
+    The server does not send heartbeats; it only ensures clients send them.
+    Each incoming frame calls :meth:`touch` to reset the deadline.  The
+    WebSocket handler concurrently runs :meth:`wait_for_timeout` and closes
+    the socket (code 1001) when it returns.
+
+    A custom ``clock`` can be injected for deterministic unit tests.  The
+    default is :func:`time.monotonic`, which is immune to wall-clock jumps.
+    """
+
+    __slots__ = ("_timeout", "_clock", "_last")
+
+    def __init__(
+        self,
+        timeout_seconds: float,
+        *,
+        clock: Clock = time.monotonic,
+    ) -> None:
+        if timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be > 0")
+        self._timeout = float(timeout_seconds)
+        self._clock = clock
+        self._last = clock()
+
+    def touch(self) -> None:
+        """Mark activity just observed; re-arms the timer."""
+        self._last = self._clock()
+
+    @property
+    def seconds_since_last(self) -> float:
+        return self._clock() - self._last
+
+    @property
+    def seconds_until_timeout(self) -> float:
+        return max(0.0, self._timeout - self.seconds_since_last)
+
+    def is_expired(self) -> bool:
+        return self.seconds_since_last >= self._timeout
+
+    async def wait_for_timeout(
+        self,
+        *,
+        sleep: Callable[[float], Any] = asyncio.sleep,
+    ) -> None:
+        """Block until the timeout deadline is reached without a ``touch``.
+
+        If :meth:`touch` is called while this coroutine is sleeping, the
+        sleep naturally extends on the next iteration because the remaining
+        window is recomputed from the updated ``_last``.  Returns as soon
+        as the deadline has been met with no intervening touch.
+        """
+        while True:
+            remaining = self.seconds_until_timeout
+            if remaining <= 0:
+                return
+            await sleep(remaining)

supython/realtime/router.py

@@ -0,0 +1,184 @@
+"""HTTP control plane for the realtime module.
+
+Exposes three REST endpoints under ``/realtime/v1`` and mounts the
+WebSocket route from :mod:`.websocket` onto the same router so that a
+single ``app.include_router(realtime.router)`` call wires up both the
+REST surface and the channel transport:
+
+``POST /realtime/v1/enable``
+    Service-role only.  Opt a table into change-event fan-out.  Wraps
+    :func:`service.enable_table`.
+
+``GET /realtime/v1/info``
+    List the contents of ``realtime.enabled_tables`` under the caller's
+    role (RLS still applies).
+
+``POST /realtime/v1/broadcast/{topic}``
+    Service-role only.  Push a Phoenix ``broadcast`` frame to every
+    subscriber of ``topic``.  Useful for server-to-client pushes from
+    edge functions and cron jobs that don't want to hold a WebSocket.
+
+``WS  /realtime/v1/websocket``
+    The actual channel transport — see :mod:`.websocket`.
+"""
+
+from typing import Annotated, Any
+
+import jwt
+from fastapi import APIRouter, Depends, Header, HTTPException, status
+
+from .. import db, tokens
+from . import service
+from .broker import get_broker
+from .schemas import (
+    BroadcastRequest,
+    BroadcastResponse,
+    EnabledTable,
+    EnableTableRequest,
+)
+from .topics import TopicError, validate_topic
+from .websocket import realtime_websocket
+
+router = APIRouter(prefix="/realtime/v1", tags=["realtime"])
+
+
+# ---------------------------------------------------------------------------
+# Error translation
+# ---------------------------------------------------------------------------
+
+
+def _realtime_error(exc: service.RealtimeError) -> HTTPException:
+    return HTTPException(
+        status_code=exc.status,
+        detail={"code": exc.code, "message": exc.message},
+    )
+
+
+# ---------------------------------------------------------------------------
+# Auth dependencies
+# ---------------------------------------------------------------------------
+
+
+async def _current_claims(
+    authorization: Annotated[str | None, Header()] = None,
+) -> dict[str, Any]:
+    """Decode the bearer JWT and return its claims."""
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Missing bearer token")
+    token = authorization.split(" ", 1)[1]
+    try:
+        return tokens.decode_access_token(token)
+    except jwt.PyJWTError as exc:
+        raise HTTPException(
+            status.HTTP_401_UNAUTHORIZED, f"Invalid token: {exc}"
+        ) from exc
+
+
+def _claims_role(claims: dict[str, Any]) -> str:
+    role = claims.get("role")
+    if not isinstance(role, str) or not role:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Token missing role claim")
+    return role
+
+
+def _require_service_role(claims: dict[str, Any]) -> None:
+    if _claims_role(claims) != "service_role":
+        raise HTTPException(
+            status.HTTP_403_FORBIDDEN,
+            detail={
+                "code": "forbidden",
+                "message": "service_role required",
+            },
+        )
+
+
+# ---------------------------------------------------------------------------
+# REST endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/enable", response_model=EnabledTable, status_code=201)
+async def enable_table(
+    payload: EnableTableRequest,
+    claims: Annotated[dict[str, Any], Depends(_current_claims)],
+) -> EnabledTable:
+    """Opt a table into realtime change events.
+
+    Only callable with a ``service_role`` JWT.  Returns the freshly
+    written :class:`EnabledTable` row so the caller can echo it back to
+    the user.
+    """
+    _require_service_role(claims)
+    try:
+        async with db.as_service_role(claims=claims) as conn:
+            return await service.enable_table(conn, payload)
+    except service.RealtimeError as exc:
+        raise _realtime_error(exc) from exc
+
+
+@router.get("/info", response_model=list[EnabledTable])
+async def list_info(
+    claims: Annotated[dict[str, Any], Depends(_current_claims)],
+) -> list[EnabledTable]:
+    """List every row of ``realtime.enabled_tables`` visible to the caller.
+
+    The registry has its own RLS policy granting ``select`` to ``anon``,
+    ``authenticated``, and ``service_role`` (see migration 0006), so all
+    callers see the same rows in v0.4 — but reads still go through a
+    role-scoped connection so future per-row policies are honoured
+    without changes here.
+    """
+    role = _claims_role(claims)
+    if role == "service_role":
+        async with db.as_service_role(claims=claims) as conn:
+            return await service.list_enabled(conn)
+    try:
+        async with db.as_role(role, claims) as conn:
+            return await service.list_enabled(conn)
+    except ValueError as exc:
+        # Role decoded from the JWT is not in db_allowed_roles.
+        raise HTTPException(
+            status.HTTP_403_FORBIDDEN,
+            detail={"code": "forbidden", "message": str(exc)},
+        ) from exc
+
+
+@router.post(
+    "/broadcast/{topic}",
+    response_model=BroadcastResponse,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def broadcast(
+    topic: str,
+    payload: BroadcastRequest,
+    claims: Annotated[dict[str, Any], Depends(_current_claims)],
+) -> BroadcastResponse:
+    """Fan a Phoenix ``broadcast`` frame out to every subscriber of *topic*.
+
+    Service-role only.  REST-initiated broadcasts have no sender id, so
+    the sender-exclusion logic is a no-op — every subscriber receives
+    the frame.
+    """
+    _require_service_role(claims)
+    try:
+        validate_topic(topic)
+    except TopicError as exc:
+        raise HTTPException(
+            status.HTTP_400_BAD_REQUEST,
+            detail={"code": "invalid_topic", "message": str(exc)},
+        ) from exc
+    delivered = get_broker().broadcast(
+        topic=topic,
+        event=payload.event,
+        payload=payload.payload,
+        sender_id=None,
+    )
+    return BroadcastResponse(topic=topic, delivered=delivered)
+
+
+# ---------------------------------------------------------------------------
+# WebSocket transport — same prefix, same router
+# ---------------------------------------------------------------------------
+
+
+router.add_api_websocket_route("/websocket", realtime_websocket)

supython/realtime/schemas.py

@@ -0,0 +1,207 @@
+from datetime import datetime
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+
+
+# ---------------------------------------------------------------------------
+# Wire envelope — Phoenix 5-tuple: [join_ref, ref, topic, event, payload]
+# ---------------------------------------------------------------------------
+
+_EnvelopeTuple = tuple[str | None, str | None, str, str, dict[str, Any]]
+
+
+class Frame(RootModel[_EnvelopeTuple]):
+    """Codec for the Phoenix channel 5-tuple wire format."""
+
+    @property
+    def join_ref(self) -> str | None:
+        return self.root[0]
+
+    @property
+    def ref(self) -> str | None:
+        return self.root[1]
+
+    @property
+    def topic(self) -> str:
+        return self.root[2]
+
+    @property
+    def event(self) -> str:
+        return self.root[3]
+
+    @property
+    def payload(self) -> dict[str, Any]:
+        return self.root[4]
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        join_ref: str | None,
+        ref: str | None,
+        topic: str,
+        event: str,
+        payload: dict[str, Any],
+    ) -> "Frame":
+        return cls.model_validate((join_ref, ref, topic, event, payload))
+
+
+# ---------------------------------------------------------------------------
+# phx_join payload — config sub-models
+# ---------------------------------------------------------------------------
+
+PostgresChangesEvent = Literal["INSERT", "UPDATE", "DELETE", "*"]
+
+
+class PostgresChangesFilter(BaseModel):
+    """One entry in config.postgres_changes sent by the client on phx_join."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    event: PostgresChangesEvent
+    schema_name: str = Field(alias="schema")
+    table: str
+    filter: str | None = None
+
+
+class BroadcastConfig(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    self_echo: bool = Field(default=False, alias="self")
+    ack: bool = False
+
+
+class PresenceConfig(BaseModel):
+    key: str = ""
+
+
+class JoinConfig(BaseModel):
+    postgres_changes: list[PostgresChangesFilter] = Field(default_factory=list)
+    broadcast: BroadcastConfig = Field(default_factory=BroadcastConfig)
+    presence: PresenceConfig = Field(default_factory=PresenceConfig)
+
+
+class PhxJoinPayload(BaseModel):
+    config: JoinConfig = Field(default_factory=JoinConfig)
+    access_token: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# phx_reply payload — join acknowledgement
+# ---------------------------------------------------------------------------
+
+
+class PostgresChangesSubscription(BaseModel):
+    """Server-assigned subscription entry returned inside the phx_join ack."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int
+    event: PostgresChangesEvent
+    schema_name: str = Field(alias="schema")
+    table: str
+    filter: str | None = None
+
+
+class PhxReplyPayload(BaseModel):
+    status: Literal["ok", "error"]
+    response: dict[str, Any] = Field(default_factory=dict)
+
+
+class JoinReplyResponse(BaseModel):
+    postgres_changes: list[PostgresChangesSubscription] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# postgres_changes server push
+# ---------------------------------------------------------------------------
+
+
+class ColumnInfo(BaseModel):
+    name: str
+    type: str
+
+
+class PostgresChangesData(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    schema_name: str = Field(alias="schema")
+    table: str
+    type: Literal["INSERT", "UPDATE", "DELETE"]
+    commit_timestamp: datetime
+    columns: list[ColumnInfo] = Field(default_factory=list)
+    record: dict[str, Any] | None = None
+    old_record: dict[str, Any] | None = None
+
+
+class PostgresChangesPush(BaseModel):
+    """Payload for the server-push 'postgres_changes' event."""
+
+    ids: list[int]
+    data: PostgresChangesData
+
+
+# ---------------------------------------------------------------------------
+# presence pushes
+# ---------------------------------------------------------------------------
+
+
+class PresenceState(BaseModel):
+    """Full presence state pushed once on join."""
+
+    # Maps presence key → list of metas
+    presences: dict[str, list[dict[str, Any]]] = Field(default_factory=dict)
+
+
+class PresenceDiff(BaseModel):
+    joins: dict[str, list[dict[str, Any]]] = Field(default_factory=dict)
+    leaves: dict[str, list[dict[str, Any]]] = Field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# REST control-plane — POST /realtime/v1/enable
+# ---------------------------------------------------------------------------
+
+
+class EnableTableRequest(BaseModel):
+    """Body for POST /realtime/v1/enable (service-role only)."""
+
+    # Fully qualified: "public.todos"
+    table: Annotated[str, Field(pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$")]
+    owner_column: str | None = "user_id"
+
+
+class EnabledTable(BaseModel):
+    """One row from realtime.enabled_tables, returned by GET /realtime/v1/info."""
+
+    schema_name: str
+    table_name: str
+    pk_columns: list[str]
+    owner_column: str | None
+    created_at: datetime
+
+
+# ---------------------------------------------------------------------------
+# REST control-plane — POST /realtime/v1/broadcast/{topic}
+# ---------------------------------------------------------------------------
+
+
+class BroadcastRequest(BaseModel):
+    """Body for POST /realtime/v1/broadcast/{topic} (service-role only).
+
+    The REST broadcast hop lets edge functions / cron jobs push to a
+    realtime channel without holding an open WebSocket.  Shape mirrors the
+    ``broadcast`` event payload sent by SDK clients so subscribers receive
+    an identical frame regardless of source.
+    """
+
+    event: str = Field(min_length=1, max_length=255)
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class BroadcastResponse(BaseModel):
+    """Result of a REST-initiated broadcast."""
+
+    topic: str
+    delivered: int