supython 0.1.0__py3-none-any.whl

supython/admin/api/service_ops.py

@@ -0,0 +1,213 @@
+"""Admin service layer for the ops backups + live log tail surface.
+
+Pure async functions over ``asyncpg.Connection``. No FastAPI imports.
+"""
+
+import asyncio
+import json
+import logging
+from collections.abc import AsyncIterator
+from datetime import UTC, datetime
+from uuid import UUID
+
+import asyncpg
+
+from ...backups import service as backups_service
+from ...logging_config import get_log_ring
+from ..errors import AdminError
+from ..schemas import AdminBackupRow, AdminBackupsPage, BackupDownloadResponse
+
+logger = logging.getLogger(__name__)
+
+
+def _row_to_admin_backup(row: asyncpg.Record) -> AdminBackupRow:
+    return AdminBackupRow(
+        id=row["id"],
+        kind=row["kind"],
+        status=row["status"],
+        size=row.get("size"),
+        file_path=row.get("file_path"),
+        error_message=row.get("error_message"),
+        started_at=row["started_at"],
+        finished_at=row.get("finished_at"),
+        created_at=row["created_at"],
+    )
+
+
+async def list_backups(
+    conn: asyncpg.Connection,
+    *,
+    limit: int = 50,
+    offset: int = 0,
+) -> AdminBackupsPage:
+    rows = await conn.fetch(
+        """
+        select id, kind, status, size, file_path, error_message,
+               started_at, finished_at, created_at
+        from admin.backups
+        order by created_at desc
+        limit $1 offset $2
+        """,
+        limit,
+        offset,
+    )
+    total = await conn.fetchval("select count(*) from admin.backups")
+    return AdminBackupsPage(
+        rows=[_row_to_admin_backup(r) for r in rows],
+        total=total or 0,
+    )
+
+
+async def start_backup(conn: asyncpg.Connection, *, kind: str) -> AdminBackupRow:
+    try:
+        record = await backups_service.start_backup(conn, kind=kind)
+    except backups_service.BackupError as exc:
+        raise AdminError(exc.code, exc.message, exc.status) from exc
+
+    # Re-fetch to get the row in admin shape
+    row = await conn.fetchrow(
+        """
+        select id, kind, status, size, file_path, error_message,
+               started_at, finished_at, created_at
+        from admin.backups
+        where id = $1
+        """,
+        record.id,
+    )
+    if row is None:
+        raise AdminError("backup_not_found", "backup not found after creation", 500)
+    return _row_to_admin_backup(row)
+
+
+async def get_backup_download_response(
+    conn: asyncpg.Connection, backup_id: UUID
+) -> BackupDownloadResponse:
+    row = await conn.fetchrow(
+        """
+        select id, status, file_path
+        from admin.backups
+        where id = $1
+        """,
+        backup_id,
+    )
+    if row is None:
+        raise AdminError("backup_not_found", f"backup {backup_id} not found", 404)
+    if row["status"] != "completed":
+        raise AdminError(
+            "backup_not_ready",
+            f"backup status is {row['status']!r}, not 'completed'",
+            409,
+        )
+    if not row["file_path"]:
+        raise AdminError(
+            "backup_no_file",
+            "backup has no file_path",
+            500,
+        )
+
+    token = backups_service.generate_download_token(backup_id)
+    download_url = f"/admin/api/v1/ops/downloads/{token}"
+
+    return BackupDownloadResponse(
+        download_url=download_url,
+        expires_in=600,
+        backup_id=backup_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Live log tail
+# ---------------------------------------------------------------------------
+
+_LOG_LEVEL_RANK: dict[str, int] = {
+    "DEBUG": 10,
+    "INFO": 20,
+    "WARNING": 30,
+    "ERROR": 40,
+    "CRITICAL": 50,
+}
+
+
+def _entry_matches(
+    entry: dict[str, object],
+    *,
+    level: str | None,
+    substring: str | None,
+    request_id: str | None,
+) -> bool:
+    if level is not None:
+        min_rank = _LOG_LEVEL_RANK.get(level.upper(), 0)
+        entry_rank = _LOG_LEVEL_RANK.get(str(entry.get("level", "")), 0)
+        if entry_rank < min_rank:
+            return False
+    if substring is not None:
+        msg = str(entry.get("message", ""))
+        if substring.lower() not in msg.lower():
+            return False
+    if request_id is not None:
+        entry_rid = str(entry.get("request_id", ""))
+        if request_id != entry_rid:
+            return False
+    return True
+
+
+_LOG_TAIL_POLL_S = 0.5
+_LOG_TAIL_KEEPALIVE_S = 15.0
+
+
+async def tail_logs(
+    *,
+    level: str | None = None,
+    substring: str | None = None,
+    request_id: str | None = None,
+) -> AsyncIterator[str]:
+    """SSE event-stream generator that tails the in-memory log ring buffer.
+
+    On first iteration it emits a ``logs:snapshot`` event with all matching
+    entries.  Subsequent iterations poll the ring buffer and emit
+    ``logs:append`` events for any new matching entries.
+
+    A keepalive ``:`` comment line is emitted every 15 s to prevent proxies
+    from closing the connection.
+    """
+    last_ts: str = ""
+    last_keepalive = datetime.now(tz=UTC)
+
+    while True:
+        all_entries = get_log_ring()
+
+        # Find the slice of entries that arrived after the last timestamp we saw.
+        # Walk from the right (newest) to find where to start.
+        if last_ts:
+            new_entries: list[dict[str, object]] = []
+            for entry in reversed(all_entries):
+                if str(entry.get("timestamp", "")) <= last_ts:
+                    break
+                new_entries.append(entry)
+            new_entries.reverse()
+        else:
+            # First poll — always emit a snapshot so clients know the
+            # handshake is complete, even when filters exclude every entry.
+            matching = [
+                e
+                for e in all_entries
+                if _entry_matches(e, level=level, substring=substring, request_id=request_id)
+            ]
+            yield f"event: logs:snapshot\ndata: {json.dumps(matching)}\n\n"
+            last_ts = str(all_entries[-1].get("timestamp", "")) if all_entries else ""
+            continue
+        # Emit matching new entries as `logs:append` events.
+        for entry in new_entries:
+            if _entry_matches(entry, level=level, substring=substring, request_id=request_id):
+                yield f"event: logs:append\ndata: {json.dumps(entry)}\n\n"
+
+        if new_entries:
+            last_ts = str(new_entries[-1].get("timestamp", ""))
+
+        # Keepalive
+        now = datetime.now(tz=UTC)
+        if (now - last_keepalive).total_seconds() >= _LOG_TAIL_KEEPALIVE_S:
+            yield ": keepalive\n\n"
+            last_keepalive = now
+
+        await asyncio.sleep(_LOG_TAIL_POLL_S)

supython/admin/api/service_realtime.py

@@ -0,0 +1,30 @@
+"""Admin service layer for the realtime surface.
+
+Pure async functions over ``asyncpg.Connection``. No FastAPI imports.
+"""
+
+import asyncpg
+
+from ...realtime.schemas import EnabledTable
+
+
+def _row_to_enabled_table(row: asyncpg.Record) -> EnabledTable:
+    return EnabledTable(
+        schema_name=row["schema_name"],
+        table_name=row["table_name"],
+        pk_columns=list(row["pk_columns"]),
+        owner_column=row["owner_column"],
+        created_at=row["created_at"],
+    )
+
+
+async def list_enabled_tables(conn: asyncpg.Connection) -> list[EnabledTable]:
+    """Return every row from ``realtime.enabled_tables`` (service_role view)."""
+    rows = await conn.fetch(
+        """
+        select schema_name, table_name, pk_columns, owner_column, created_at
+        from realtime.enabled_tables
+        order by schema_name, table_name
+        """
+    )
+    return [_row_to_enabled_table(r) for r in rows]

supython/admin/api/service_storage.py

@@ -0,0 +1,220 @@
+from typing import Literal
+from uuid import UUID
+
+import asyncpg
+
+from ... import db
+from ...storage import service as storage_service
+from ...storage.backends import BackendError, StorageBackend, make_object_key
+from ..errors import AdminError
+from ..schemas import (
+    AdminBucket,
+    AdminObject,
+    AdminObjectsPage,
+    AdminSignedUrlResponse,
+)
+from .service_db import preview_claims
+
+
+def _row_to_bucket(row: asyncpg.Record) -> AdminBucket:
+    return AdminBucket(
+        id=row["id"],
+        name=row["name"],
+        owner=row["owner"],
+        public=row["public"],
+        object_count=row["object_count"],
+        total_size=row["total_size"],
+        file_size_limit=row["file_size_limit"],
+        allowed_mime_types=row["allowed_mime_types"],
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+    )
+
+
+def _row_to_object(row: asyncpg.Record) -> AdminObject:
+    return AdminObject(
+        id=row["id"],
+        bucket=row["bucket_name"],
+        name=row["name"],
+        owner=row["owner"],
+        size=row["size"],
+        mime_type=row["mime_type"],
+        etag=row["etag"],
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+    )
+
+
+async def list_buckets(conn: asyncpg.Connection) -> list[AdminBucket]:
+    rows = await conn.fetch(
+        """
+        select b.id, b.name, b.owner, b.public,
+               b.file_size_limit, b.allowed_mime_types,
+               b.created_at, b.updated_at,
+               coalesce(o.count, 0)::bigint as object_count,
+               coalesce(o.total_size, 0)::bigint as total_size
+        from storage.buckets b
+        left join (
+            select bucket_id,
+                   count(*) as count,
+                   sum(size) as total_size
+            from storage.objects
+            group by bucket_id
+        ) o on o.bucket_id = b.id
+        order by b.name
+        """
+    )
+    return [_row_to_bucket(r) for r in rows]
+
+
+async def list_bucket_objects(
+    conn: asyncpg.Connection,
+    bucket: str,
+    prefix: str | None,
+    limit: int,
+    offset: int,
+) -> AdminObjectsPage:
+    if limit <= 0 or limit > 500:
+        raise AdminError("invalid_limit", "limit must be between 1 and 500", 422)
+    if offset < 0:
+        raise AdminError("invalid_offset", "offset must be >= 0", 422)
+    bucket_row = await conn.fetchrow(
+        "select id from storage.buckets where name = $1",
+        bucket,
+    )
+    if bucket_row is None:
+        raise AdminError("bucket_not_found", f"Bucket {bucket!r} not found", 404)
+    bucket_id = bucket_row["id"]
+    rows = await conn.fetch(
+        """
+        select o.id, o.bucket_id, o.name, o.owner, o.size, o.mime_type,
+               o.etag, o.created_at, o.updated_at,
+               $1::text as bucket_name
+        from storage.objects o
+        where o.bucket_id = $2
+          and ($3::text is null or o.name like $3 || '%')
+        order by o.name
+        limit $4 offset $5
+        """,
+        bucket,
+        bucket_id,
+        prefix,
+        limit,
+        offset,
+    )
+    total = await conn.fetchval(
+        """
+        select count(*)
+        from storage.objects
+        where bucket_id = $1
+          and ($2::text is null or name like $2 || '%')
+        """,
+        bucket_id,
+        prefix,
+    )
+    return AdminObjectsPage(
+        rows=[_row_to_object(r) for r in rows],
+        total=total or 0,
+        prefix=prefix,
+    )
+
+
+async def _resolve_object(
+    conn: asyncpg.Connection, object_id: UUID
+) -> tuple[str, str]:
+    row = await conn.fetchrow(
+        """
+        select b.name as bucket_name, o.name
+        from storage.objects o
+        join storage.buckets b on b.id = o.bucket_id
+        where o.id = $1
+        """,
+        object_id,
+    )
+    if row is None:
+        raise AdminError("object_not_found", "Object not found", 404)
+    return row["bucket_name"], row["name"]
+
+
+async def sign_object(
+    object_id: UUID,
+    expires_in: int | None,
+    role: Literal["service_role", "authenticated", "anon"],
+    impersonate_sub: UUID | None,
+) -> tuple[AdminSignedUrlResponse, str, str]:
+    """Sign a download URL for ``object_id``.
+
+    Resolution happens under ``service_role`` so the admin can always find the
+    object. The signing call itself runs under ``role`` so RLS gates whether
+    that role would have been able to issue the URL — the disclosed
+    ``signed_under_role`` tells the operator which surface they granted
+    access through.
+    """
+    async with db.as_service_role() as conn:
+        bucket_name, path = await _resolve_object(conn, object_id)
+
+    if role == "service_role":
+        async with db.as_service_role() as conn:
+            try:
+                signed = await storage_service.issue_signed_url(
+                    conn,
+                    bucket_name=bucket_name,
+                    path=path,
+                    expires_in=expires_in,
+                )
+            except storage_service.StorageError as exc:
+                raise AdminError(exc.code, exc.message, exc.status) from exc
+    else:
+        claims = preview_claims(role, impersonate_sub)
+        async with db.as_role(role, claims) as conn:
+            try:
+                signed = await storage_service.issue_signed_url(
+                    conn,
+                    bucket_name=bucket_name,
+                    path=path,
+                    expires_in=expires_in,
+                )
+            except storage_service.StorageError as exc:
+                raise AdminError(exc.code, exc.message, exc.status) from exc
+
+    response = AdminSignedUrlResponse(
+        signed_url=signed.signed_url,
+        token=signed.token,
+        expires_at=signed.expires_at,
+        expires_in=signed.expires_in,
+        signed_under_role=role,
+    )
+    return response, bucket_name, path
+
+
+async def delete_object(
+    backend: StorageBackend, object_id: UUID
+) -> tuple[str, str]:
+    """Delete object metadata + bytes. Returns ``(bucket_name, path)`` for audit."""
+    async with db.as_service_role() as conn:
+        row = await conn.fetchrow(
+            """
+            select b.name as bucket_name, o.name
+            from storage.objects o
+            join storage.buckets b on b.id = o.bucket_id
+            where o.id = $1
+            """,
+            object_id,
+        )
+        if row is None:
+            raise AdminError("object_not_found", "Object not found", 404)
+        bucket_name = row["bucket_name"]
+        path = row["name"]
+        await conn.execute(
+            "delete from storage.objects where id = $1",
+            object_id,
+        )
+
+    try:
+        await backend.delete(make_object_key(bucket_name, path))
+    except BackendError:
+        # Orphaned bytes after a successful metadata delete are acceptable per
+        # the storage contract. Metadata is the authority.
+        pass
+
+    return bucket_name, path

supython/admin/api/storage.py

@@ -0,0 +1,117 @@
+import ipaddress
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Body, Depends, Request
+
+from ... import db
+from ...storage.backends import get_backend
+from .. import audit
+from ..deps import require_admin
+from ..errors import AdminError, to_http
+from ..schemas import (
+    AdminBucket,
+    AdminObjectsPage,
+    AdminSignedUrlResponse,
+    AdminSignObjectRequest,
+)
+from . import service_storage
+
+router = APIRouter(prefix="/admin/api/v1/storage", tags=["admin.storage"])
+
+
+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
+
+
+@router.get("/buckets", response_model=list[AdminBucket])
+async def list_buckets(
+    _: Annotated[UUID, Depends(require_admin)],
+) -> list[AdminBucket]:
+    async with db.as_service_role() as conn:
+        return await service_storage.list_buckets(conn)
+
+
+@router.get("/buckets/{bucket}/objects", response_model=AdminObjectsPage)
+async def list_bucket_objects(
+    bucket: str,
+    _: Annotated[UUID, Depends(require_admin)],
+    prefix: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+) -> AdminObjectsPage:
+    try:
+        async with db.as_service_role() as conn:
+            return await service_storage.list_bucket_objects(
+                conn, bucket, prefix, limit, offset
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+
+
+@router.post("/objects/{object_id}/sign", response_model=AdminSignedUrlResponse)
+async def sign_object(
+    object_id: UUID,
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+    payload: Annotated[AdminSignObjectRequest | None, Body()] = None,
+) -> AdminSignedUrlResponse:
+    body = payload or AdminSignObjectRequest()
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    try:
+        response, bucket_name, path = await service_storage.sign_object(
+            object_id,
+            body.expires_in,
+            body.role,
+            body.impersonate_sub,
+        )
+        async with db.as_service_role() as conn:
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="storage.object.sign",
+                target=str(object_id),
+                payload={
+                    "bucket": bucket_name,
+                    "path": path,
+                    "expires_in": response.expires_in,
+                    "signed_under_role": response.signed_under_role,
+                },
+                ip=ip,
+                ua=ua,
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc
+    return response
+
+
+@router.delete("/objects/{object_id}", status_code=204)
+async def delete_object(
+    object_id: UUID,
+    request: Request,
+    admin_id: Annotated[UUID, Depends(require_admin)],
+) -> None:
+    ip = _client_ip(request)
+    ua = request.headers.get("user-agent")
+    backend = get_backend()
+    try:
+        bucket_name, path = await service_storage.delete_object(backend, object_id)
+        async with db.as_service_role() as conn:
+            await audit.write(
+                conn,
+                admin_id=admin_id,
+                action="storage.object.delete",
+                target=str(object_id),
+                payload={"bucket": bucket_name, "path": path},
+                ip=ip,
+                ua=ua,
+            )
+    except AdminError as exc:
+        raise to_http(exc) from exc

supython/admin/api/system.py

@@ -0,0 +1,37 @@
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+
+from ... import db, jwks
+from ...settings import get_settings
+from ..deps import require_admin
+from ..schemas import SystemStatus, SystemVersion
+
+router = APIRouter(prefix="/admin/api/v1/system", tags=["admin.system"])
+
+
+@router.get("/status", response_model=SystemStatus)
+async def system_status(
+    _: Annotated[UUID, Depends(require_admin)],
+) -> SystemStatus:
+    settings = get_settings()
+    pool = db.get_pool()
+    jwks_doc = jwks.dump_jwks(jwks.load_verification_keyset())
+    kids = [k["kid"] for k in jwks_doc.get("keys", [])]
+    kid = kids[0] if kids else ""
+    return SystemStatus(
+        pool_size=pool.get_size(),
+        jwks_kid=kid,
+        broker=settings.realtime_enabled,
+        jobs=settings.jobs_enabled,
+    )
+
+
+@router.get("/version", response_model=SystemVersion)
+async def system_version(
+    _: Annotated[UUID, Depends(require_admin)],
+) -> SystemVersion:
+    from ... import __version__
+
+    return SystemVersion(version=__version__)

supython/admin/audit.py

@@ -0,0 +1,29 @@
+import json
+from typing import Any
+from uuid import UUID
+
+import asyncpg
+
+
+async def write(
+    conn: asyncpg.Connection,
+    *,
+    admin_id: UUID | None,
+    action: str,
+    target: str | None,
+    payload: dict[str, Any],
+    ip: str | None,
+    ua: str | None,
+) -> None:
+    await conn.execute(
+        """
+        insert into admin.admin_audit (admin_id, action, target, payload, ip, user_agent)
+        values ($1, $2, $3, $4::jsonb, $5, $6)
+        """,
+        admin_id,
+        action,
+        target,
+        json.dumps(payload),
+        ip,
+        ua,
+    )

supython/admin/deps.py

@@ -0,0 +1,22 @@
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import Cookie, HTTPException, Request, status
+
+from .. import db
+from . import session as admin_session
+
+
+async def require_admin(
+    request: Request,
+    cookie: Annotated[str | None, Cookie(alias=admin_session.SESSION_COOKIE)] = None,
+) -> UUID:
+    if not cookie:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Admin session required")
+    async with db.as_service_role() as conn:
+        resolved = await admin_session.resolve(conn, cookie)
+    if resolved is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid or expired session")
+    admin_id, _expires = resolved
+    request.state.admin_id = admin_id
+    return admin_id

supython/admin/errors.py

@@ -0,0 +1,16 @@
+from fastapi import HTTPException
+
+
+class AdminError(Exception):
+    def __init__(self, code: str, message: str, status: int = 400):
+        self.code = code
+        self.message = message
+        self.status = status
+        super().__init__(message)
+
+
+def to_http(exc: AdminError) -> HTTPException:
+    return HTTPException(
+        status_code=exc.status,
+        detail={"code": exc.code, "message": exc.message},
+    )