supython 0.1.0__py3-none-any.whl

supython/gen/types_ts.py

@@ -0,0 +1,365 @@
+"""Render a TypeScript ``Database`` interface from Postgres schema introspection.
+
+Public entry point: :func:`render_types_ts`. The returned string is a full
+TypeScript module exporting a ``Database`` interface compatible with
+``@supabase/postgrest-js`` and ``@supython/sdk``.
+
+The generator opens its own asyncpg connection and closes it before returning;
+it does not depend on the supython service running.
+"""
+
+from datetime import UTC, datetime
+
+import asyncpg
+
+from ..settings import get_settings
+from ._introspect import (
+    _fetch_columns,
+    _fetch_enums,
+    _fetch_relationships,
+    _fetch_tables,
+)
+from .types_py import _class_name
+
+_TS_TYPE_MAP: dict[str, str] = {
+    # strings
+    "text": "string",
+    "varchar": "string",
+    "bpchar": "string",
+    "char": "string",
+    "citext": "string",
+    "name": "string",
+    "inet": "string",
+    "cidr": "string",
+    "macaddr": "string",
+    "tsvector": "string",
+    "tsquery": "string",
+    "bit": "string",
+    "varbit": "string",
+    "uuid": "string",
+    "bytea": "string",
+    "oid": "string",
+    # numbers
+    "int2": "number",
+    "int4": "number",
+    "int8": "number",
+    "float4": "number",
+    "float8": "number",
+    "numeric": "number",
+    "money": "number",
+    # boolean
+    "bool": "boolean",
+    # dates/times as ISO strings
+    "timestamptz": "string",
+    "timestamp": "string",
+    "date": "string",
+    "time": "string",
+    "timetz": "string",
+    "interval": "string",
+    # json
+    "json": "Record<string, unknown>",
+    "jsonb": "Record<string, unknown>",
+}
+
+# TypeScript reserved words that cannot be used as bare identifiers
+_TS_KEYWORDS: set[str] = {
+    # strict mode reserved
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "null",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "implements",
+    "interface",
+    "let",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "static",
+    "yield",
+    "await",
+    "abstract",
+    "as",
+    "asserts",
+    "async",
+    "constructor",
+    "declare",
+    "from",
+    "get",
+    "infer",
+    "intrinsic",
+    "is",
+    "keyof",
+    "module",
+    "namespace",
+    "never",
+    "of",
+    "readonly",
+    "require",
+    "set",
+    "type",
+    "unique",
+    "unknown",
+}
+
+
+def _safe_ts_col_name(name: str) -> str:
+    """Append _ if column name is a TS reserved word."""
+    if name in _TS_KEYWORDS:
+        return f"{name}_"
+    return name
+
+
+def _pg_to_ts(
+    udt_schema: str,
+    udt_name: str,
+    data_type: str,
+    element: tuple[str, str, str] | None,
+    enum_types: set[tuple[str, str]],
+) -> str:
+    """Return TypeScript type annotation string."""
+    if data_type == "ARRAY" and element is not None:
+        elem_type = _pg_to_ts(element[1], element[2], element[0], None, enum_types)
+        return f"{elem_type}[]"
+
+    if data_type == "USER-DEFINED" and (udt_schema, udt_name) in enum_types:
+        # Enum type - will be rendered as "schema.name" union type
+        return f"{udt_schema}.{udt_name}"
+
+    if udt_name in _TS_TYPE_MAP:
+        return _TS_TYPE_MAP[udt_name]
+
+    return "unknown"
+
+
+def _has_default(col: asyncpg.Record) -> bool:
+    """Return True if column has a default value, is generated, or is identity."""
+    return (
+        col["column_default"] is not None
+        or col["is_generated"] != "NEVER"
+        or col["is_identity"] == "YES"
+    )
+
+
+def _render_table_shape(
+    cols: list[asyncpg.Record],
+    enum_types: set[tuple[str, str]],
+    relationships: list[dict],
+) -> tuple[list[str], list[str], list[str], list[str]]:
+    """Render Row, Insert, Update, and Relationships lines for a table.
+
+    Returns (row_lines, insert_lines, update_lines, relationships_lines).
+    """
+    row_lines: list[str] = []
+    insert_lines: list[str] = []
+    update_lines: list[str] = []
+
+    for c in cols:
+        element = None
+        if c["element_data_type"]:
+            element = (
+                c["element_data_type"],
+                c["element_udt_schema"],
+                c["element_udt_name"],
+            )
+        ts_type = _pg_to_ts(
+            c["udt_schema"],
+            c["udt_name"],
+            c["data_type"],
+            element,
+            enum_types,
+        )
+
+        col_name = _safe_ts_col_name(c["column_name"])
+        nullable = c["is_nullable"] == "YES"
+        has_default = _has_default(c)
+
+        # Row: required if NOT NULL
+        row_optional = nullable
+        row_lines.append(
+            f"        {col_name}{'?' if row_optional else ''}: {ts_type};"
+        )
+
+        # Insert: required if NOT NULL and no default
+        insert_optional = nullable or has_default
+        insert_lines.append(
+            f"        {col_name}{'?' if insert_optional else ''}: {ts_type};"
+        )
+
+        # Update: always optional
+        update_lines.append(f"        {col_name}?: {ts_type};")
+
+    # Relationships
+    rel_lines: list[str] = []
+    if relationships:
+        for rel in relationships:
+            columns = rel["columns"]
+            referenced = rel["referencedRelation"]
+            ref_cols = rel["referencedColumns"]
+            rel_lines.append("      {")
+            fk_name = rel["foreignKeyName"]
+            rel_lines.append(f'        foreignKeyName: "{fk_name}";')
+            cols_str = ", ".join(repr(c) for c in columns)
+            rel_lines.append(f"        columns: [{cols_str}];")
+            rel_lines.append(f'        referencedRelation: "{referenced}";')
+            ref_str = ", ".join(repr(c) for c in ref_cols)
+            rel_lines.append(f"        referencedColumns: [{ref_str}];")
+            rel_lines.append("      },")
+
+    return row_lines, insert_lines, update_lines, rel_lines
+
+
+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]],
+    relationships: dict[tuple[str, str], list[dict]],
+) -> str:
+    """Render the full TypeScript Database interface."""
+    # Build enum type names set
+    enum_types: set[tuple[str, str]] = set(enums.keys())
+
+    # Group tables by schema
+    by_schema: dict[str, list[tuple[str, str]]] = {}
+    for schema, table in tables:
+        by_schema.setdefault(schema, []).append((schema, table))
+
+    body: list[str] = []
+
+    # Emit enum type aliases at top level
+    for (schema, name), labels in sorted(enums.items()):
+        enum_name = _class_name(schema, name, schemas)
+        label_union = " | ".join(f'"{lbl}"' for lbl in labels)
+        body.append(f"export type {enum_name} = {label_union};")
+        body.append("")
+
+    # Start Database interface
+    body.append("export interface Database {")
+
+    for schema in sorted(schemas):
+        schema_tables = by_schema.get(schema, [])
+
+        body.append(f"  {schema}: {{")
+
+        # Tables section
+        body.append("    Tables: {")
+        for s, table in schema_tables:
+            cols = columns.get((s, table), [])
+            if not cols:
+                continue
+
+            rels = relationships.get((s, table), [])
+
+            row_lines, insert_lines, update_lines, rel_lines = _render_table_shape(
+                cols, enum_types, rels
+            )
+
+            body.append(f"      {table}: {{")
+            body.append("        Row: {")
+            body.extend(row_lines)
+            body.append("        };")
+            body.append("        Insert: {")
+            body.extend(insert_lines)
+            body.append("        };")
+            body.append("        Update: {")
+            body.extend(update_lines)
+            body.append("        };")
+
+            if rel_lines:
+                body.append("        Relationships: [")
+                body.extend(rel_lines)
+                body.append("        ];")
+
+            body.append("      };")
+        body.append("    };")
+
+        # Views section - deferred (needs table_type tracking to separate
+        # from BASE TABLE entries already rendered in Tables above)
+        body.append("    Views: {")
+        body.append("    };")
+
+        # Functions section (RPC) - deferred
+        body.append("    Functions: {")
+        body.append("    };")
+
+        # Enums section - export as type aliases at schema level
+        schema_enums = [
+            (s, n) for s, n in enums if s == schema
+        ]
+        if schema_enums:
+            body.append("    Enums: {")
+            for s, name in sorted(schema_enums):
+                enum_name = _class_name(s, name, schemas)
+                labels = enums[(s, name)]
+                label_union = " | ".join(f'"{lbl}"' for lbl in labels)
+                body.append(f"      {name}: {label_union};")
+            body.append("    };")
+        else:
+            body.append("    Enums: {")
+            body.append("    };")
+
+        body.append("  };")
+
+    body.append("}")
+
+    # Build final output
+    lines: list[str] = []
+    lines.append("// Generated by `supython gen types --lang ts`. Do not edit.")
+    lines.append("//")
+    lines.append(f"// Schemas: {', '.join(schemas)}")
+    lines.append(f"// Generated at: {datetime.now(UTC).isoformat()}")
+    lines.append("")
+    lines.extend(body)
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+async def render_types_ts(schemas: list[str]) -> str:
+    """Connect to ``DATABASE_URL`` and return a rendered TypeScript ``Database`` interface."""
+    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)
+        relationships = await _fetch_relationships(conn, schemas)
+    finally:
+        await conn.close()
+    return _render(schemas, enums, tables, columns, relationships)
+
+
+__all__ = ["render_types_ts"]

