supython 0.1.0__py3-none-any.whl

supython/migrations/0007_jobs_schema.sql

@@ -0,0 +1,254 @@
+-- v0.5 jobs: durable job queue with idempotency, bounded zombie reclaim, and
+-- cron scheduling metadata.
+--
+-- Creates:
+--   jobs schema (owned by service_role)
+--   jobs.jobs               — main queue table
+--   jobs.cron_schedules     — cron schedule metadata
+--   jobs.enqueue()          — idempotent insert, returns (job, is_new)
+--   jobs.claim_next()       — SKIP LOCKED poll + bounded zombie reclaim
+--   Partial unique index on idempotency_key
+--   4-policy RLS on jobs.jobs
+--   pg_cron grants for service_role (when the extension is installed)
+--
+-- Per B5: execute grant on jobs.enqueue is service_role only.
+-- Per B9: claim_next reclaims zombies older than visibility_timeout_ms.
+-- Per B6: enqueue returns TABLE(job jobs.jobs, is_new boolean).
+
+create schema if not exists jobs;
+
+grant usage on schema jobs to anon, authenticated, service_role;
+
+-- ─── pg_cron grants ──────────────────────────────────────────────────────────
+--
+-- ``sync_pg_cron`` runs as ``service_role`` and needs to call
+-- ``cron.schedule`` / ``cron.unschedule``. Without these grants the pg_cron
+-- path raises ``InsufficientPrivilegeError``. The block is conditional so
+-- this migration still applies cleanly on managed Postgres without pg_cron.
+
+do $$
+begin
+    if exists (select 1 from pg_extension where extname = 'pg_cron') then
+        execute 'grant usage on schema cron to service_role';
+        execute 'grant select on all tables in schema cron to service_role';
+        execute 'grant execute on function cron.schedule(text, text, text) to service_role';
+        execute 'grant execute on function cron.unschedule(text) to service_role';
+    end if;
+end $$;
+
+-- ─── jobs.jobs ────────────────────────────────────────────────────────────────
+
+create table if not exists jobs.jobs (
+    id              uuid primary key default gen_random_uuid(),
+    name            text            not null,
+    version         int             not null default 1,
+    payload         jsonb           not null default '{}',
+    queue           text            not null default 'default',
+    idempotency_key text,
+    user_id         uuid            references auth.users (id) on delete cascade,
+    status          text            not null default 'queued'
+                        check (status in ('queued', 'running', 'succeeded', 'failed', 'cancelled')),
+    attempts        int             not null default 0,
+    max_attempts    int             not null default 3,
+    backoff         text            not null default 'exponential'
+                        check (backoff in ('exponential', 'linear', 'constant')),
+    backoff_base_s  float           not null default 5.0,
+    backoff_max_s   float           not null default 300.0,
+    run_at          timestamptz     not null default now(),
+    locked_at       timestamptz,
+    locked_by       text,
+    role            text            not null default 'service_role',
+    claims_from     text,
+    finished_at     timestamptz,
+    created_at      timestamptz     not null default now()
+);
+
+alter table jobs.jobs owner to service_role;
+
+-- idempotency: at most one queued/running job per key
+create unique index if not exists jobs_jobs_idempotency_key_idx
+    on jobs.jobs (idempotency_key)
+    where idempotency_key is not null
+      and status in ('queued', 'running');
+
+-- index for user-scoped queries
+create index if not exists jobs_jobs_user_id_idx
+    on jobs.jobs (user_id)
+    where user_id is not null;
+
+-- ─── RLS ─────────────────────────────────────────────────────────────────────
+
+alter table jobs.jobs enable row level security;
+
+drop policy if exists "jobs: owner can read"   on jobs.jobs;
+drop policy if exists "jobs: owner can insert" on jobs.jobs;
+drop policy if exists "jobs: owner can update" on jobs.jobs;
+drop policy if exists "jobs: owner can delete" on jobs.jobs;
+
+create policy "jobs: owner can read"
+    on jobs.jobs for select to authenticated
+    using (user_id = auth.uid());
+
+create policy "jobs: owner can insert"
+    on jobs.jobs for insert to authenticated
+    with check (user_id = auth.uid());
+
+create policy "jobs: owner can update"
+    on jobs.jobs for update to authenticated
+    using (user_id = auth.uid())
+    with check (user_id = auth.uid());
+
+create policy "jobs: owner can delete"
+    on jobs.jobs for delete to authenticated
+    using (user_id = auth.uid());
+
+grant select, insert, update, delete on jobs.jobs to authenticated;
+
+-- ─── jobs.cron_schedules ─────────────────────────────────────────────────────
+
+create table if not exists jobs.cron_schedules (
+    id              uuid primary key default gen_random_uuid(),
+    name            text            not null unique,
+    cron_expr       text            not null,
+    job_name        text            not null,
+    job_version     int             not null default 1,
+    payload         jsonb           not null default '{}',
+    queue           text            not null default 'default',
+    enabled         boolean         not null default true,
+    last_fire_at    timestamptz,
+    created_at      timestamptz     not null default now()
+);
+
+alter table jobs.cron_schedules owner to service_role;
+
+-- ─── jobs.enqueue ────────────────────────────────────────────────────────────
+--
+-- Idempotent enqueue. If an idempotency_key is provided and a queued/running
+-- row already exists with that key, the existing row is returned with
+-- is_new = false. Otherwise a new row is inserted and is_new = true.
+--
+-- The "fresh insert" path is split into a CTE so we never need to reference
+-- a system column (``xmax = 0``) after moving the row into a local variable —
+-- the idempotency short-circuit above returns before the INSERT, so anything
+-- that makes it past the guard is definitively new.
+
+create or replace function jobs.enqueue(
+    p_name           text,
+    p_payload        jsonb        default '{}',
+    p_queue          text         default 'default',
+    p_idempotency_key text        default null,
+    p_user_id        uuid         default null,
+    p_max_attempts   int          default 3,
+    p_backoff        text         default 'exponential',
+    p_backoff_base_s float        default 5.0,
+    p_backoff_max_s  float        default 300.0,
+    p_run_at         timestamptz  default now(),
+    p_version        int          default 1,
+    p_role           text         default 'service_role',
+    p_claims_from    text         default null
+)
+returns table (job jobs.jobs, is_new boolean)
+language plpgsql
+security definer
+as $$
+declare
+    existing_id uuid;
+begin
+    if p_idempotency_key is not null then
+        select j.id into existing_id
+        from jobs.jobs j
+        where j.idempotency_key = p_idempotency_key
+          and j.status in ('queued', 'running')
+        limit 1;
+
+        if existing_id is not null then
+            return query
+            select j, false
+            from jobs.jobs j
+            where j.id = existing_id;
+            return;
+        end if;
+    end if;
+
+    return query
+    with ins as (
+        insert into jobs.jobs (
+            name, version, payload, queue, idempotency_key, user_id,
+            max_attempts, backoff, backoff_base_s, backoff_max_s,
+            run_at, role, claims_from
+        )
+        values (
+            p_name, p_version, coalesce(p_payload, '{}'::jsonb), p_queue,
+            p_idempotency_key, p_user_id,
+            p_max_attempts, p_backoff, p_backoff_base_s, p_backoff_max_s,
+            coalesce(p_run_at, now()), p_role, p_claims_from
+        )
+        returning *
+    )
+    select ins::jobs.jobs, true from ins;
+end;
+$$;
+
+grant execute on function jobs.enqueue(
+    text, jsonb, text, text, uuid, int, text, float, float, timestamptz, int, text, text
+) to service_role;
+
+-- ─── jobs.claim_next ─────────────────────────────────────────────────────────
+
+-- Poll the queue for the next available job.  Uses SKIP LOCKED so multiple
+-- workers never claim the same row.  Reclaims "zombie" rows whose
+-- locked_at is older than p_visibility_timeout_ms ago (bounded by
+-- p_zombie_batch to avoid thundering herd).
+create or replace function jobs.claim_next(
+    p_queue               text    default 'default',
+    p_worker_id           text    default null,
+    p_visibility_timeout_ms int   default 300000,
+    p_zombie_batch        int     default 10
+)
+returns setof jobs.jobs
+language plpgsql
+security definer
+as $$
+declare
+    reclaimed int;
+begin
+    -- bounded zombie reclaim
+    update jobs.jobs
+    set status    = 'queued',
+        locked_at = null,
+        locked_by = null
+    where id in (
+        select id
+        from jobs.jobs
+        where status  = 'running'
+          and queue   = p_queue
+          and locked_at < now() - (p_visibility_timeout_ms || ' milliseconds')::interval
+        order by locked_at
+        limit p_zombie_batch
+        for update skip locked
+    );
+
+    get diagnostics reclaimed = row_count;
+
+    -- claim the next queued job
+    return query
+    update jobs.jobs j
+    set status    = 'running',
+        attempts  = j.attempts + 1,
+        locked_at = now(),
+        locked_by = p_worker_id
+    where j.id in (
+        select c.id
+        from jobs.jobs c
+        where c.status = 'queued'
+          and c.queue  = p_queue
+          and c.run_at <= now()
+        order by c.run_at, c.id
+        limit 1
+        for update skip locked
+    )
+    returning j.*;
+end;
+$$;
+
+grant execute on function jobs.claim_next(text, text, int, int) to service_role;

