feat(examples): add FastAPI Realtime Rule Engine example

[grdsdev]

Summary

Adds a complete examples/fastapi/ example application that stress-tests the async Realtime path of supabase-py. The example is a FastAPI Realtime Rule Engine: users define watch rules ("when tasks.status changes to done, broadcast to channel #team-alerts"), and a Python background task holds a persistent AsyncRealtimeClient connection, subscribes to Postgres Changes, evaluates matching rules, and broadcasts enriched events — all from Python.

What's included

• examples/fastapi/main.py — FastAPI app with lifespan managing the service role client and engine task
• examples/fastapi/engine.py — AsyncRealtimeClient background coroutine: Postgres Changes subscription + server-side broadcast
• examples/fastapi/dependencies.py — Per-request JWT client injection via AsyncClientOptions header mutation
• examples/fastapi/routers/ — Auth, tasks, and rules routers with RLS-enforced PostgREST queries
• examples/fastapi/templates/ — Jinja2 HTML shell; browser uses @supabase/supabase-js CDN for Realtime, presence, and auth
• examples/fastapi/supabase/migrations/001_initial.sql — Tables (tasks, rules, rule_events) with RLS policies; ALTER PUBLICATION supabase_realtime ADD TABLE tasks
• examples/fastapi/friction_log.md — 6 documented SDK pain points surfaced during implementation
• examples/fastapi/README.md — Setup and run instructions

SDK paths stressed

Call	Purpose
acreate_client(url, service_key)	Long-lived service role singleton
acreate_client(url, anon_key, options=...)	Per-request client with JWT injection
channel.on_postgres_changes(event="UPDATE", ...)	Postgres Changes subscription
await service_client.realtime.connect()	Explicit WS connect (required before subscribe)
await channel.subscribe()	Channel subscription lifecycle
await channel.send(type="broadcast", ...)	Server-side broadcast from Python
await client.table(...).select("*").execute()	PostgREST from background asyncio task

Friction log highlights

The friction_log.md documents 6 SDK issues found during implementation, including:

• Per-request JWT injection requires mutating AsyncClientOptions().headers after construction (passing headers={} to the constructor drops DEFAULT_HEADERS)
• realtime.connect() must be called manually before channel.subscribe() — no auto-connect
• Realtime callbacks are sync-only with no documented async path (workaround: asyncio.get_running_loop().create_task())
• channel.send() requires a prior channel.subscribe() on the broadcast channel

Tests

26 tests covering engine rule evaluation, JWT dependency injection, all router endpoints, SQL migration, and template rendering. No mocking of Supabase's network layer — mocks target only the SDK client objects.

26 passed in 0.50s

Test plan

• Apply migration to a local Supabase project: supabase db push from examples/fastapi/
• Configure .env with SUPABASE_URL, SUPABASE_SERVICE_KEY, SUPABASE_ANON_KEY
• Run: uv sync from repo root, then uv run uvicorn main:app --reload from examples/fastapi/
• Sign in via /signin, create tasks and rules, verify live broadcast events appear in the feed
• Confirm RLS: a user cannot update tasks not assigned to them