supython 0.5.0__py3-none-any.whl

supython/migrate.py

@@ -0,0 +1,81 @@
+"""Tiny SQL migration runner for framework DDL only.
+
+Applies every `*.sql` file shipped under ``supython/migrations`` in
+lexical order, recording each filename in ``supython.migrations`` so it
+runs exactly once. This is intentionally minimal and intentionally
+scoped: it owns the framework's own schemas (``auth``, ``storage``,
+``realtime``, ``jobs``, ``supython``), not your application's schema
+history.
+
+The framework migrations ship inside the installed wheel
+(``src/supython/migrations/``) so ``supython migrate`` works from any
+working directory — no repo checkout required.
+
+For app-level migrations, supython recommends **dbmate** (single Go
+binary, raw SQL, no Python deps) — see ``docs/migrations.md``. atlas and
+sqitch are documented as alternates. Alembic is deliberately not
+recommended (no ORM → no autogeneration → no value-add over dbmate).
+"""
+
+import asyncio
+import logging
+from pathlib import Path
+
+import asyncpg
+
+from .settings import get_settings
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MIGRATIONS_DIR = Path(__file__).resolve().parent / "migrations"
+
+
+async def _ensure_table(conn: asyncpg.Connection) -> None:
+    await conn.execute(
+        """
+        create schema if not exists supython;
+        create table if not exists supython.migrations (
+            name        text primary key,
+            applied_at  timestamptz not null default now()
+        );
+        """
+    )
+
+
+async def run_migrations(directory: Path | None = None) -> list[str]:
+    """Apply pending migrations. Returns the list of newly applied filenames."""
+    target = directory or DEFAULT_MIGRATIONS_DIR
+    if not target.exists():
+        raise FileNotFoundError(f"Migrations directory not found: {target}")
+
+    files = sorted(p for p in target.glob("*.sql"))
+    applied: list[str] = []
+
+    settings = get_settings()
+    conn = await asyncpg.connect(settings.database_url)
+    try:
+        await _ensure_table(conn)
+        existing = {
+            r["name"]
+            for r in await conn.fetch("select name from supython.migrations")
+        }
+        for path in files:
+            if path.name in existing:
+                continue
+            sql = path.read_text()
+            async with conn.transaction():
+                await conn.execute(sql)
+                await conn.execute(
+                    "insert into supython.migrations (name) values ($1)",
+                    path.name,
+                )
+            applied.append(path.name)
+            logger.info("migration applied: %s", path.name)
+    finally:
+        await conn.close()
+
+    return applied
+
+
+def run_sync(directory: Path | None = None) -> list[str]:
+    return asyncio.run(run_migrations(directory))

supython/migrations/0001_extensions_and_roles.sql

@@ -0,0 +1,46 @@
+-- Extensions and the role hierarchy that PostgREST + supython depend on.
+--
+-- Roles:
+--   authenticator   - the role PostgREST connects to the DB as (LOGIN).
+--                     It owns no tables; it switches into one of the roles
+--                     below for each request via SET ROLE.
+--   anon            - unauthenticated requests (no JWT).
+--   authenticated   - any user with a valid JWT issued by supython.
+--   service_role    - bypasses RLS; used by supython for admin tasks.
+
+create extension if not exists pgcrypto;
+-- pg_cron: required by the jobs module for SQL-level cron scheduling.
+-- The extension is declared here (not in 0007) per project convention:
+-- all extensions are registered in 0001_extensions_and_roles.sql.
+create extension if not exists pg_cron;
+
+do $$
+begin
+    if not exists (select 1 from pg_roles where rolname = 'anon') then
+        create role anon nologin noinherit;
+    end if;
+
+    if not exists (select 1 from pg_roles where rolname = 'authenticated') then
+        create role authenticated nologin noinherit;
+    end if;
+
+    if not exists (select 1 from pg_roles where rolname = 'service_role') then
+        create role service_role nologin noinherit bypassrls;
+    end if;
+
+    if not exists (select 1 from pg_roles where rolname = 'authenticator') then
+        create role authenticator with login password 'authenticator' noinherit;
+    end if;
+end
+$$;
+
+grant anon, authenticated, service_role to authenticator;
+
+grant usage on schema public to anon, authenticated, service_role;
+
+alter default privileges in schema public
+    grant all on tables to service_role;
+alter default privileges in schema public
+    grant all on sequences to service_role;
+alter default privileges in schema public
+    grant all on functions to service_role;