supython/migrations/0008_jobs_last_error.sql

@@ -0,0 +1,56 @@
+-- v0.6 grooming: add last_error column to jobs.jobs so the failure reason
+-- lands on the row instead of only in logs.
+
+alter table jobs.jobs add column if not exists last_error text;
+
+-- clear last_error on reclaim so zombie rows don't carry stale errors
+create or replace function jobs.claim_next(
+    p_queue               text    default 'default',
+    p_worker_id           text    default null,
+    p_visibility_timeout_ms int   default 300000,
+    p_zombie_batch        int     default 10
+)
+returns setof jobs.jobs
+language plpgsql
+security definer
+as $$
+declare
+    reclaimed int;
+begin
+    update jobs.jobs
+    set status    = 'queued',
+        locked_at = null,
+        locked_by = null,
+        last_error = null
+    where id in (
+        select id
+        from jobs.jobs
+        where status  = 'running'
+          and queue   = p_queue
+          and locked_at < now() - (p_visibility_timeout_ms || ' milliseconds')::interval
+        order by locked_at
+        limit p_zombie_batch
+        for update skip locked
+    );
+
+    get diagnostics reclaimed = row_count;
+
+    return query
+    update jobs.jobs j
+    set status    = 'running',
+        attempts  = j.attempts + 1,
+        locked_at = now(),
+        locked_by = p_worker_id
+    where j.id in (
+        select c.id
+        from jobs.jobs c
+        where c.status = 'queued'
+          and c.queue  = p_queue
+          and c.run_at <= now()
+        order by c.run_at, c.id
+        limit 1
+        for update skip locked
+    )
+    returning j.*;
+end;
+$$;

