Merge 4d83d02a8f into b9b1271f14

Update CONFIG_PARAMS, QUICK_START_GUIDE and FAQ

docs/CONFIG_PARAMS.en.md

@@ -50,6 +50,8 @@ This document lists all configuration keys accepted by `config.toml`.
 | me_d2c_flush_batch_max_bytes | `usize` | `131072` | `4096..=2_097_152`. | Max ME->client payload bytes coalesced before flush. |
 | me_d2c_flush_batch_max_delay_us | `u64` | `500` | `0..=5000`. | Max microsecond wait for coalescing more ME->client frames (`0` disables timed coalescing). |
 | me_d2c_ack_flush_immediate | `bool` | `true` | — | Flushes client writer immediately after quick-ack write. |
+| me_quota_soft_overshoot_bytes | `u64` | `65536` | `0..=16_777_216`. | Extra per-route quota allowance (bytes) tolerated before writer-side quota enforcement drops route data. |
+| me_d2c_frame_buf_shrink_threshold_bytes | `usize` | `262144` | `4096..=16_777_216`. | Threshold for shrinking oversized ME->client frame-aggregation buffers after flush. |
 | direct_relay_copy_buf_c2s_bytes | `usize` | `65536` | `4096..=1_048_576`. | Copy buffer size for client->DC direction in direct relay. |
 | direct_relay_copy_buf_s2c_bytes | `usize` | `262144` | `8192..=2_097_152`. | Copy buffer size for DC->client direction in direct relay. |
 | crypto_pending_buffer | `usize` | `262144` | — | Max pending ciphertext buffer per client writer (bytes). |
@@ -243,6 +245,10 @@ Note: When `server.proxy_protocol` is enabled, incoming PROXY protocol headers a
 | Parameter | Type | Default | Constraints / validation | Description |
 |---|---|---|---|---|
 | client_handshake | `u64` | `30` | — | Client handshake timeout. |
+| relay_idle_policy_v2_enabled | `bool` | `true` | — | Enables soft/hard middle-relay client idle policy. |
+| relay_client_idle_soft_secs | `u64` | `120` | Must be `> 0`; must be `<= relay_client_idle_hard_secs`. | Soft idle threshold for middle-relay client uplink inactivity (seconds). |
+| relay_client_idle_hard_secs | `u64` | `360` | Must be `> 0`; must be `>= relay_client_idle_soft_secs`. | Hard idle threshold for middle-relay client uplink inactivity (seconds). |
+| relay_idle_grace_after_downstream_activity_secs | `u64` | `30` | Must be `<= relay_client_idle_hard_secs`. | Extra hard-idle grace after recent downstream activity (seconds). |
 | tg_connect | `u64` | `10` | — | Upstream Telegram connect timeout. |
 | client_keepalive | `u64` | `15` | — | Client keepalive timeout. |
 | client_ack | `u64` | `90` | — | Client ACK timeout. |
@@ -255,6 +261,9 @@ Note: When `server.proxy_protocol` is enabled, incoming PROXY protocol headers a
 |---|---|---|---|---|
 | tls_domain | `String` | `"petrovich.ru"` | — | Primary TLS domain used in fake TLS handshake profile. |
 | tls_domains | `String[]` | `[]` | — | Additional TLS domains for generating multiple links. |
+| unknown_sni_action | `"drop" \| "mask"` | `"drop"` | — | Action for TLS ClientHello with unknown/non-configured SNI. |
+| tls_fetch_scope | `String` | `""` | Value is trimmed during load; empty keeps default upstream routing behavior. | Upstream scope tag used for TLS-front metadata fetches. |
+| tls_fetch | `Table` | built-in defaults | See `[censorship.tls_fetch]` section below. | TLS-front metadata fetch strategy settings. |
 | mask | `bool` | `true` | — | Enables masking/fronting relay mode. |
 | mask_host | `String \| null` | `null` | — | Upstream mask host for TLS fronting relay. |
 | mask_port | `u16` | `443` | — | Upstream mask port for TLS fronting relay. |
@@ -280,6 +289,18 @@ Note: When `server.proxy_protocol` is enabled, incoming PROXY protocol headers a
 | mask_timing_normalization_floor_ms | `u64` | `0` | Must be `> 0` when timing normalization is enabled; must be `<= ceiling`. | Lower bound (ms) for masking outcome normalization target. |
 | mask_timing_normalization_ceiling_ms | `u64` | `0` | Must be `>= floor`; must be `<= 60000`. | Upper bound (ms) for masking outcome normalization target. |
 