supython/health.py

@@ -0,0 +1,229 @@
+"""Deep health probes: /livez, /readyz, /health."""
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+from time import perf_counter
+from typing import Any
+
+import httpx
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from . import __version__, db
+from .settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["meta"])
+CHECK_TIMEOUT_S = 2.0
+WORKER_HEARTBEAT_MAX_AGE_S = 30.0
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class CheckResult(BaseModel):
+    status: str  # "ok" | "fail"
+    detail: str | None = None
+    latency_ms: float | None = None
+
+
+class ReadyzResponse(BaseModel):
+    status: str  # "ok" | "fail"
+    checks: dict[str, CheckResult]
+
+
+class HealthResponse(BaseModel):
+    status: str
+    version: str
+    checks: dict[str, CheckResult]
+    postgrest_url: str
+    timestamp: str
+
+
+class LivezResponse(BaseModel):
+    status: str
+
+
+# ---------------------------------------------------------------------------
+# Check functions (pure async, no FastAPI deps)
+# ---------------------------------------------------------------------------
+
+
+async def _check_database() -> CheckResult:
+    """Run select 1 with one total timeout."""
+    started = perf_counter()
+    try:
+        async with asyncio.timeout(CHECK_TIMEOUT_S):
+            async with db.acquire() as conn:
+                await conn.fetchval("select 1")
+    except TimeoutError:
+        return CheckResult(status="fail", detail="timeout")
+    except Exception as exc:
+        return CheckResult(status="fail", detail=str(exc))
+    elapsed = (perf_counter() - started) * 1000
+    return CheckResult(status="ok", latency_ms=round(elapsed, 1))
+
+
+async def _check_postgrest() -> CheckResult:
+    """HEAD / with one total timeout."""
+    settings = get_settings()
+    started = perf_counter()
+    try:
+        async with asyncio.timeout(CHECK_TIMEOUT_S):
+            async with httpx.AsyncClient(timeout=CHECK_TIMEOUT_S) as client:
+                resp = await client.head(f"{settings.postgrest_url.rstrip('/')}/")
+        if resp.status_code >= 500:
+            return CheckResult(
+                status="fail",
+                detail=f"postgrest_status={resp.status_code}",
+            )
+    except TimeoutError:
+        return CheckResult(status="fail", detail="timeout")
+    except Exception as exc:
+        return CheckResult(status="fail", detail=str(exc))
+    elapsed = (perf_counter() - started) * 1000
+    return CheckResult(status="ok", latency_ms=round(elapsed, 1))
+
+
+async def _check_broker(broker: Any | None) -> CheckResult:
+    """Broker listener task alive and connection open."""
+    if broker is None:
+        return CheckResult(status="fail", detail="broker_not_started")
+    try:
+        async with asyncio.timeout(CHECK_TIMEOUT_S):
+            if not broker.is_healthy:
+                return CheckResult(status="fail", detail="listener_not_ready")
+            connection_count = broker.connection_count
+    except TimeoutError:
+        return CheckResult(status="fail", detail="timeout")
+    except Exception as exc:
+        return CheckResult(status="fail", detail=str(exc))
+    return CheckResult(status="ok", detail=f"connections={connection_count}")
+
+
+async def _check_worker() -> CheckResult:
+    """Check freshness of the newest worker heartbeat row."""
+    started = perf_counter()
+    try:
+        async with asyncio.timeout(CHECK_TIMEOUT_S):
+            async with db.as_service_role() as conn:
+                row = await conn.fetchrow(
+                    """
+                    select
+                        count(*)::int as workers,
+                        coalesce(sum(inflight), 0)::int as inflight,
+                        extract(epoch from now() - max(last_heartbeat))::float as age_s
+                    from jobs.worker_heartbeats
+                    """
+                )
+    except TimeoutError:
+        return CheckResult(status="fail", detail="timeout")
+    except Exception as exc:
+        return CheckResult(status="fail", detail=str(exc))
+
+    if row is None or row["workers"] == 0 or row["age_s"] is None:
+        return CheckResult(status="fail", detail="no_worker_heartbeat")
+
+    age_s = float(row["age_s"])
+    if age_s > WORKER_HEARTBEAT_MAX_AGE_S:
+        return CheckResult(status="fail", detail=f"heartbeat_stale age_s={age_s:.1f}")
+
+    elapsed = (perf_counter() - started) * 1000
+    return CheckResult(
+        status="ok",
+        detail=f"workers={row['workers']} inflight={row['inflight']} age_s={age_s:.1f}",
+        latency_ms=round(elapsed, 1),
+    )
+
+
+async def _check_pg_cron() -> CheckResult:
+    """pg_cron extension present and cron.job readable."""
+    started = perf_counter()
+    try:
+        async with asyncio.timeout(CHECK_TIMEOUT_S):
+            async with db.as_service_role() as conn:
+                has_ext = await conn.fetchval(
+                    "select exists(select 1 from pg_extension where extname = 'pg_cron')"
+                )
+                if not has_ext:
+                    return CheckResult(status="fail", detail="pg_cron_extension_missing")
+                count = await conn.fetchval("select count(*) from cron.job")
+    except TimeoutError:
+        return CheckResult(status="fail", detail="timeout")
+    except Exception as exc:
+        return CheckResult(status="fail", detail=str(exc))
+    elapsed = (perf_counter() - started) * 1000
+    return CheckResult(
+        status="ok",
+        detail=f"scheduled_jobs={count}",
+        latency_ms=round(elapsed, 1),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+
+async def run_checks(request: Request) -> dict[str, CheckResult]:
+    """Run all applicable checks concurrently and return results."""
+    settings = get_settings()
+    app_state = request.app.state
+
+    coros: dict[str, Any] = {
+        "database": _check_database(),
+        "postgrest": _check_postgrest(),
+    }
+    if settings.realtime_enabled:
+        coros["broker"] = _check_broker(getattr(app_state, "broker", None))
+    if settings.jobs_enabled:
+        coros["worker"] = _check_worker()
+        if settings.jobs_cron_backend == "pg_cron":
+            coros["pg_cron"] = _check_pg_cron()
+
+    # Gather all checks concurrently
+    names = list(coros.keys())
+    results = await asyncio.gather(*coros.values())
+    return dict(zip(names, results, strict=True))
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/livez", response_model=LivezResponse)
+async def livez() -> LivezResponse:
+    return LivezResponse(status="ok")
+
+
+@router.get("/readyz")
+async def readyz(request: Request) -> JSONResponse:
+    checks = await run_checks(request)
+    all_ok = all(c.status == "ok" for c in checks.values())
+    body = ReadyzResponse(
+        status="ok" if all_ok else "fail",
+        checks=checks,
+    )
+    return JSONResponse(
+        content=body.model_dump(mode="json"),
+        status_code=200 if all_ok else 503,
+    )
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health(request: Request) -> HealthResponse:
+    settings = get_settings()
+    checks = await run_checks(request)
+    all_ok = all(c.status == "ok" for c in checks.values())
+    return HealthResponse(
+        status="ok" if all_ok else "degraded",
+        version=__version__,
+        checks=checks,
+        postgrest_url=settings.postgrest_url,
+        timestamp=datetime.now(UTC).isoformat(),
+    )

supython/hooks.py

@@ -0,0 +1,117 @@
+"""Generic hook system for supython lifecycle events.
+
+Provides ``on(event, fn)`` to register a handler and ``fire(event, *args)``
+to invoke all registered handlers for that event in registration order.
+
+The ``fn=None`` default on ``on()`` makes both ``@app.on_signup`` (bare)
+and ``@app.on_signup()`` (called) work correctly.
+
+``HookCtx`` / ``build_hook_ctx`` live here rather than in ``jobs/context.py``
+so feature modules (auth, storage, realtime, jobs, ...) share one hook
+contract. Keeping the type in ``hooks`` also breaks the ``auth → jobs``
+import edge that would otherwise couple auth to the jobs package.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from collections.abc import Awaitable, Callable, Coroutine
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover
+    import asyncpg
+
+    from .mailer import EmailBackend
+    from .settings import Settings
+
+logger = logging.getLogger(__name__)
+
+_handlers: dict[str, list[Callable[..., Coroutine[Any, Any, None]]]] = defaultdict(list)
+
+
+def on(
+    event: str,
+    fn: Callable[..., Coroutine[Any, Any, None]] | None = None,
+) -> Callable[..., Coroutine[Any, Any, None]]:
+    """Register an async handler for *event*.
+
+    Usage::
+
+        @hooks.on("signup")
+        async def on_signup(user, ctx):
+            ...
+
+    Or imperatively::
+
+        hooks.on("signup", my_handler)
+    """
+
+    def _register(
+        f: Callable[..., Coroutine[Any, Any, None]],
+    ) -> Callable[..., Coroutine[Any, Any, None]]:
+        _handlers[event].append(f)
+        return f
+
+    if fn is not None:
+        return _register(fn)
+    return _register
+
+
+async def fire(event: str, *args: Any, **kwargs: Any) -> None:
+    """Invoke all registered handlers for *event* in order.
+
+    Exceptions are logged but do not prevent subsequent handlers from running.
+    """
+    for handler in _handlers.get(event, []):
+        try:
+            await handler(*args, **kwargs)
+        except Exception:
+            logger.exception("hooks.fire error in %r handler %r", event, handler)
+
+
+def reset() -> None:
+    _handlers.clear()
+
+
+@dataclass
+class HookCtx:
+    """Value passed to hook handlers (e.g. ``on_signup``).
+
+    Smaller than ``jobs.JobCtx`` and ``functions.Ctx`` on purpose: a hook
+    fires inline on the request/worker path and should only reach for the
+    things every lifecycle event is expected to need — the role-scoped DB
+    connection, settings, a mailer, and a logger. Anything heavier belongs
+    in an enqueued job.
+    """
+
+    db: asyncpg.Connection
+    settings: Settings
+    send_email: Callable[..., Awaitable[None]]
+    logger: logging.Logger
+
+
+def build_hook_ctx(
+    *,
+    conn: asyncpg.Connection,
+    settings: Settings | None = None,
+    mailer: EmailBackend | None = None,
+) -> HookCtx:
+    """Assemble a ``HookCtx`` from a role-scoped connection.
+
+    The caller is expected to have entered ``db.as_role(...)`` already so
+    that ``conn`` carries the intended RLS posture; this factory does not
+    switch roles.
+    """
+    from .functions.context import _make_send_email
+    from .mailer import get_mailer
+    from .settings import get_settings
+
+    s = settings or get_settings()
+    return HookCtx(
+        db=conn,
+        settings=s,
+        send_email=_make_send_email(mailer or get_mailer()),
+        logger=logging.getLogger("supython.hooks"),
+    )