| name | MTProto Client Behavior Matrix |
| description | Version-pinned Telegram client connection behavior notes for proxy compatibility debugging. |
MTProto Client Behavior Matrix
Use this skill when behavior differs by client platform (iOS/Android/Desktop) or when tuning relay/handshake timeouts.
Evidence Policy
- Do not publish behavior claims without evidence.
- Accept only:
- reproducible local captures/logs, or
- direct client source links pinned to a tag and commit.
- Mark each claim as
source-backed or field-capture.
iOS (Telegram iOS)
Version snapshot:
- Repo/tag:
TelegramMessenger/Telegram-iOS build-26855
- Commit:
b16d9acdffa9b3f88db68e26b77a3713e87a92e3
Source-backed behavior:
- TCP connect timeout:
12s
- Response watchdog base:
MTMinTcpResponseTimeout = 12.0
- Response timeout includes payload-dependent term and resets on partial reads
- Transport-level watchdog:
20s
- Reconnect backoff steps (
1s, then 4s, then 8s)
Field-capture behavior (proxy-side observations):
- Pre-warms multiple idle sockets.
- Can split 64-byte obfuscation handshake across TLS records.
- May delay first payload after
ServerHello.
Proxy implications:
- Assemble handshake bytes until full 64-byte payload is complete.
- Keep generous handshake stage timeout; tighten only after relay is active.
- Do not treat short idle prewarmed sockets as protocol failure.
Android (Telegram Android)
Version snapshot:
- Repo/ref:
DrKLO/Telegram master (snapshot: 12.6.4 (6666))
- Commit:
009e97356f966bb81eceba113d210230bf383122
Source-backed behavior:
- Enables
TCP_NODELAY, switches socket to O_NONBLOCK, uses connect(..., EINPROGRESS) with edge-triggered epoll.
- Connect path chooses address family/static flags and sets per-type logical timeouts (
Proxy=5s, Generic=8/12s, Upload=25/40s, Push=20/30s).
- Timeout model is logical/internal (
setTimeout / checkTimeout).
- Explicit connection-type split (
Generic, Download, Upload, Push, Temp, Proxy) and multiple parallel slots.
Proxy implications:
- Expect several concurrent connection attempts from one device/session.
- Treat connect churn as normal; optimize for quick accept + cheap close path.
Desktop (Windows/Linux/macOS via Telegram Desktop)
Version snapshot:
- Repo/tag:
telegramdesktop/tdesktop v6.7.2
- Commit:
085c4ba65d1f8aa13abf0fd7fc8489f094552542
Source-backed behavior:
- Builds multiple test connections and chooses by priority.
- Wait-for-connected starts at
1000ms and grows on failures.
- TCP/HTTP transport full-connect timeout:
8s.
- Resolver path uses per-IP timeout
4000ms and scales by resolved IP count.
- After first success, may wait
2000ms for a better candidate.
Linux/macOS note:
- In reviewed MTProto sources, timeout/retry logic is shared with Windows path (no observed OS-specific branching there).
- Validate package/channel specifics separately (Snap/DEB/Flatpak/macOS build IDs) before asserting behavioral deltas.
Proxy implications:
- Expect candidate racing and early cancellation patterns.
- Keep reconnect path cheap and non-blocking.
- Do not overfit timeout policy to a single desktop platform.
Practical Use Checklist
- If one platform fails and others pass, first compare known timeout model for that client.
- Verify whether failures happen pre-handshake, in 64-byte obfuscation phase, or after relay starts.
- Inspect whether client behavior is expected parallel racing vs actual proxy regression.
- Update this skill only with pinned sources or reproducible captures.
