supython 0.1.0__py3-none-any.whl

supython/admin/api/realtime.py

@@ -0,0 +1,281 @@
+"""Admin realtime control plane.
+
+GET  /admin/api/v1/realtime/tables
+    List every row in ``realtime.enabled_tables``.
+
+GET  /admin/api/v1/realtime/inspect?topic=...
+    SSE stream; subscribe to the broker under ``service_role`` and
+    receive broadcast / postgres_changes events in real time.  1 000-event
+    cap, then the stream closes cleanly (matches frontend ``useLiveTail``).
+
+POST /admin/api/v1/realtime/broadcast
+    Confirm-required broadcast to a topic.  Wraps the broker's
+    ``broadcast()`` method.  Audit-logged.
+"""
+
+import asyncio
+import ipaddress
+import json
+import logging
+from collections.abc import AsyncGenerator
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Query, Request, status
+from fastapi.responses import StreamingResponse
+
+from ... import db
+from ...realtime import get_broker
+from ...realtime.broker import BrokerError
+from ...realtime.schemas import (
+    BroadcastResponse,
+    EnabledTable,
+    JoinConfig,
+    PostgresChangesFilter,
+)
+from ...realtime.topics import TopicError, assign_subscription_ids, validate_topic
+from .. import audit
+from ..deps import require_admin
+from ..schemas import AdminBroadcastRequest
+from . import service_realtime
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/admin/api/v1/realtime", tags=["admin.realtime"])
+
+# Maximum events pushed before the SSE inspect stream self-closes.
+_INSPECT_EVENT_CAP = 1000
+
+
+def _client_ip(request: Request) -> str | None:
+    if request.client is None:
+        return None
+    try:
+        ipaddress.ip_address(request.client.host)
+    except ValueError:
+        return None
+    return request.client.host
+
+
+# ---------------------------------------------------------------------------
+# GET /tables — list realtime-enabled tables
+# ---------------------------------------------------------------------------
+
+
+@router.get("/tables", response_model=list[EnabledTable])
+async def list_tables(
+    _: Annotated[UUID, Depends(require_admin)],
+) -> list[EnabledTable]:
+    """List every row in ``realtime.enabled_tables``."""
+    async with db.as_service_role() as conn:
+        return await service_realtime.list_enabled_tables(conn)
+
+
+# ---------------------------------------------------------------------------
+# GET /inspect — SSE broker subscriber
+# ---------------------------------------------------------------------------
+
+
+def _sse_event(event: str, data: dict) -> str:
+    """Format a single SSE event."""
+    payload = json.dumps(data, separators=(",", ":"), default=str)
+    return f"event: {event}\ndata: {payload}\n\n"
+
+
+async def _inspect_events(
+    topic: str,
+) -> AsyncGenerator[str, None]:
+    """Async generator that yields SSE frames from the broker for *topic*.
+
+    Registers a virtual connection under ``service_role``, subscribes to
+    *topic* with broadcast and all-tables postgres_changes, then drains
+    the broker outbound queue.  Stops after ``_INSPECT_EVENT_CAP`` frames
+    or when the client disconnects.
+    """
+    broker = get_broker()
+
+    try:
+        conn = await broker.register(
+            role="service_role",
+            claims={"role": "service_role"},
+        )
+    except BrokerError as exc:
+        yield _sse_event("error", {"code": "broker_full", "message": str(exc)})
+        return
+
+    # Build postgres_changes subscriptions for every enabled table so the
+    # admin sees all DB changes flowing through any channel on this topic.
+    # Any failure between register and subscribe must unregister the
+    # virtual connection so it does not leak a broker slot.
+    try:
+        async with db.as_service_role() as db_conn:
+            enabled = await service_realtime.list_enabled_tables(db_conn)
+
+        postgres_changes = [
+            PostgresChangesFilter(
+                event="*",
+                schema=t.schema_name,
+                table=t.table_name,
+            )
+            for t in enabled
+        ]
+        config = JoinConfig(postgres_changes=postgres_changes)
+        resolved = assign_subscription_ids(config)
+
+        await broker.subscribe(
+            conn,
+            topic=topic,
+            join_ref=None,
+            postgres_changes=resolved,
+            broadcast_self=True,
+            presence_key="",
+        )
+    except Exception as exc:
+        await broker.unregister(conn)
+        yield _sse_event(
+            "error",
+            {"code": "subscribe_failed", "message": str(exc)},
+        )
+        return
+
+    sent = 0
+    try:
+        # Yield an initial "connected" event so the frontend knows the
+        # subscription is live.
+        yield _sse_event(
+            "connected",
+            {"topic": topic, "tables": len(enabled)},
+        )
+
+        while sent < _INSPECT_EVENT_CAP:
+            try:
+                frame = await asyncio.wait_for(conn.outbound.get(), timeout=30.0)
+            except TimeoutError:
+                # Heartbeat to keep the connection alive.
+                yield _sse_event("heartbeat", {})
+                continue
+
+            yield _sse_event(
+                frame.event,
+                {
+                    "topic": frame.topic,
+                    "payload": frame.payload,
+                },
+            )
+            sent += 1
+    except asyncio.CancelledError:
+        pass
+    finally:
+        try:
+            await broker.unregister(conn)
+        except Exception:
+            logger.debug(
+                "realtime inspect: unregister failed for topic=%s",
+                topic,
+                exc_info=True,
+            )
+
+
+@router.get("/inspect")
+async def inspect(
+    request: Request,
+    _: Annotated[UUID, Depends(require_admin)],
+    topic: Annotated[str, Query(description="realtime:<name> topic to subscribe to")],
+) -> StreamingResponse:
+    """Subscribe to the broker for *topic* and stream events as SSE.
+
+    Events are pushed as ``text/event-stream``.  The stream self-closes
+    after 1 000 events or 30 s of inactivity.  Every event carries an
+    ``event:`` field matching the Phoenix frame event and a ``data:``
+    field with ``{topic, payload}`` JSON.
+    """
+    try:
+        validate_topic(topic)
+    except TopicError as exc:
+        raise HTTPException(
+            status.HTTP_400_BAD_REQUEST,
+            detail={"code": "invalid_topic", "message": str(exc)},
+        ) from exc
+
+    broker = get_broker()
+    if not broker.is_healthy:
+        raise HTTPException(
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail={
+                "code": "broker_unhealthy",
+                "message": "Realtime broker is not running",
+            },
+        )
+
+    logger.debug("realtime inspect: admin subscribed to topic=%s", topic)
+
+    async def _stream() -> AsyncGenerator[str, None]:
+        async for chunk in _inspect_events(topic):
+            if await request.is_disconnected():
+                break
+            yield chunk
+
+    return StreamingResponse(
+        _stream(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# POST /broadcast — confirm-required broadcast
+# ---------------------------------------------------------------------------
+
+
+@router.post(
+    "/broadcast",
+    response_model=BroadcastResponse,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+async def broadcast(
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+    body: Annotated[AdminBroadcastRequest, Body()],
+) -> BroadcastResponse:
+    """Fan a broadcast frame out to every subscriber of *topic*.
+
+    Confirm-required by the frontend (Story 10.3).  The confirmation
+    dialog is presented in the UI before this endpoint is called; the
+    backend simply executes the broadcast under ``service_role`` and
+    logs an audit event.
+    """
+    try:
+        validate_topic(body.topic)
+    except TopicError as exc:
+        raise HTTPException(
+            status.HTTP_400_BAD_REQUEST,
+            detail={"code": "invalid_topic", "message": str(exc)},
+        ) from exc
+
+    broker = get_broker()
+    delivered = broker.broadcast(
+        topic=body.topic,
+        event=body.event,
+        payload=body.payload,
+        sender_id=None,
+    )
+
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    async with db.as_service_role() as conn:
+        await audit.write(
+            conn,
+            admin_id=admin_id,
+            action="realtime.broadcast",
+            target=body.topic,
+            payload={
+                "event": body.event,
+                "delivered": delivered,
+            },
+            ip=ip,
+            ua=ua,
+        )
+    return BroadcastResponse(topic=body.topic, delivered=delivered)

supython/admin/api/service_auth.py

@@ -0,0 +1,49 @@
+from datetime import datetime
+from uuid import UUID
+
+import asyncpg
+
+from ..errors import AdminError
+
+
+async def authenticate(
+    conn: asyncpg.Connection, email: str, password: str
+) -> tuple[UUID, str]:
+    """Verify credentials and return (admin_id, email).
+
+    Raises AdminError("invalid_credentials", 401) on bad email/password.
+    """
+    from ... import passwords
+
+    row = await conn.fetchrow(
+        """
+        select id, email, password_hash
+        from admin.admin_users
+        where email = $1
+        """,
+        email,
+    )
+    if not row or not passwords.verify_password(row["password_hash"], password):
+        raise AdminError("invalid_credentials", "Invalid credentials", 401)
+    return row["id"], row["email"]
+
+
+async def touch_last_login(conn: asyncpg.Connection, admin_id: UUID) -> None:
+    await conn.execute(
+        "update admin.admin_users set last_login_at = now() where id = $1",
+        admin_id,
+    )
+
+
+async def fetch_admin(
+    conn: asyncpg.Connection, admin_id: UUID
+) -> tuple[str, datetime | None] | None:
+    row = await conn.fetchrow(
+        """
+        select email, last_login_at
+        from admin.admin_users
+        where id = $1
+        """,
+        admin_id,
+    )
+    return (row["email"], row["last_login_at"]) if row else None

supython/admin/api/service_auth_templates.py

@@ -0,0 +1,83 @@
+"""Raw SQL helpers for email template CRUD — no Pydantic, no FastAPI."""
+
+from datetime import datetime, timezone
+
+import asyncpg
+
+from ..errors import AdminError
+from ..schemas import EmailTemplate
+
+
+async def list_templates(conn: asyncpg.Connection) -> list[EmailTemplate]:
+    rows = await conn.fetch(
+        """
+        select name, subject, text_body, updated_at
+        from admin.email_templates
+        order by name
+        """
+    )
+    return [
+        EmailTemplate(
+            name=row["name"],
+            subject=row["subject"],
+            text_body=row["text_body"],
+            updated_at=row["updated_at"],
+        )
+        for row in rows
+    ]
+
+
+async def get_template(conn: asyncpg.Connection, name: str) -> EmailTemplate:
+    row = await conn.fetchrow(
+        """
+        select name, subject, text_body, updated_at
+        from admin.email_templates
+        where name = $1
+        """,
+        name,
+    )
+    if row is None:
+        raise AdminError("not_found", f"template {name!r} not found", 404)
+    return EmailTemplate(
+        name=row["name"],
+        subject=row["subject"],
+        text_body=row["text_body"],
+        updated_at=row["updated_at"],
+    )
+
+
+async def update_template(
+    conn: asyncpg.Connection,
+    name: str,
+    subject: str | None,
+    text_body: str | None,
+) -> EmailTemplate:
+    """Patch one or both fields. Returns the updated row."""
+    existing = await conn.fetchrow(
+        "select subject, text_body from admin.email_templates where name = $1",
+        name,
+    )
+    if existing is None:
+        raise AdminError("not_found", f"template {name!r} not found", 404)
+
+    new_subject = subject if subject is not None else existing["subject"]
+    new_body = text_body if text_body is not None else existing["text_body"]
+
+    row = await conn.fetchrow(
+        """
+        update admin.email_templates
+        set subject = $2, text_body = $3, updated_at = $4
+        where name = $1
+        returning name, subject, text_body, updated_at
+        """,
+        name,
+        new_subject,
+        new_body,
+        datetime.now(tz=timezone.utc),
+    )
+    return EmailTemplate(
+        name=row["name"],
+        subject=row["subject"],
+        text_body=row["text_body"],
+        updated_at=row["updated_at"],
+    )