supython/migrations/0002_auth_schema.sql

@@ -0,0 +1,66 @@
+-- The `auth` schema mirrors Supabase's loose conventions so RLS policies
+-- written for either system tend to work in both.
+
+create extension if not exists citext;
+
+create schema if not exists auth;
+
+grant usage on schema auth to anon, authenticated, service_role;
+
+create table if not exists auth.users (
+    id                 uuid primary key default gen_random_uuid(),
+    email              citext unique not null,
+    encrypted_password text,
+    email_confirmed_at timestamptz,
+    last_sign_in_at    timestamptz,
+    raw_user_meta_data jsonb not null default '{}'::jsonb,
+    created_at         timestamptz not null default now(),
+    updated_at         timestamptz not null default now()
+);
+
+create table if not exists auth.refresh_tokens (
+    id          bigserial primary key,
+    user_id     uuid not null references auth.users (id) on delete cascade,
+    token       text unique not null,
+    parent      text,
+    revoked     boolean not null default false,
+    created_at  timestamptz not null default now()
+);
+
+create index if not exists refresh_tokens_user_id_idx
+    on auth.refresh_tokens (user_id);
+
+-- Helpers used by RLS policies. They read the JWT claims that PostgREST
+-- (or the supython service) sets via `SET LOCAL request.jwt.claims = ...`.
+create or replace function auth.uid()
+returns uuid
+language sql
+stable
+as $$
+    select nullif(
+        current_setting('request.jwt.claims', true)::jsonb ->> 'sub',
+        ''
+    )::uuid
+$$;
+
+create or replace function auth.role()
+returns text
+language sql
+stable
+as $$
+    select current_setting('request.jwt.claims', true)::jsonb ->> 'role'
+$$;
+
+create or replace function auth.email()
+returns text
+language sql
+stable
+as $$
+    select current_setting('request.jwt.claims', true)::jsonb ->> 'email'
+$$;
+
+grant execute on function auth.uid(), auth.role(), auth.email()
+    to anon, authenticated, service_role;
+
+grant all on all tables in schema auth to service_role;
+grant all on all sequences in schema auth to service_role;

supython/migrations/0003_demo_todos.sql

@@ -0,0 +1,42 @@
+-- A trivial todos table the spike uses to demonstrate the whole point:
+-- ZERO Python CRUD code. Reads, writes, filters, ordering, pagination —
+-- all served by PostgREST under RLS.
+
+create table if not exists public.todos (
+    id          uuid primary key default gen_random_uuid(),
+    user_id     uuid not null default auth.uid()
+                    references auth.users (id) on delete cascade,
+    title       text not null check (length(title) > 0),
+    done        boolean not null default false,
+    created_at  timestamptz not null default now()
+);
+
+alter table public.todos enable row level security;
+
+drop policy if exists "todos: owner can read"   on public.todos;
+drop policy if exists "todos: owner can insert" on public.todos;
+drop policy if exists "todos: owner can update" on public.todos;
+drop policy if exists "todos: owner can delete" on public.todos;
+
+create policy "todos: owner can read"
+    on public.todos for select
+    to authenticated
+    using (user_id = auth.uid());
+
+create policy "todos: owner can insert"
+    on public.todos for insert
+    to authenticated
+    with check (user_id = auth.uid());
+
+create policy "todos: owner can update"
+    on public.todos for update
+    to authenticated
+    using (user_id = auth.uid())
+    with check (user_id = auth.uid());
+
+create policy "todos: owner can delete"
+    on public.todos for delete
+    to authenticated
+    using (user_id = auth.uid());
+
+grant select, insert, update, delete on public.todos to authenticated;

supython/migrations/0004_auth_v0_2.sql

