src/routes/proxy.py

"""Thin HTTP handler — reads the request, delegates to the Router."""   # module docstring
from __future__ import annotations   # defer annotation evaluation (PEP 563)

from typing import Optional   # Optional for the module global

from fastapi import APIRouter, Request   # router + request object
from fastapi.responses import JSONResponse   # JSON responses for errors

from ..services.router import Router   # the unified router (one retry loop)

router = APIRouter()   # the FastAPI router all routes attach to
ROUTER: Optional[Router] = None   # set once at startup by init_router()


def init_router(config, client) -> None:   # called once at startup to wire the router
    global ROUTER   # mutate the module global
    ROUTER = Router(config, client)   # construct the unified router


@router.get("/v1/models")   # OpenAI-compatible models listing (public, no auth)
async def list_models():   # advertises all models we expose
    return JSONResponse({"object": "list", "data": ROUTER.config.list_models()})   # OpenAI-shaped list


@router.api_route(   # OpenAI-compatible proxy — only /v1/* paths (static files served elsewhere)
    "/v1/{path:path}",   # captures everything after /v1/ (e.g. chat/completions)
    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"],   # all verbs we forward
)
async def proxy(path: str, request: Request):   # main forwarding handler
    # The forwarder expects the full client path including the v1/ prefix,   # forwarder.py strips it per-target
    full_path = "v1/" + path   # reconstruct "v1/chat/completions" for the router
    body_bytes = await request.body()   # read the raw request body once
    client_headers = dict(request.headers)   # snapshot client headers
    query_params = dict(request.query_params)   # snapshot query string
    # billing identity (set by the gate middleware); None for admin/unmetered
    user_id = getattr(request.state, "user_id", None)   # billing user_id (or None)
    is_admin = getattr(request.state, "is_admin", False)   # admin bypasses billing
    return await ROUTER.handle(request.method, full_path, body_bytes, client_headers,   # delegate to router
                               query_params, user_id=user_id, is_admin=is_admin)   # delegate to router