supython 0.5.0__py3-none-any.whl

supython/scaffold/init_project.py

@@ -0,0 +1,133 @@
+"""Scaffold a new supython project directory."""
+
+import json
+import os
+import secrets
+from pathlib import Path
+
+from supython import jwks as _jwks
+
+_TEMPLATES_DIR = Path(__file__).parent / "templates"
+_JWT_KEYS_DIRNAME = ".supython"
+_PRIVATE_KEY_FILENAME = "jwt_private.pem"
+_JWKS_FILENAME = "jwks.json"
+
+_TEMPLATE_MAP: list[tuple[str, str]] = [
+    ("docker-compose.yml.tmpl", "docker-compose.yml"),
+    ("docker-compose.prod.yml.tmpl", "docker-compose.prod.yml"),
+    ("env.example.tmpl", ".env.example"),
+    ("gitignore.tmpl", ".gitignore"),
+    ("README.md.tmpl", "README.md"),
+    ("functions_README.md.tmpl", "functions/README.md"),
+    ("Caddyfile.tmpl", "Caddyfile"),
+    ("docker_postgres_Dockerfile.tmpl", "docker/postgres/Dockerfile"),
+    ("docker_postgres_postgresql.conf.tmpl", "docker/postgres/postgresql.conf"),
+]
+
+
+def scaffold(name: str, target: Path, *, force: bool = False) -> list[Path]:
+    """Write a minimal supython project into *target*.
+
+    Returns the list of paths written, in order.
+    Raises ``FileExistsError`` if *target* is non-empty and *force`` is False.
+    """
+    if target.exists() and any(target.iterdir()) and not force:
+        raise FileExistsError(f"{target} is not empty. Use --force to overwrite.")
+
+    target.mkdir(parents=True, exist_ok=True)
+    (target / "migrations").mkdir(exist_ok=True)
+    (target / "functions").mkdir(exist_ok=True)
+
+    vars: dict[str, str] = {
+        "name": name,
+    }
+
+    written: list[Path] = []
+
+    for tmpl_name, dest_rel in _TEMPLATE_MAP:
+        tmpl_path = _TEMPLATES_DIR / tmpl_name
+        content = tmpl_path.read_text().format(**vars)
+        dest = target / dest_rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        if dest.exists() and not force:
+            continue
+        dest.write_text(content)
+        written.append(dest)
+
+    gitkeep = target / "migrations" / ".gitkeep"
+    if not gitkeep.exists() or force:
+        gitkeep.write_text("")
+        written.append(gitkeep)
+
+    written.extend(_write_scaffold_keypair(target, force=force))
+    written.extend(_write_scaffold_secrets(target, force=force))
+    return written
+
+
+def _write_scaffold_keypair(target: Path, *, force: bool) -> list[Path]:
+    key_dir = target / _JWT_KEYS_DIRNAME
+    key_dir.mkdir(parents=True, exist_ok=True)
+    pem_path = key_dir / _PRIVATE_KEY_FILENAME
+    jwks_path = key_dir / _JWKS_FILENAME
+
+    if not force and pem_path.exists() and jwks_path.exists():
+        return []
+
+    key = _jwks.generate_private_key("RS256")
+    signer = _jwks.signing_key_from_private_key(key, "RS256")
+    _jwks.write_private_key_pem(pem_path, _jwks.private_key_to_pem(key), force=force)
+    _jwks.write_jwks_file(jwks_path, _jwks.jwks_for_signing_key(signer))
+    return [pem_path, jwks_path]
+
+
+def _write_scaffold_secrets(target: Path, *, force: bool) -> list[Path]:
+    secrets_dir = target / ".supython" / "secrets"
+    secrets_dir.mkdir(parents=True, exist_ok=True)
+    manifest_path = target / ".supython" / "secrets.json"
+
+    if not force and manifest_path.exists():
+        return []
+
+    oauth_secret = secrets.token_urlsafe(48)
+    storage_secret = secrets.token_urlsafe(48)
+
+    oauth_kid = "v1"
+    storage_kid = "v1"
+
+    (secrets_dir / f"oauth_state.{oauth_kid}.secret").write_text(oauth_secret)
+    (secrets_dir / f"storage_signed_url.{storage_kid}.secret").write_text(storage_secret)
+    if os.name == "posix":
+        (secrets_dir / f"oauth_state.{oauth_kid}.secret").chmod(0o600)
+        (secrets_dir / f"storage_signed_url.{storage_kid}.secret").chmod(0o600)
+
+    now_iso = "2026-01-01T00:00:00Z"  # static; tests read back the actual values
+    manifest = {
+        "oauth_state": {
+            "active": oauth_kid,
+            "keys": [
+                {
+                    "kid": oauth_kid,
+                    "status": "active",
+                    "created_at": now_iso,
+                    "retired_at": None,
+                }
+            ],
+        },
+        "storage_signed_url": {
+            "active": storage_kid,
+            "keys": [
+                {
+                    "kid": storage_kid,
+                    "status": "active",
+                    "created_at": now_iso,
+                    "retired_at": None,
+                }
+            ],
+        },
+    }
+    manifest_path.write_text(json.dumps(manifest, sort_keys=True, indent=2) + "\n")
+    return [
+        secrets_dir / f"oauth_state.{oauth_kid}.secret",
+        secrets_dir / f"storage_signed_url.{storage_kid}.secret",
+        manifest_path,
+    ]