supython/migrations/0009_auth_rate_limits.sql

@@ -0,0 +1,33 @@
+-- v0.6: brute-force protection for auth endpoints with a Postgres-backed
+-- fixed-window counter (no Redis dependency).
+--
+-- Uses an UNLOGGED table because counters are ephemeral; a crash truncation
+-- only resets buckets, which is preferable to keeping stale windows.
+
+create unlogged table if not exists auth.rate_limit_buckets (
+    bucket        text        not null,
+    window_start  timestamptz not null,
+    count         int         not null default 0,
+    primary key (bucket, window_start)
+);
+
+alter table auth.rate_limit_buckets owner to service_role;
+
+grant select, insert, update, delete
+    on auth.rate_limit_buckets to service_role;
+
+-- prune stale buckets every 5 minutes when pg_cron is available.
+-- conditional so migration applies cleanly on managed Postgres without pg_cron.
+do $$
+begin
+    if exists (select 1 from pg_extension where extname = 'pg_cron') then
+        perform cron.unschedule('auth_rate_limit_prune')
+            where exists (select 1 from cron.job where jobname = 'auth_rate_limit_prune');
+        perform cron.schedule(
+            'auth_rate_limit_prune',
+            '*/5 * * * *',
+            $cron$delete from auth.rate_limit_buckets
+                  where window_start < now() - interval '1 hour'$cron$
+        );
+    end if;
+end $$;