+## [censorship.tls_fetch]
+
+| Parameter | Type | Default | Constraints / validation | Description |
+|---|---|---|---|---|
+| profiles | `("modern_chrome_like" \| "modern_firefox_like" \| "compat_tls12" \| "legacy_minimal")[]` | `["modern_chrome_like", "modern_firefox_like", "compat_tls12", "legacy_minimal"]` | Empty list falls back to defaults; values are deduplicated preserving order. | Ordered ClientHello profile fallback chain for TLS-front metadata fetch. |
+| strict_route | `bool` | `true` | — | Fails closed on upstream-route connect errors instead of falling back to direct TCP when route is configured. |
+| attempt_timeout_ms | `u64` | `5000` | Must be `> 0`. | Timeout budget per one TLS-fetch profile attempt (ms). |
+| total_budget_ms | `u64` | `15000` | Must be `> 0`. | Total wall-clock budget across all TLS-fetch attempts (ms). |
+| grease_enabled | `bool` | `false` | — | Enables GREASE-style random values in selected ClientHello extensions for fetch traffic. |
+| deterministic | `bool` | `false` | — | Enables deterministic ClientHello randomness for debugging/tests. |
+| profile_cache_ttl_secs | `u64` | `600` | `0` disables cache. | TTL for winner-profile cache entries used by TLS fetch path. |
+
 ### Shape-channel hardening notes (`[censorship]`)
 
 These parameters are designed to reduce one specific fingerprint source during masking: the exact number of bytes sent from proxy to `mask_host` for invalid or probing traffic.

docs/FAQ.en.md

@@ -63,9 +63,12 @@ user3 = "00000000000000000000000000000003"
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
+## "Unknown TLS SNI" Error
+You probably updated tls_domain, but users are still connecting via old links with the previous domain.
+
 ## How to view metrics
 
-1. Open the config `nano /etc/telemt.toml`
+1. Open the config `nano /etc/telemt/telemt.toml`
 2. Add the following parameters
 ```toml
 [server]

docs/FAQ.ru.md

@@ -64,9 +64,12 @@ user3 = "00000000000000000000000000000003"
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
+## Ошибка "Unknown TLS SNI"
+Возможно, вы обновили tls_domain, но пользователи всё ещё пытаются подключаться по старым ссылкам с прежним доменом.
+
 ## Как посмотреть метрики
 
-1. Открыть конфиг `nano /etc/telemt.toml`
+1. Открыть конфиг `nano /etc/telemt/telemt.toml`
 2. Добавить следующие параметры
 ```toml
 [server]

docs/QUICK_START_GUIDE.en.md

@@ -27,12 +27,12 @@ chmod +x /bin/telemt
 
 **0. Check port and generate secrets**
 
-The port you have selected for use should be MISSING from the list, when:
+The port you have selected for use should not be in the list:
 ```bash
 netstat -lnp
 ```
 
-Generate 16 bytes/32 characters HEX with OpenSSL or another way:
+Generate 16 bytes/32 characters in HEX format with OpenSSL or another way:
 ```bash
 openssl rand -hex 16
 ```
@@ -50,7 +50,7 @@ Save the obtained result somewhere. You will need it later!
 
 **1. Place your config to /etc/telemt/telemt.toml**
 
-Create config directory:
+Create the config directory:
 ```bash
 mkdir /etc/telemt
 ```
@@ -59,7 +59,7 @@ Open nano
 ```bash
 nano /etc/telemt/telemt.toml
 ```
-paste your config
+Insert your configuration:
 
 ```toml
 # === General Settings ===
@@ -93,8 +93,9 @@ hello = "00000000000000000000000000000000"
 then Ctrl+S -> Ctrl+X to save
 
 > [!WARNING]
-> Replace the value of the hello parameter with the value you obtained in step 0. 
-> Replace the value of the tls_domain parameter with another website.
+> Replace the value of the hello parameter with the value you obtained in step 0.  
+> Additionally, change the value of the tls_domain parameter to a different website.
+> Changing the tls_domain parameter will break all links that use the old domain!
 
 ---
 
@@ -105,14 +106,14 @@ useradd -d /opt/telemt -m -r -U telemt
 chown -R telemt:telemt /etc/telemt
 ```
 
-**3. Create service on /etc/systemd/system/telemt.service**
+**3. Create service in /etc/systemd/system/telemt.service**
 
 Open nano
 ```bash
 nano /etc/systemd/system/telemt.service
 ```
 
