From 70b357a3bd6f596212c2946f4ddbc8d8cef00f13 Mon Sep 17 00:00:00 2001
From: Alexey <247128645+axkurcom@users.noreply.github.com>
Date: Sat, 31 Oct 2026 12:51:59 +0300
Subject: [PATCH] Ping-Pong Comparison Diagrams + Mermaid Validation in
 AGENTS.md

---
 AGENTS.md                 |  8 ++++++++
 docs/WEB/PROXY_PING.de.md | 38 ++++++++++++++++++++++++++++++++++++++
 docs/WEB/PROXY_PING.en.md | 38 ++++++++++++++++++++++++++++++++++++++
 docs/WEB/PROXY_PING.ru.md | 38 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 122 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index d3f6f56..e88fe4e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -210,6 +210,14 @@ Use English for newly written or substantively updated source comments, document
 - Follow local formatting and naming patterns. Avoid style-only churn.
 - Remove an obsolete item only when doing so is necessary for the task; do not perform general warning or dead-code cleanup by default.
 
+### 12.1 Mermaid Diagram Validation
+
+- When adding or changing Mermaid diagrams, validate every Mermaid block in the affected documents, including localized versions, with a real Mermaid parser (`mermaid.parse`) or Mermaid CLI (`mmdc`). Checking Markdown fences alone is insufficient.
+- Fix parse errors before completing the change. For syntax fixes, reproduce the original failure before validating the correction when practical.
+- When changing diagram layout, also render and inspect readability, label clipping, and connections when a renderer is available.
+- Avoid unescaped semicolons in sequence-diagram labels and notes because Mermaid can interpret them as statement separators. Use commas or supported escaping instead.
+- Report the Mermaid version and actual validation results. Distinguish parser validation, rendering, and GitHub verification; mark checks that were not executed as **NOT RUN** or **BLOCKED**, as applicable.
+
 ## 13. Communication and Deliverables
 
 For a simple answer, answer directly. For a nontrivial implementation, briefly convey the plan, meaningful impact, and verification. Avoid repetitive process narration.
diff --git a/docs/WEB/PROXY_PING.de.md b/docs/WEB/PROXY_PING.de.md
index 2fd75f6..23808f6 100644
--- a/docs/WEB/PROXY_PING.de.md
+++ b/docs/WEB/PROXY_PING.de.md
@@ -75,6 +75,44 @@ Bei einer neuen Verbindung ohne Paketverlust benötigt der übliche TCP-Handshak
 
 Das anfängliche TLS für die Bridge liegt normalerweise vor der Android-Messung. Zusätzliche HTTP-Verbindungen oder ein WebSocket-Upgrade können noch innerhalb des Intervalls stattfinden; Verbindungswiederverwendung muss anhand eines Traces belegt werden. Persistente HTTPS-Verbindungen und bestehende WebSockets führen nicht für jeden Ping einen neuen TLS-Handshake aus. `cache: 'no-store'` steuert Caching, nicht die Wiederverwendung von TCP/TLS. Weder das Abschalten der Zertifikatsprüfung noch TLS 0-RTT ist zur Erklärung oder Diagnose erforderlich. Siehe [persistente HTTP-Verbindungen][http1] und [Bridge-Anfragen][request].
 