supython/migrations/0010_worker_heartbeat.sql

@@ -0,0 +1,14 @@
+-- Worker heartbeat table for /readyz health probing.
+-- Each running worker upserts a row on every poll tick;
+-- /readyz checks the age of the most recent heartbeat.
+create table if not exists jobs.worker_heartbeats (
+    worker_id       text primary key,
+    last_heartbeat  timestamptz not null default now(),
+    inflight        int not null default 0
+);
+
+alter table jobs.worker_heartbeats enable row level security;
+alter table jobs.worker_heartbeats owner to service_role;
+
+-- service_role owns the table; workers run as service_role.
+-- No grant to authenticated -- this is internal infrastructure.

supython/migrations/0011_admin_schema.sql

@@ -0,0 +1,45 @@
+create schema if not exists admin authorization service_role;
+
+create table if not exists admin.admin_users (
+    id            uuid primary key default gen_random_uuid(),
+    email         citext unique not null,
+    password_hash text not null,
+    is_root       boolean not null default false,
+    created_at    timestamptz not null default now(),
+    last_login_at timestamptz
+);
+
+create table if not exists admin.admin_sessions (
+    id           uuid primary key default gen_random_uuid(),
+    admin_id     uuid not null references admin.admin_users(id) on delete cascade,
+    token_hash   bytea not null unique,
+    issued_at    timestamptz not null default now(),
+    expires_at   timestamptz not null,
+    revoked_at   timestamptz,
+    ip           inet,
+    user_agent   text
+);
+create index if not exists admin_sessions_admin_id_idx on admin.admin_sessions (admin_id);
+
+create table if not exists admin.admin_audit (
+    id         bigserial primary key,
+    admin_id   uuid references admin.admin_users(id) on delete set null,
+    action     text not null,
+    target     text,
+    payload    jsonb not null default '{}'::jsonb,
+    ip         inet,
+    user_agent text,
+    at         timestamptz not null default now()
+);
+create index if not exists admin_audit_at_idx on admin.admin_audit (at desc);
+
+revoke all on schema admin from public;
+revoke all on all tables in schema admin from public;
+
+-- Schema is owned by service_role, but tables created here by the migration
+-- runner (e.g. `supython` in dev) are not. Grant explicitly so the login
+-- handler — which runs as service_role via `db.as_service_role()` — can read
+-- and write admin tables. Mirrors the pattern in 0002_auth_schema.sql.
+grant usage on schema admin to service_role;
+grant all on all tables in schema admin to service_role;
+grant all on all sequences in schema admin to service_role;

supython/migrations/0012_auth_banned_until.sql

@@ -0,0 +1,10 @@
+-- Add a per-user ban window so the admin surface can ban / unban accounts
+-- without deleting rows. `auth.users.banned_until` is null when the user is
+-- not banned, otherwise the timestamp at which the ban lifts.
+
+alter table auth.users
+    add column if not exists banned_until timestamptz;
+
+create index if not exists users_banned_until_idx
+    on auth.users (banned_until)
+    where banned_until is not null;

supython/migrations/0013_email_templates.sql

@@ -0,0 +1,19 @@
+-- Store editable email templates so operators can customise the auth emails
+-- without touching source files. The auth module looks up templates by name;
+-- if a row exists, its subject + text_body are used instead of the built-in
+-- default.
+
+create table if not exists admin.email_templates (
+    name       text primary key,
+    subject    text not null,
+    text_body  text not null,
+    updated_at timestamptz not null default now()
+);
+
+-- Seed the three templates the auth module currently ships as hard-coded
+-- strings, so the operator sees the current defaults on first open.
+insert into admin.email_templates (name, subject, text_body) values
+    ('recover',    'Reset your password',                     'Use this token to reset your password: {{ token }}'),
+    ('magic_link', 'Sign in to your account',                 'Click the link to sign in: {{ url }}'),
+    ('otp',        'Your one-time password',                  'Your OTP is: {{ token }}')
+on conflict (name) do nothing;

supython/migrations/0014_realtime_payload_warning.sql