supython/scaffold/templates/Caddyfile.tmpl

@@ -0,0 +1,4 @@
+{{$SITE_URL}} {{
+	reverse_proxy /rest/v1/* postgrest:3000
+	reverse_proxy supython:8000
+}}

supython/scaffold/templates/README.md.tmpl

@@ -0,0 +1,22 @@
+# {name}
+
+A [supython](https://github.com/your-org/supython) project.
+
+## Quick start
+
+```bash
+cp .env.example .env
+pip install supython
+supython up   # start Postgres + PostgREST and apply migrations
+supython dev  # start the auth/API service on http://localhost:8000
+```
+
+## Layout
+
+- `migrations/` — SQL migration files (applied in filename order by `supython migrate`)
+- `functions/` — edge functions (one `.py` file per route, no restart required)
+- `.supython/` — generated JWT keypair and JWKS (private key is gitignored)
+
+## Docs
+
+See the [supython documentation](https://github.com/your-org/supython) for full reference.

supython/scaffold/templates/docker-compose.prod.yml.tmpl

@@ -0,0 +1,84 @@
+name: {name}
+
+services:
+  db:
+    build: ./docker/postgres
+    container_name: {name}-db
+    environment:
+      POSTGRES_USER: {name}
+      POSTGRES_PASSWORD: ${{POSTGRES_PASSWORD:-{name}}}
+      POSTGRES_DB: {name}
+    ports:
+      - "127.0.0.1:54322:5432"
+    volumes:
+      - {name}-db-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {name} -d {name}"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  postgrest:
+    image: postgrest/postgrest:v12.2.3
+    container_name: {name}-postgrest
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      PGRST_DB_URI: postgres://authenticator:${{AUTHENTICATOR_PASSWORD:-authenticator}}@db:5432/{name}
+      PGRST_DB_SCHEMAS: public
+      PGRST_DB_ANON_ROLE: anon
+      PGRST_JWT_SECRET: "@/etc/postgrest/jwks.json"
+      PGRST_JWT_AUD: authenticated
+      PGRST_OPENAPI_MODE: ignore-privileges
+      PGRST_DB_USE_LEGACY_GUCS: "false"
+    volumes:
+      - ./.supython/jwks.json:/etc/postgrest/jwks.json:ro
+
+  supython:
+    # Pin to a release tag, or replace with `build: .` if you are building from source.
+    image: ghcr.io/<owner>/supython:<version>
+    container_name: {name}-api
+    depends_on:
+      postgrest:
+        condition: service_started
+    env_file:
+      - .env
+    volumes:
+      - ./.supython/jwt_private.pem:/run/secrets/jwt_private.pem:ro
+      - ./.supython/jwks.json:/run/secrets/jwks.json:ro
+      - {name}-storage:/var/lib/supython/storage
+    ports:
+      - "${{SUPYTHON_PUBLISH_PORT:-8000}}:8000"
+
+  worker:
+    image: ghcr.io/<owner>/supython:<version>
+    profiles: ["worker"]
+    container_name: {name}-worker
+    depends_on:
+      - db
+    env_file:
+      - .env
+    volumes:
+      - ./.supython/jwt_private.pem:/run/secrets/jwt_private.pem:ro
+    command: ["supython", "worker", "run", "--queue", "default"]
+
+  caddy:
+    image: caddy:2-alpine
+    profiles: ["tls"]
+    container_name: {name}-caddy
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - {name}-caddy-data:/data
+      - {name}-caddy-config:/config
+    depends_on:
+      - supython
+
+volumes:
+  {name}-db-data:
+  {name}-storage:
+  {name}-caddy-data:
+  {name}-caddy-config:

supython/scaffold/templates/docker-compose.yml.tmpl

@@ -0,0 +1,41 @@
+name: {name}
+
+services:
+  db:
+    image: postgres:16-alpine
+    container_name: {name}-db
+    environment:
+      POSTGRES_USER: {name}
+      POSTGRES_PASSWORD: {name}
+      POSTGRES_DB: {name}
+    ports:
+      - "54322:5432"
+    volumes:
+      - {name}-db-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {name} -d {name}"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  postgrest:
+    image: postgrest/postgrest:v12.2.3
+    container_name: {name}-postgrest
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      PGRST_DB_URI: postgres://authenticator:${{AUTHENTICATOR_PASSWORD:-authenticator}}@db:5432/{name}
+      PGRST_DB_SCHEMAS: public
+      PGRST_DB_ANON_ROLE: anon
+      PGRST_JWT_SECRET: "@/etc/postgrest/jwks.json"
+      PGRST_JWT_AUD: authenticated
+      PGRST_OPENAPI_MODE: ignore-privileges
+      PGRST_DB_USE_LEGACY_GUCS: "false"
+    ports:
+      - "54321:3000"
+    volumes:
+      - ./.supython/jwks.json:/etc/postgrest/jwks.json:ro
+
+volumes:
+  {name}-db-data:

supython/scaffold/templates/docker_postgres_Dockerfile.tmpl

@@ -0,0 +1,9 @@
+FROM postgres:16-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends postgresql-16-cron \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY postgresql.conf /etc/postgresql/postgresql.conf
+
+CMD ["postgres", "-c", "config_file=/etc/postgresql/postgresql.conf"]

supython/scaffold/templates/docker_postgres_postgresql.conf.tmpl

@@ -0,0 +1,3 @@
+shared_preload_libraries = 'pg_cron'
+cron.database_name = '{name}'
+listen_addresses = '*'

supython/scaffold/templates/env.example.tmpl

@@ -0,0 +1,149 @@
+# Copy to .env and adjust as needed.
+
+DATABASE_URL=postgresql://{name}:{name}@localhost:54322/{name}
+# 0 disables; otherwise per-connection ceiling for any one query.
+DB_STATEMENT_TIMEOUT_MS=30000
+DB_POOL_MIN_SIZE=1
+DB_POOL_MAX_SIZE=10
+DB_ALLOWED_ROLES=anon,authenticated
+
+# Asymmetric JWT (RS256). `supython init` generated the keypair under
+# ./.supython/; the private key is .gitignored, the JWKS (public) is safe
+# to commit if you want reproducible PostgREST behavior across clones.
+# To rotate, run: supython keygen --force
+JWT_ALG=RS256
+JWT_PRIVATE_KEY_PATH=./.supython/jwt_private.pem
+# Inline PEM alternative to JWT_PRIVATE_KEY_PATH (use for container secrets).
+# JWT_PRIVATE_KEY=
+JWT_JWKS_PATH=./.supython/jwks.json
+JWT_AUD=authenticated
+
+
+ACCESS_TOKEN_TTL=3600
+REFRESH_TOKEN_TTL=2592000
+
+# One-time token lifetimes (seconds): password recover, magic link, email OTP.
+RECOVER_TOKEN_TTL=3600
+MAGIC_LINK_TOKEN_TTL=900
+OTP_TOKEN_TTL=600
+AUTH_RATE_LIMIT_ENABLED=true
+AUTH_RATE_LIMIT_WINDOW_SECONDS=60
+AUTH_RATE_LIMIT_TOKEN_PER_WINDOW=10
+AUTH_RATE_LIMIT_SIGNUP_PER_WINDOW=5
+AUTH_RATE_LIMIT_RECOVER_PER_WINDOW=3
+AUTH_RATE_LIMIT_OTP_PER_WINDOW=5
+AUTH_RATE_LIMIT_MAGICLINK_PER_WINDOW=5
+
+# Postgres superuser password. Used by docker-compose.prod.yml; dev compose hardcodes it.
+POSTGRES_PASSWORD={name}
+
+# PostgREST connects as `authenticator`; default matches migrations/0001_extensions_and_roles.sql.
+# If you change this, update docker-compose PGRST_DB_URI (or AUTHENTICATOR_PASSWORD) to match.
+AUTHENTICATOR_PASSWORD=authenticator
+
+# Email: console (log only) or smtp.
+EMAIL_BACKEND=console
+EMAIL_FROM={name}@localhost
+SMTP_HOST=localhost
+SMTP_PORT=587
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_STARTTLS=true
+
+# OAuth (optional). Leave unset to disable a provider.
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+# OAuth state signing key is generated fresh by `supython init` and stored
+# in .supython/secrets/ (manifest: .supython/secrets.json).
+# Rotate via: supython secret rotate oauth
+OAUTH_STATE_MAX_AGE=600
+
+POSTGREST_URL=http://localhost:54321
+SITE_URL=http://localhost:8000
+
+# Comma-separated list of allowed browser origins (scheme + host + port). Empty = no CORS
+# wildcard; cross-origin browser calls with credentials will not be allowed until you set this.
+# Example: CORS_ORIGINS=http://localhost:3000,https://app.example.com
+CORS_ORIGINS=
+
+# Storage: local (default) or s3 (requires pip install supython[s3]).
+STORAGE_BACKEND=local
+STORAGE_LOCAL_ROOT=./storage
+
+# S3 / MinIO / R2 (only when STORAGE_BACKEND=s3). Set endpoint for non-AWS.
+STORAGE_S3_ENDPOINT=
+STORAGE_S3_REGION=us-east-1
+STORAGE_S3_BUCKET=
+STORAGE_S3_ACCESS_KEY_ID=
+STORAGE_S3_SECRET_ACCESS_KEY=
+
+# Storage signed-URL signing key is generated fresh by `supython init` and
+# stored in .supython/secrets/ (manifest: .supython/secrets.json).
+# Rotate via: supython secret rotate storage
+STORAGE_SIGNED_URL_DEFAULT_TTL=3600
+# Hard cap above any per-bucket file_size_limit (bytes).
+STORAGE_MAX_UPLOAD_BYTES=52428800
+
+# Functions: directory holding edge functions (one .py per route).
+FUNCTIONS_DIR=./functions
+# Reload changed function modules on each request. Disable in production.
+FUNCTIONS_HOT_RELOAD=true
+# Max eager request body the dispatcher will buffer before invoking a handler.
+FUNCTIONS_MAX_BODY_BYTES=5242880
+# Max handler execution time (seconds) before cancellation.
+FUNCTIONS_MAX_HANDLER_SECONDS=30.0
+
+# Realtime (v0.4)
+REALTIME_ENABLED=true
+REALTIME_NOTIFY_CHANNEL=realtime:changes
+REALTIME_MAX_CONNECTIONS=1000
+REALTIME_MAX_SUBS_PER_CONN=100
+# Server-side idle timeout (seconds); client sends heartbeats every ~25s.
+REALTIME_HEARTBEAT_TIMEOUT_SECONDS=30
+REALTIME_BROKER_QUEUE_SIZE=1000
+REALTIME_RLS_CHECK_TIMEOUT_S=1.0
+REALTIME_BROADCAST_SELF_DEFAULT=false
+
+# Jobs & cron (v0.5). Enable the job queue worker.
+JOBS_ENABLED=true
+JOBS_BACKEND=pg
+JOBS_CRON_BACKEND=pg_cron
+JOBS_QUEUE_DEFAULT=default
+JOBS_POLL_INTERVAL_S=1.0
+JOBS_CONCURRENCY=5
+JOBS_DEFAULT_MAX_ATTEMPTS=3
+JOBS_BACKOFF_BASE_S=5.0
+JOBS_BACKOFF_MAX_S=300.0
+JOBS_VISIBILITY_TIMEOUT_S=300.0
+JOBS_VISIBILITY_RECLAIM_BATCH=10
+JOBS_DRAIN_TIMEOUT_S=30.0
+JOBS_DEV_INPROCESS=false
+
+# External queue backends (optional — only needed if you switch jobs_backend).
+ARQ_REDIS_URL=redis://localhost:6379
+DRAMATIQ_BROKER_URL=redis://localhost:6379
+
+# Security headers (v0.7)
+SECURITY_HEADERS_ENABLED=true
+# HSTS: None = auto (on iff SITE_URL starts with https://). True/False forces.
+SECURITY_HSTS_ENABLED=
+SECURITY_HSTS_MAX_AGE=31536000
+SECURITY_HSTS_INCLUDE_SUBDOMAINS=true
+SECURITY_HSTS_PRELOAD=false
+SECURITY_FRAME_OPTIONS=DENY
+SECURITY_REFERRER_POLICY=strict-origin-when-cross-origin
+SECURITY_CSP="default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"
+SECURITY_CSP_EXEMPT_PATHS=/docs,/redoc,/openapi.json,/admin
+# Global request body cap (bytes); exempt paths use their own per-feature caps.
+SECURITY_MAX_BODY_BYTES=1048576
+SECURITY_BODY_LIMIT_EXEMPT_PATHS=/storage/v1/object,/functions
+
+# Port published by the prod compose supython service (dev uses hardcoded 8000).
+SUPYTHON_PUBLISH_PORT=8000
+
+# Observability
+LOG_LEVEL=INFO
+LOG_JSON=true

supython/scaffold/templates/functions_README.md.tmpl

@@ -0,0 +1,21 @@
+# functions/
+
+Drop a `.py` file here and supython will serve it under `POST /functions/<name>` — no server restart required.
+
+```python
+# functions/hello.py
+auth = "anon"          # "anon" | "authenticated" (default)
+methods = ["GET", "POST"]
+
+async def handler(req, ctx):
+    name = ctx.user.email if ctx.user else "world"
+    return {{"msg": f"hello, {{name}}"}}
+```
+
+`ctx` gives you:
+- `ctx.db` — a role-scoped `asyncpg.Connection` (RLS already applied)
+- `ctx.user` — caller identity (`id`, `email`, `role`, `claims`)
+- `ctx.storage` — `upload / download / sign` over the storage subsystem
+- `ctx.postgrest` — `httpx.AsyncClient` pre-authed with the caller's JWT
+- `ctx.send_email(to=..., subject=..., text=...)` — send transactional email
+- `ctx.request` — the raw FastAPI `Request` (escape hatch)

supython/scaffold/templates/gitignore.tmpl

@@ -0,0 +1,14 @@
+.env
+.venv/
+__pycache__/
+.pytest_cache/
+storage/
+
+# Asymmetric JWT private key (public JWKS stays tracked).
+.supython/jwt_private.pem
+.supython/keys/
+.supython/keyset.json
+
+# Symmetric secrets
+.supython/secrets/
+.supython/secrets.json