+## Zusätzliche Arbeit bei WEB gegenüber nativem MTProxy
+
+Die Darstellung trennt Arbeit vor dem Android-Timer von Arbeit, die in den angezeigten Wert eingehen kann. Als Basis dient Classic/DD über TCP. Bei EE gehört FakeTLS zum Aufbau des nativen Transports. Die Größe der Kästen und die Länge der Pfeile stellen keine Zeitdauer dar.
+
+```mermaid
+flowchart LR
+    subgraph N["Natives MTProxy: Classic/DD"]
+        direction TB
+        N0["Vor der Messung<br/>DNS + TCP + nativer Transportaufbau"] --> N1["Entfernter Transport bereit<br/>Anfragezeitstempel aktualisiert"]
+        N1 --> N2["MTProxy-Anfrage und Antwort<br/>Ausstehender Relay-Aufbau, Netzwerk, Warteschlangen, Telegram-DC"] --> N3["TL_pong empfangen<br/>Angezeigte Messung beendet"]
+    end
+    subgraph W["WEB: MTProxy in HTTPS oder WebSocket"]
+        direction TB
+        W0["Vor der Messung<br/>DNS + TCP + echtes TLS<br/>HTTP-Bridge + HELLO/WELCOME + 500 ms"] --> W1["Lokaler Socket bereit<br/>Anfragezeitstempel aktualisiert"]
+        W1 --> W2["Zusätzliche Client-Arbeit<br/>Java / WebView / JavaScript-Warteschlangen<br/>Entferntes OPEN eventuell noch ausstehend"] --> W3["Uplink-Verarbeitung<br/>HTTP-Upload oder WebSocket-Frame<br/>Frontend-Verarbeitung und mögliche Pufferung"]
+        W3 --> W4["Innere MTProxy-Anfrage und Antwort<br/>Ausstehender Relay-Aufbau, Netzwerk, Warteschlangen, Telegram-DC"] --> W5["Downlink-Verarbeitung<br/>HTTP-Poll oder WebSocket-Frame<br/>ACK/Commit-Freigabe und native Zustellwarteschlangen"]
+        W5 --> W6["TL_pong empfangen<br/>Angezeigte Messung beendet"]
+        X["Nur wenn eine weitere Verbindung nötig ist<br/>TCP + TLS, eventuell WebSocket-Upgrade<br/>Kein Handshake pro Ping bei Wiederverwendung"] -.-> W3
+        X -.-> W5
+        R["Nur bei Fehlern oder Überlastung<br/>Retries und Backoff<br/>Retry-After: 1 kann etwa eine Sekunde hinzufügen"] -.-> W3
+        R -.-> W5
+    end
+    classDef preparation fill:#eeeeee,stroke:#666666,color:#111111
+    classDef boundary fill:#dbeafe,stroke:#2563eb,color:#111111
+    classDef shared fill:#dcfce7,stroke:#15803d,color:#111111
+    classDef extra fill:#ffedd5,stroke:#c2410c,color:#111111
+    class N0,W0 preparation
+    class N1,N3,W1,W6 boundary
+    class N2,W4 shared
+    class W2,W3,W5,X,R extra
+```
+
+**Grau:** Arbeit vor der angezeigten Messung. **Blau:** Timer-Grenzen. **Grün:** MTProxy-Relay/DC-Arbeit in beiden Pfaden, deren tatsächliche Dauer abweichen kann. **Orange:** WEB-Transport- und Client-Arbeit innerhalb der Messung. **Gestrichelte Pfeile:** bedingter Verbindungsaufbau oder Retries, keine obligatorischen Phasen.
+
+Bei Wiederverwendung des Carriers entfällt der bedingte TCP/TLS/Upgrade-Aufwand. Framing, HTTP- oder WebSocket-Verarbeitung und Client-Warteschlangen bleiben bestehen. HTTP kann Up- und Downlink überlappen, sodass nicht jede Anfrage zwingend einen ganzen RTT hinzufügt. Polling wird bei verfügbaren Daten geweckt, und Frontend-Pufferung hängt von der Installation ab. Paketverlust, Netzwerküberlastung und Upstream-Aufbau können auch natives MTProxy verzögern.
+
+Die sichtbare Differenz kann somit verbleibenden WEB-Streamaufbau, zusätzliche Verbindungen, Transportverarbeitung und Scheduling sowie belegte Retries enthalten. Sie ist weder ein fester TLS-Zuschlag noch die arithmetische Summe aller Kästen. Der erste echte TLS-Handshake steht bewusst vor dem Android-Timer: Er beeinflusst die Gesamtdauer der Prüfung, normalerweise aber nicht den angezeigten Messwert. Da die Prüfung einen separaten Transport verwendet, garantiert eine aktive App-Verbindung auch keine warme Prüfung in der Proxyliste.
+
 ## HTTP, WebSocket und weitere Verzögerungen
 
 | Faktor | Auswirkung und Beleg |
diff --git a/docs/WEB/PROXY_PING.en.md b/docs/WEB/PROXY_PING.en.md
index e65b61c..2c37b0a 100644
--- a/docs/WEB/PROXY_PING.en.md
+++ b/docs/WEB/PROXY_PING.en.md
@@ -75,6 +75,44 @@ For a new connection without loss, the usual TCP handshake costs about one clien
 
 Initial bridge TLS normally occurs before Android's measurement. Additional HTTP connections or a WebSocket Upgrade can still occur inside it; connection reuse must be established from a trace. Persistent HTTPS and an established WebSocket do not perform a new TLS handshake for every ping. `cache: 'no-store'` controls caching, not TCP/TLS reuse. Neither disabling certificate checks nor enabling TLS 0-RTT is required to explain or diagnose this behavior. See [HTTP persistence][http1] and [bridge requests][request].
 
