tg-ws-proxy-rs: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (and humans) working in this repository.

What this project is

tg-ws-proxy-rs is a Rust port of Flowseal/tg-ws-proxy: a local MTProto proxy that tunnels Telegram Desktop traffic through WebSocket connections to Telegram's data centers. It exists for networks where raw TCP to Telegram is blocked but WebSocket/HTTPS to web.telegram.org still works (common in Russia and other censored networks).

At a high level: a Telegram client (Desktop, or any MTProto-speaking client) connects to this proxy over plain MTProto (optionally disguised as FakeTLS). The proxy de-obfuscates the MTProto transport frame, re-encrypts it for the target DC, and forwards it — preferring a WebSocket tunnel to wss://kwsN.web.telegram.org/apiws, with Cloudflare-proxy, Cloudflare-Worker, upstream MTProto proxy, and raw TCP as successive fallbacks.

Repository layout

src/
  main.rs              Thin CLI wrapper: clap parse, tracing, then server::run
  server.rs            Process-level bind / banner / accept loop (shared by the binary and embedders)
  config.rs            clap-derived Config struct; all CLI flags + TG_* env var fallbacks
  inbound.rs            Inbound layer: `Inbound` trait → `Session`, shared handshake timeout, listeners, client stream
  inbound/mtproto.rs    MTProto listener: MTProxy-secret handshake, optional inbound FakeTLS
  inbound/socks.rs      Optional SOCKS5 listener: destination IP → DC map, secretless transports
  proxy.rs              Routing core fed a `Session`: DC routing, WS/CF/TCP fallback chain, bridges
  crypto.rs             MTProto obfuscated-transport crypto (AES-256-CTR key derivation, secret layout)
  faketls.rs            0xee FakeTLS camouflage: fake TLS 1.3 handshake for inbound + upstream proxies
  splitter.rs            Splits/reassembles MTProto transport frames from WebSocket message boundaries
  ws_client.rs           WebSocket client that dials Telegram DC endpoints (kwsN.web.telegram.org)
  pool.rs                Pre-warmed pool of idle WebSocket connections per DC (cuts handshake latency)
  check.rs               `--check` connectivity tester for CF domains and upstream MTProto proxies
  limits.rs              Connection cap derived from the process file-descriptor budget
  default_domains.rs      Fetches + deobfuscates the community CF-proxy domain list from GitHub
  runtime.rs              Shared runtime state (outbound connector, fronting window, DC metadata)
  outbound/               Outbound TCP connector: HTTP/SOCKS5(h) proxy support, NO_PROXY matching
  default_domains/http.rs  Minimal HTTPS GET used only to fetch the default domain list

tests/                   Integration tests (one file per subsystem, mirrors src/ module names)
tests/common/mod.rs      Shared integration fixtures (fake HTTP CONNECT proxy, proxy-connection driver)
docs/                    User-facing guides. README stays an overview and links here rather than growing:
                         Fallbacks.md (routing tiers), Building.md (cross-compiling, UPX), Deployment.md
                         (Docker, OpenWrt, env vars), CfProxy.md + CfWorker.md (Cloudflare setup),
                         Android.md (Compose app + NDK build), Forkop.md (SOCKS5 inbound + router routing)
android/                 Jetpack Compose app (Gradle catalog + build-logic convention; see docs/Android.md)
crates/android-jni/      JNI start/stop + log callback cdylib; built only by the Android Gradle task