telegram-web-proxy-stack/docs/incidents/bridge-routing.md

Design note: bridge query routing

Failure mode

A public fallback handler that matches every GET / request also captures the authenticated bridge request because the bridge capability is carried in the query string. The service may appear healthy while Telegram clients cannot connect.

Required behavior

Serve the fallback page only when the request has no query string:

if request.Method == http.MethodGet &&
    request.URL.Path == "/" &&
    request.URL.RawQuery == "" {
    servePublicPage()
}

Requests with bridge parameters, carrier API requests and WebSocket upgrades must be proxied to tproxy-server.

Verification

• the public root returns the fallback page;
• an authenticated bridge request returns the bridge document and disables caching;
• WebSocket traffic reaches the relay;
• a healthy admin endpoint is treated as necessary but not sufficient.