+## Where WEB adds work compared with native MTProxy
+
+The comparison below separates work before the Android timer from work that can enter the displayed sample. The baseline is Classic/DD over TCP. For EE, FakeTLS belongs to native transport setup. Box sizes and arrow lengths do not represent elapsed time.
+
+```mermaid
+flowchart LR
+    subgraph N["Native MTProxy: Classic/DD"]
+        direction TB
+        N0["Before measurement<br/>DNS + TCP + native transport setup"] --> N1["Remote transport ready<br/>Request timestamp refreshed"]
+        N1 --> N2["MTProxy request and response<br/>Relay setup still pending, network, queues, Telegram DC"] --> N3["TL_pong received<br/>Displayed sample ends"]
+    end
+    subgraph W["WEB: MTProxy inside HTTPS or WebSocket"]
+        direction TB
+        W0["Before measurement<br/>DNS + TCP + real TLS<br/>HTTP bridge + HELLO/WELCOME + 500 ms"] --> W1["Local socket ready<br/>Request timestamp refreshed"]
+        W1 --> W2["Extra client work<br/>Java / WebView / JavaScript queues<br/>Remote OPEN may still be pending"] --> W3["Uplink carrier work<br/>HTTP upload or WebSocket frame<br/>Frontend handling and possible buffering"]
+        W3 --> W4["Inner MTProxy request and response<br/>Relay setup still pending, network, queues, Telegram DC"] --> W5["Downlink carrier work<br/>HTTP poll or WebSocket frame<br/>ACK/commit gate, native delivery queues"]
+        W5 --> W6["TL_pong received<br/>Displayed sample ends"]
+        X["Only if another connection is needed<br/>TCP + TLS, possible WebSocket Upgrade<br/>No handshake per ping on a reused connection"] -.-> W3
+        X -.-> W5
+        R["Only on errors or overload<br/>Retries and backoff<br/>Retry-After: 1 can add about one second"] -.-> W3
+        R -.-> W5
+    end
+    classDef preparation fill:#eeeeee,stroke:#666666,color:#111111
+    classDef boundary fill:#dbeafe,stroke:#2563eb,color:#111111
+    classDef shared fill:#dcfce7,stroke:#15803d,color:#111111
+    classDef extra fill:#ffedd5,stroke:#c2410c,color:#111111
+    class N0,W0 preparation
+    class N1,N3,W1,W6 boundary
+    class N2,W4 shared
+    class W2,W3,W5,X,R extra
+```
+
+**Gray:** work before the displayed sample. **Blue:** timer boundaries. **Green:** MTProxy relay/DC work present in both paths, whose actual cost can differ. **Orange:** WEB carrier and client work inside the sample. **Dashed arrows:** conditional connection setup or retries, not obligatory stages.
+
+On a reused carrier, the conditional TCP/TLS/Upgrade cost disappears, while framing, HTTP or WebSocket handling and client queues remain. HTTP can overlap uplink and downlink; it does not necessarily add a whole RTT for every request. Polling wakes on data, and frontend buffering is deployment-dependent. Any delay from loss, congestion or upstream setup may also affect native MTProxy.
+
+Thus the visible difference can include remaining WEB stream setup, additional connection setup, carrier handling and scheduling, plus retries when observed. It is not a fixed TLS surcharge or an arithmetic sum of all boxes. The initial real TLS handshake is shown outside the Android timer deliberately: it affects total time to check, but normally not the displayed sample. The separate checker transport also means that an active app connection does not guarantee a warm proxy-list check.
+
 ## HTTP, WebSocket and other delay sources
 
 | Factor | Effect and evidence |
diff --git a/docs/WEB/PROXY_PING.ru.md b/docs/WEB/PROXY_PING.ru.md
index ec5afba..fa45cf6 100644
--- a/docs/WEB/PROXY_PING.ru.md
+++ b/docs/WEB/PROXY_PING.ru.md
@@ -75,6 +75,44 @@ sequenceDiagram
 
 Начальный TLS для загрузки моста обычно происходит до измерения Android. Дополнительные HTTP-соединения или WebSocket Upgrade могут оказаться внутри него; повторное использование соединений нужно подтверждать трассировкой. Постоянное HTTPS-соединение и установленный WebSocket не выполняют новый TLS-handshake для каждого ping. `cache: 'no-store'` управляет кешированием, а не повторным использованием TCP/TLS. Для объяснения и диагностики не требуется отключать проверку сертификатов или включать TLS 0-RTT. См. [постоянные HTTP-соединения][http1] и [запросы моста][request].
 
