Skip to content

AGENTS.md

Latest commit

 

History

History
38 lines (28 loc) · 2.69 KB

AGENTS.md

File metadata and controls

38 lines (28 loc) · 2.69 KB
Raw

AGENTS.md — FunTimeEvents API Proxy

Single‑package Python 3.11+ reverse proxy. Transparent HTTP/WebSocket relay: forwards the client's own X-API-Key / api_key as-is to hide the origin client IP. Does NOT inject any key — the backend validates the client key directly.

Commands

Action Command
Run server fte-proxy run (all options via FTE_PROXY_* env vars or .env)
Editable install pip install -e .
Run all tests pytest (no extra flags; asyncio_mode = auto via pyproject.toml)
Ruff lint ruff check . (line‑length 120, double quotes, select E/F/I/G)

CLI entrypoint: proxy/main.py:cli (click group → run subcommand).

Architecture

  • proxy/config.py — pydantic‑settings BaseSettings with env_prefix="FTE_PROXY_"; auto‑loads .env. Backend URL (backend_url) is a private attribute (set via __init__), hardcoded to https://api.funtimeevents.su, not configurable via env/CLI
  • proxy/http_proxy.py — catch‑all route /{tail:.*} → replaces origin with backend, forwards headers as-is (strips Host, overrides User-Agent), returns 502 on upstream failure
  • proxy/ws_relay.py — WebSocket relay at /v1/relay; forwards every text frame (including the client auth frame with its own api_key) to the backend as-is
  • proxy/logger.py — loguru with coloured stderr sink ({module} extra field in format)
  • proxy/__init__.py — empty

Key conventions

  • No test runners or pre‑commit scripts — just pytest and ruff check .
  • SSLContext built manually from FTE_PROXY_TLS_CERT/FTE_PROXY_TLS_KEY (paths must exist on disk; validated at startup)
  • .env is gitignored — copy .env.example and adjust host/port
  • pytest‑asyncio with asyncio_mode = "auto" and asyncio_default_fixture_loop_scope = "function" — every test file is async by default, no decorators needed. pytest-aiohttp provides the aiohttp_server/aiohttp_client fixtures
  • Tests use aiohttp_server/aiohttp_client fixtures to spin up mock backends and proxy apps in‑process; no external services required
  • _backend_url is a private attribute (set via __init__, not a pydantic field) — tests pass it via Settings(backend_url=...). Do not expose it as a public field or env var.

Notable constraints

  • HTTP proxy strips the Host header from client and overrides User-Agent with FTE_PROXY_USER_AGENT
  • The proxy must NEVER add or replace X-API-Key / api_key — client authentication is the backend's job (401 / 4001 on invalid key)
  • WebSocket: SDK sends auth frame first or the relay drops the connection silently
  • Proxy never caches, stores, or modifies response bodies — only headers