supabase-pinger/AGENTS.md

AGENTS.md

Quick Commands

pytest -q                    # Run all tests
python app.py                # Start server (requires valid .env)

Testing

• Tests use config_override in create_app() to mock settings and skip the collector thread (start_collector=False).
• No database connection required for tests—SQLite uses temp directories.
• Test files: tests/test_api.py with 3 test functions.

Required Env Vars

Variable	Purpose
SUPABASE_DB_HOST	Connection pooler hostname
SUPABASE_DB_PORT	Pooler port (typically 6543)
SUPABASE_DB_NAME	Database name
SUPABASE_DB_USER	User in format postgres.<project-ref>
SUPABASE_DB_PASSWORD	Password

App Architecture

• Entry: app.py exports create_app() and app (FastAPI instance).
• Config: load_config() validates required vars, returns Settings dataclass.
• Storage: RRDStore class manages SQLite circular buffer (auto-prunes based on max_samples).
• Ping: run_ping() executes keep-alive query, returns (success, latency_ms, error_message).
• Collector: collector_loop() runs in daemon thread, interval from PING_INTERVAL_MINUTES.

API Endpoints

• GET / — Dashboard (SmokePing-style)
• GET /api/status — Latest sample
• GET /api/history?hours=48 — Sample history (max 48h)
• GET /docs — Swagger UI
• GET /openapi.json — OpenAPI schema

Docker

docker build -t supabase-pinger .
docker run -d --env-file .env -p 8080:8080 --restart unless-stopped supabase-pinger