@@ -0,0 +1,96 @@
+-- v0.4 follow-up: do not let realtime.fire_notify() abort user writes
+-- when the rendered NOTIFY payload exceeds Postgres's 8000-byte ceiling.
+--
+-- Background: pg_notify(channel, payload) raises `payload string too
+-- long` if `payload` is larger than 8000 bytes (a hard server-side
+-- limit). Before this migration the trigger called pg_notify
+-- unconditionally, so a single oversize row aborted the user's write
+-- transaction. That is a correctness bug: a realtime subscription must
+-- never break user writes.
+--
+-- New behavior: pre-check the rendered payload size before NOTIFY.
+--   * Under the threshold (default 7900 bytes — ~100-byte headroom):
+--     identical to migration 0006.
+--   * Over the threshold:
+--       1. RAISE WARNING with schema, table, op, and rendered byte size
+--          so the operator sees the event in the Postgres log. The v0.8
+--          benchmark counts these as the second motivator for the
+--          deferred logical-replication source (§19, 2026-05-04).
+--       2. Skip pg_notify. The write succeeds; subscribers receive no
+--          event for this row. (Skipping is the conservative choice:
+--          emitting a metadata-only notify would put `record: null` on
+--          the wire for INSERT/UPDATE, which today only happens for
+--          DELETE — a wire-shape change the broker and SDKs would have
+--          to learn about.)
+--
+-- Operator escape hatch: realtime v2 (logical replication, Post v1.1)
+-- has no payload-size cap. Until that ships, oversize rows are not
+-- delivered via realtime; clients can refetch via REST/PostgREST.
+--
+-- Idempotent: `create or replace function` — fresh installs apply 0006
+-- and then this; existing installs apply only this and pick up the new
+-- body in place.
+
+create or replace function realtime.fire_notify()
+returns trigger language plpgsql security definer as $$
+declare
+    v_columns       jsonb;
+    v_payload       jsonb;
+    v_payload_text  text;
+    v_payload_bytes int;
+    -- 8000-byte NOTIFY cap minus ~100 bytes of headroom for asyncpg /
+    -- channel-name overhead. Hard-coded rather than a setting because
+    -- the 8000 limit is a Postgres compile-time constant — operators
+    -- cannot raise it without recompiling.
+    v_payload_max   int := 7900;
+begin
+    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
+    );
+
+    v_payload_text  := v_payload::text;
+    v_payload_bytes := octet_length(v_payload_text);
+
+    if v_payload_bytes > v_payload_max then
+        raise warning
+            'realtime.fire_notify: dropping % event for %.%; payload is % bytes (>%-byte NOTIFY ceiling)',
+            tg_op,
+            tg_table_schema,
+            tg_table_name,
+            v_payload_bytes,
+            v_payload_max;
+        return null;
+    end if;
+
+    perform pg_notify('realtime:changes', v_payload_text);
+
+    return null;
+end $$;

supython/migrations/0015_backups_schema.sql

@@ -0,0 +1,14 @@
+create table if not exists admin.backups (
+    id            uuid primary key default gen_random_uuid(),
+    kind          text not null check (kind in ('full', 'schema-only')),
+    status        text not null default 'running'
+                      check (status in ('running', 'completed', 'failed')),
+    size          bigint,
+    file_path     text,
+    error_message text,
+    started_at    timestamptz not null default now(),
+    finished_at   timestamptz,
+    created_at    timestamptz not null default now()
+);
+
+grant all on admin.backups to service_role;

supython/passwords.py

@@ -0,0 +1,15 @@
+from argon2 import PasswordHasher
+from argon2.exceptions import VerificationError, VerifyMismatchError
+
+_hasher = PasswordHasher()
+
+
+def hash_password(password: str) -> str:
+    return _hasher.hash(password)
+
+
+def verify_password(hashed: str, password: str) -> bool:
+    try:
+        return _hasher.verify(hashed, password)
+    except (VerifyMismatchError, VerificationError):
+        return False

supython/realtime/__init__.py

@@ -0,0 +1,6 @@
+"""Realtime module — Phoenix-channels subset over WebSockets, in-process broker."""
+
+from .broker import Broker, get_broker, reset_broker
+from .router import router
+
+__all__ = ["Broker", "get_broker", "reset_broker", "router"]