@@ -0,0 +1,47 @@
+-- v0.2 auth: OAuth identity mapping, one-time tokens (password reset / magic
+-- link / email OTP), security audit log, and index for refresh-token chain
+-- walks (reuse detection).
+
+create table if not exists auth.identities (
+    id                 uuid primary key default gen_random_uuid(),
+    user_id            uuid not null references auth.users (id) on delete cascade,
+    provider           text not null,
+    provider_user_id   text not null,
+    identity_data      jsonb not null default '{}'::jsonb,
+    created_at         timestamptz not null default now(),
+    constraint identities_provider_user_unique unique (provider, provider_user_id)
+);
+
+create table if not exists auth.one_time_tokens (
+    id           uuid primary key default gen_random_uuid(),
+    user_id      uuid not null references auth.users (id) on delete cascade,
+    type         text not null,
+    token_hash   text not null,
+    expires_at   timestamptz not null,
+    used_at      timestamptz,
+    created_at   timestamptz not null default now(),
+    constraint one_time_tokens_type_check
+        check (type in ('recover', 'magic_link', 'otp')),
+    constraint one_time_tokens_token_hash_unique unique (token_hash)
+);
+
+create table if not exists auth.audit_log (
+    id         uuid primary key default gen_random_uuid(),
+    user_id    uuid references auth.users (id) on delete set null,
+    event      text not null,
+    ip         inet,
+    ua         text,
+    payload    jsonb not null default '{}'::jsonb,
+    created_at timestamptz not null default now()
+);
+
+create index if not exists refresh_tokens_parent_idx
+    on auth.refresh_tokens (parent);
+
+alter table if exists auth.identities owner to service_role;
+alter table if exists auth.one_time_tokens owner to service_role;
+alter table if exists auth.audit_log owner to service_role;
+
+grant all on table auth.identities to service_role;
+grant all on table auth.one_time_tokens to service_role;
+grant all on table auth.audit_log to service_role;

supython/migrations/0005_storage_schema.sql

@@ -0,0 +1,117 @@
+-- v0.3 storage: logical buckets and object metadata with RLS. Bytes live in a
+-- backend (local/S3); this schema is the authority for who may read/write.
+
+create schema if not exists storage;
+
+grant usage on schema storage to anon, authenticated, service_role;
+
+create table if not exists storage.buckets (
+    id                 uuid primary key default gen_random_uuid(),
+    name               text unique not null
+        check (name ~ '^[a-z0-9][a-z0-9_-]{0,62}$'),
+    owner              uuid references auth.users (id) on delete set null,
+    public             boolean not null default false,
+    file_size_limit    bigint,
+    allowed_mime_types text[],
+    created_at         timestamptz not null default now(),
+    updated_at         timestamptz not null default now()
+);
+
+create table if not exists storage.objects (
+    id          uuid primary key default gen_random_uuid(),
+    bucket_id   uuid not null references storage.buckets (id) on delete cascade,
+    name        text not null,
+    owner       uuid not null default auth.uid()
+        references auth.users (id) on delete cascade,
+    size        bigint not null,
+    mime_type   text,
+    etag        text,
+    metadata    jsonb not null default '{}'::jsonb,
+    created_at  timestamptz not null default now(),
+    updated_at  timestamptz not null default now(),
+    constraint objects_bucket_name_unique unique (bucket_id, name)
+);
+
+create index if not exists objects_owner_idx on storage.objects (owner);
+
+alter table if exists storage.buckets owner to service_role;
+alter table if exists storage.objects owner to service_role;
+
+grant all on all tables in schema storage to service_role;
+
+alter table storage.buckets enable row level security;
+alter table storage.objects enable row level security;
+
+drop policy if exists "buckets: any authed can read" on storage.buckets;
+drop policy if exists "buckets: anon can read public" on storage.buckets;
+drop policy if exists "buckets: owner can insert" on storage.buckets;
+drop policy if exists "buckets: owner can update" on storage.buckets;
+drop policy if exists "buckets: owner can delete" on storage.buckets;
+
+create policy "buckets: any authed can read"
+    on storage.buckets for select
+    to authenticated
+    using (true);
+
+-- Lets anon evaluate `bucket_id in (select id from storage.buckets where public)`
+-- when the objects policy runs; without this, anon has no bucket rows under RLS.
+create policy "buckets: anon can read public"
+    on storage.buckets for select
+    to anon
+    using (public);
+
+create policy "buckets: owner can insert"
+    on storage.buckets for insert
+    to authenticated
+    with check (owner = auth.uid());
+
+create policy "buckets: owner can update"
+    on storage.buckets for update
+    to authenticated
+    using (owner = auth.uid())
+    with check (owner = auth.uid());
+
+create policy "buckets: owner can delete"
+    on storage.buckets for delete
+    to authenticated
+    using (owner = auth.uid());
+
+drop policy if exists "objects: owner can read" on storage.objects;
+drop policy if exists "objects: owner can insert" on storage.objects;
+drop policy if exists "objects: owner can update" on storage.objects;
+drop policy if exists "objects: owner can delete" on storage.objects;
+drop policy if exists "objects: public bucket read" on storage.objects;
+
+create policy "objects: owner can read"
+    on storage.objects for select
+    to authenticated
+    using (owner = auth.uid());
+
+create policy "objects: owner can insert"
+    on storage.objects for insert
+    to authenticated
+    with check (owner = auth.uid());
+
+create policy "objects: owner can update"
+    on storage.objects for update
+    to authenticated
+    using (owner = auth.uid())
+    with check (owner = auth.uid());
+
+create policy "objects: owner can delete"
+    on storage.objects for delete
+    to authenticated
+    using (owner = auth.uid());
+
+create policy "objects: public bucket read"
+    on storage.objects for select
+    to anon, authenticated
+    using (
+        bucket_id in (
+            select id from storage.buckets where public
+        )
+    );
+
+grant select, insert, update, delete on storage.buckets to authenticated;
+grant select, insert, update, delete on storage.objects to authenticated;
+grant select on storage.buckets, storage.objects to anon;