-paste this Systemd Module
+Insert this Systemd module:
 ```bash
 [Unit]
 Description=Telemt
@@ -147,13 +148,16 @@ systemctl daemon-reload
 
 **6.** For automatic startup at system boot, enter `systemctl enable telemt`
 
-**7.** To get the link(s), enter
+**7.** To get the link(s), enter:
 ```bash
 curl -s http://127.0.0.1:9091/v1/users | jq
 ```
 
 > Any number of people can use one link.
 
+> [!WARNING]
+> Only the command from step 7 can provide a working link. Do not try to create it yourself or copy it from anywhere if you are not sure what you are doing!
+
 ---
 
 # Telemt via Docker Compose

docs/QUICK_START_GUIDE.ru.md

@@ -95,6 +95,7 @@ hello = "00000000000000000000000000000000"
 > [!WARNING]
 > Замените значение параметра hello на значение, которое вы получили в пункте 0.  
 > Так же замените значение параметра tls_domain на другой сайт.
+> Изменение параметра tls_domain сделает нерабочими все ссылки, использующие старый домен!
 
 ---
 

src/config/load.rs

@@ -346,6 +346,12 @@ impl ProxyConfig {
             ));
         }
 
+        if config.timeouts.tg_connect == 0 {
+            return Err(ProxyError::Config(
+                "timeouts.tg_connect must be > 0".to_string(),
+            ));
+        }
+
         if config.general.upstream_unhealthy_fail_threshold == 0 {
             return Err(ProxyError::Config(
                 "general.upstream_unhealthy_fail_threshold must be > 0".to_string(),
@@ -1905,6 +1911,26 @@ mod tests {
         let _ = std::fs::remove_file(path);
     }
 
+    #[test]
+    fn tg_connect_zero_is_rejected() {
+        let toml = r#"
+            [timeouts]
+            tg_connect = 0
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_tg_connect_zero_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("timeouts.tg_connect must be > 0"));
+        let _ = std::fs::remove_file(path);
+    }
+
     #[test]
     fn rpc_proxy_req_every_out_of_range_is_rejected() {
         let toml = r#"

src/maestro/mod.rs

@@ -225,6 +225,7 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
         config.general.upstream_connect_retry_attempts,
         config.general.upstream_connect_retry_backoff_ms,
         config.general.upstream_connect_budget_ms,
+        config.timeouts.tg_connect,
         config.general.upstream_unhealthy_fail_threshold,
         config.general.upstream_connect_failfast_hard_errors,
         stats.clone(),

src/transport/upstream.rs

@@ -34,8 +34,6 @@ const NUM_DCS: usize = 5;
 
 /// Timeout for individual DC ping attempt
 const DC_PING_TIMEOUT_SECS: u64 = 5;
-/// Timeout for direct TG DC TCP connect readiness.
-const DIRECT_CONNECT_TIMEOUT_SECS: u64 = 10;
 /// Interval between upstream health-check cycles.
 const HEALTH_CHECK_INTERVAL_SECS: u64 = 30;
 /// Timeout for a single health-check connect attempt.
@@ -319,6 +317,8 @@ pub struct UpstreamManager {
     connect_retry_attempts: u32,
     connect_retry_backoff: Duration,
     connect_budget: Duration,
+    /// Per-attempt TCP connect timeout to Telegram DC (`[timeouts] tg_connect`, seconds).
+    tg_connect_timeout_secs: u64,
     unhealthy_fail_threshold: u32,
     connect_failfast_hard_errors: bool,
     no_upstreams_warn_epoch_ms: Arc<AtomicU64>,
@@ -332,6 +332,7 @@ impl UpstreamManager {
         connect_retry_attempts: u32,
         connect_retry_backoff_ms: u64,
         connect_budget_ms: u64,
+        tg_connect_timeout_secs: u64,
         unhealthy_fail_threshold: u32,
         connect_failfast_hard_errors: bool,
         stats: Arc<Stats>,
@@ -347,6 +348,7 @@ impl UpstreamManager {
             connect_retry_attempts: connect_retry_attempts.max(1),
             connect_retry_backoff: Duration::from_millis(connect_retry_backoff_ms),
             connect_budget: Duration::from_millis(connect_budget_ms.max(1)),
+            tg_connect_timeout_secs: tg_connect_timeout_secs.max(1),
             unhealthy_fail_threshold: unhealthy_fail_threshold.max(1),
             connect_failfast_hard_errors,
             no_upstreams_warn_epoch_ms: Arc::new(AtomicU64::new(0)),
@@ -797,8 +799,8 @@ impl UpstreamManager {
                 break;
             }
             let remaining_budget = self.connect_budget.saturating_sub(elapsed);
-            let attempt_timeout =
-                Duration::from_secs(DIRECT_CONNECT_TIMEOUT_SECS).min(remaining_budget);
+            let attempt_timeout = Duration::from_secs(self.tg_connect_timeout_secs)
+                .min(remaining_budget);
             if attempt_timeout.is_zero() {
                 last_error = Some(ProxyError::ConnectionTimeout {
                     addr: target.to_string(),
@@ -1901,6 +1903,7 @@ mod tests {
             1,
             100,
             1000,
+            10,
             1,
             false,
             Arc::new(Stats::new()),