+## Где WEB добавляет работу относительно обычного MTProxy
+
+На схеме разделены этапы до запуска таймера Android и работа, которая может попасть в показанный результат. Базовый вариант — Classic/DD поверх TCP. Для EE FakeTLS относится к подготовке нативного транспорта. Размеры блоков и длины стрелок не обозначают длительность.
+
+```mermaid
+flowchart LR
+    subgraph N["Обычный MTProxy: Classic/DD"]
+        direction TB
+        N0["До измерения<br/>DNS + TCP + подготовка нативного транспорта"] --> N1["Удалённый транспорт готов<br/>Временная метка запроса обновлена"]
+        N1 --> N2["Запрос и ответ MTProxy<br/>Оставшаяся подготовка relay, сеть, очереди, Telegram DC"] --> N3["Получен TL_pong<br/>Отображаемый замер завершён"]
+    end
+    subgraph W["WEB: MTProxy внутри HTTPS или WebSocket"]
+        direction TB
+        W0["До измерения<br/>DNS + TCP + настоящий TLS<br/>HTTP-мост + HELLO/WELCOME + 500 мс"] --> W1["Локальный сокет готов<br/>Временная метка запроса обновлена"]
+        W1 --> W2["Дополнительная работа клиента<br/>Очереди Java / WebView / JavaScript<br/>Удалённый OPEN ещё может быть не завершён"] --> W3["Работа транспорта на отправке<br/>HTTP upload или кадр WebSocket<br/>Обработка фронтендом и возможная буферизация"]
+        W3 --> W4["Внутренний запрос и ответ MTProxy<br/>Оставшаяся подготовка relay, сеть, очереди, Telegram DC"] --> W5["Работа транспорта на приёме<br/>HTTP poll или кадр WebSocket<br/>Ожидание ACK/commit и очереди доставки в native"]
+        W5 --> W6["Получен TL_pong<br/>Отображаемый замер завершён"]
+        X["Только если нужно ещё одно соединение<br/>TCP + TLS, возможный WebSocket Upgrade<br/>При переиспользовании нет handshake на каждый ping"] -.-> W3
+        X -.-> W5
+        R["Только при ошибках или перегрузке<br/>Повторы и backoff<br/>Retry-After: 1 может добавить около секунды"] -.-> W3
+        R -.-> W5
+    end
+    classDef preparation fill:#eeeeee,stroke:#666666,color:#111111
+    classDef boundary fill:#dbeafe,stroke:#2563eb,color:#111111
+    classDef shared fill:#dcfce7,stroke:#15803d,color:#111111
+    classDef extra fill:#ffedd5,stroke:#c2410c,color:#111111
+    class N0,W0 preparation
+    class N1,N3,W1,W6 boundary
+    class N2,W4 shared
+    class W2,W3,W5,X,R extra
+```
+
+**Серый:** работа до отображаемого замера. **Синий:** границы таймера. **Зелёный:** работа MTProxy relay/DC, присутствующая в обоих путях, но не обязательно одинаковая по длительности. **Оранжевый:** работа WEB-транспорта и клиента внутри замера. **Пунктир:** условные затраты на соединения или повторы, а не обязательные этапы.
+
+При повторном использовании транспорта условные затраты на TCP/TLS/Upgrade исчезают, но остаются формирование кадров, обработка HTTP или WebSocket и очереди клиента. HTTP может совмещать отправку и приём: каждый запрос не обязательно добавляет целый RTT. Polling пробуждается при появлении данных, а буферизация фронтенда зависит от развёртывания. Потери, перегрузка сети и подготовка upstream могут задерживать и обычный MTProxy.
+
+Таким образом, в видимую разницу могут войти оставшееся открытие WEB-потока, дополнительные соединения, обработка транспорта, планирование и подтверждённые повторы. Это не фиксированная надбавка TLS и не арифметическая сумма блоков. Начальный настоящий TLS намеренно показан до таймера Android: он влияет на полное время проверки, но обычно не на отображаемый замер. Отдельный транспорт проверки также означает, что активное соединение приложения не гарантирует прогретую проверку в списке прокси.
+
 ## HTTP, WebSocket и другие источники задержки
 
 | Фактор | Влияние и подтверждение |