supython/migrations/0006_realtime_schema.sql

@@ -0,0 +1,206 @@
+-- v0.4 realtime: in-process broker + Phoenix-channels subset over WebSocket.
+--
+-- Creates the realtime schema with:
+--   realtime.enabled_tables  — registry of tables opted into change events
+--   realtime.fire_notify()   — AFTER INSERT/UPDATE/DELETE trigger function
+--   realtime.enable(regclass, text) — management helper (service_role only)
+--
+-- The broker listens on the pg_notify channel 'realtime:changes'.  The
+-- channel name is also stored in settings.realtime_notify_channel; both
+-- must agree.  Changing the channel requires updating this trigger and the
+-- application setting together.
+
+create schema if not exists realtime;
+
+grant usage on schema realtime to anon, authenticated, service_role;
+
+-- ─── registry ────────────────────────────────────────────────────────────────
+
+create table if not exists realtime.enabled_tables (
+    schema_name   text        not null,
+    table_name    text        not null,
+    pk_columns    text[]      not null,
+    -- owner_column is used for DELETE fan-out under RLS: when a DELETE fires
+    -- the row is gone, so the broker falls back to comparing
+    -- old_record-><owner_column> against the subscriber's auth.uid().
+    -- null means DELETEs are delivered only to service_role subscribers.
+    owner_column  text,
+    created_at    timestamptz not null default now(),
+    primary key (schema_name, table_name)
+);
+
+alter table realtime.enabled_tables owner to service_role;
+
+alter table realtime.enabled_tables enable row level security;
+
+-- Any authenticated or anonymous client may read the registry to validate
+-- their phx_join config.  Writes flow exclusively through realtime.enable()
+-- which is security definer and reserved for service_role callers.
+drop policy if exists "enabled_tables: anyone can read" on realtime.enabled_tables;
+
+create policy "enabled_tables: anyone can read"
+    on realtime.enabled_tables for select
+    to anon, authenticated, service_role
+    using (true);
+
+grant select on realtime.enabled_tables to anon, authenticated;
+grant all    on realtime.enabled_tables to service_role;
+
+-- ─── trigger function ─────────────────────────────────────────────────────────
+
+-- fire_notify() is attached to every table registered via realtime.enable().
+-- It emits one pg_notify per changed row on the 'realtime:changes' channel.
+--
+-- Payload shape (JSON object; broker enriches nothing — all data lives here):
+--   schema           text        — tg_table_schema
+--   table            text        — tg_table_name
+--   type             text        — INSERT | UPDATE | DELETE
+--   commit_timestamp text        — ISO-8601 UTC, e.g. "2026-04-20T12:34:56Z"
+--   columns          jsonb array — [{name, type}, …] from pg_attribute cache
+--   record           jsonb | null — NEW row for INSERT / UPDATE, null for DELETE
+--   old_record       jsonb | null — OLD row for UPDATE / DELETE, null for INSERT
+--
+-- security definer so the function always runs with enough privilege to read
+-- pg_attribute and call pg_notify regardless of the invoking role.
+create or replace function realtime.fire_notify()
+returns trigger language plpgsql security definer as $$
+declare
+    v_columns jsonb;
+    v_payload jsonb;
+begin
+    -- column metadata from the shared-buffer catalog cache (very fast)
+    select jsonb_agg(
+               jsonb_build_object(
+                   'name', a.attname,
+                   'type', format_type(a.atttypid, a.atttypmod)
+               )
+               order by a.attnum
+           )
+    into v_columns
+    from pg_attribute a
+    where a.attrelid = tg_relid
+      and a.attnum   > 0
+      and not a.attisdropped;
+
+    v_payload := jsonb_build_object(
+        'schema',           tg_table_schema,
+        'table',            tg_table_name,
+        'type',             tg_op,
+        'commit_timestamp', to_char(
+                                now() at time zone 'utc',
+                                'YYYY-MM-DD"T"HH24:MI:SS"Z"'
+                            ),
+        'columns',          coalesce(v_columns, '[]'::jsonb),
+        'record',           case
+                                when tg_op in ('INSERT', 'UPDATE') then to_jsonb(new)
+                                else null
+                            end,
+        'old_record',       case
+                                when tg_op in ('UPDATE', 'DELETE') then to_jsonb(old)
+                                else null
+                            end
+    );
+
+    perform pg_notify('realtime:changes', v_payload::text);
+
+    -- AFTER trigger; return value is ignored for row-level AFTER triggers,
+    -- but returning null is the conventional choice.
+    return null;
+end $$;
+
+-- ─── enable() helper ─────────────────────────────────────────────────────────
+
+-- realtime.enable(tbl, owner_column):
+--   1. Resolves the schema + table name and primary-key columns from
+--      the system catalog.
+--   2. Upserts a row in realtime.enabled_tables.
+--   3. Drops then recreates the realtime_notify AFTER trigger on the table.
+--
+-- Idempotent: safe to call multiple times; re-registers pk_columns and
+-- owner_column on conflict.
+--
+-- owner_column defaults to 'user_id'.  If the column does not exist on the
+-- target table, owner_column is silently set to null (opt-out of the
+-- DELETE short-circuit path; only service_role listeners receive DELETEs).
+--
+-- Raises an exception if the table has no primary key.
+create or replace function realtime.enable(
+    tbl          regclass,
+    owner_column text default 'user_id'
+)
+returns void language plpgsql security definer as $$
+declare
+    v_schema       text;
+    v_table        text;
+    v_pk_columns   text[];
+    v_has_owner    boolean;
+    v_trigger_name text := 'realtime_notify';
+begin
+    -- resolve schema + table name
+    select n.nspname, c.relname
+    into strict v_schema, v_table
+    from pg_class     c
+    join pg_namespace n on n.oid = c.relnamespace
+    where c.oid = tbl;
+
+    -- collect PK columns in index-key order using unnest+ordinality so the
+    -- order matches pg_index.indkey exactly (array_position on int2vector is
+    -- not reliable across all PG versions)
+    select array_agg(a.attname order by k.ord)
+    into v_pk_columns
+    from pg_index ix
+    cross join lateral unnest(ix.indkey) with ordinality as k(attnum, ord)
+    join pg_attribute a
+         on  a.attrelid = ix.indrelid
+         and a.attnum   = k.attnum
+         and a.attnum   > 0
+         and not a.attisdropped
+    where ix.indrelid   = tbl
+      and ix.indisprimary;
+
+    if v_pk_columns is null then
+        raise exception
+            'table % has no primary key — realtime.enable() requires a primary key',
+            tbl::text;
+    end if;
+
+    -- silently clear owner_column when the column is absent on the table
+    if owner_column is not null then
+        select exists(
+            select 1
+            from pg_attribute
+            where attrelid   = tbl
+              and attname     = owner_column
+              and attnum      > 0
+              and not attisdropped
+        ) into v_has_owner;
+
+        if not v_has_owner then
+            owner_column := null;
+        end if;
+    end if;
+
+    -- upsert the registry entry
+    insert into realtime.enabled_tables (schema_name, table_name, pk_columns, owner_column)
+    values (v_schema, v_table, v_pk_columns, owner_column)
+    on conflict (schema_name, table_name) do update
+        set pk_columns   = excluded.pk_columns,
+            owner_column = excluded.owner_column;
+
+    -- (re-)attach the trigger; drop first for idempotency
+    execute format(
+        'drop trigger if exists %I on %s',
+        v_trigger_name, tbl
+    );
+
+    execute format(
+        'create trigger %I
+             after insert or update or delete on %s
+             for each row execute function realtime.fire_notify()',
+        v_trigger_name, tbl
+    );
+end $$;
+
+-- Only service_role may opt tables in to realtime.  The trigger function is
+-- security definer and is invoked automatically; no explicit grant is needed.
+grant execute on function realtime.enable(regclass, text) to service_role;