Bump

Update Cargo.lock
API Fixes + Exclusive Mask + Startup Speed-up + IDN + Decomposing hot-path modules: merge pull request #796 from telemt/flow
2026-06-19 01:11:09 +03:00 · 2026-05-22 11:00:41 +03:00 · 2026-05-22 11:00:18 +03:00 · 2026-05-22 10:55:26 +03:00 · 2026-05-21 23:45:54 +03:00 · 2026-05-21 20:35:25 +03:00
173 changed files with 33183 additions and 13501 deletions
@@ -191,6 +191,11 @@ When facing a non-trivial modification, follow this sequence:
 4. **Implement**: Make the minimal, isolated change.
 5. **Verify**: Explain why the change preserves existing behavior and architectural integrity.

+When the repository contains a `PLAN.md` for the current task, maintain it as
+a working checkbox plan while implementing changes. Mark completed and partial
+items in `PLAN.md` as the code changes land, so the remaining work stays
+explicit and future passes do not waste time rediscovering status.
+
 ---

 ### 9. Context Awareness
@@ -222,10 +227,9 @@ Your response MUST consist of two sections:

 **Section 2: `## Changes`**

- For each modified or created file: the filename on a separate line in backticks, followed by the code block.
- For files **under 200 lines**: return the full file with all changes applied.
- For files **over 200 lines**: return only the changed functions/blocks with at least 3 lines of surrounding context above and below. If the user requests the full file, provide it.
- New files: full file content.
+- For each modified or created file: the filename on a separate line in backticks, followed by a concise description of what changed.
+- Do not include full file contents or long code blocks in `## Changes` unless the user explicitly asks for code text.
+- If code snippets are necessary, include only the minimal relevant excerpt.
 - End with a suggested git commit message in English.

 #### Reporting Out-of-Scope Issues
@@ -429,4 +433,3 @@ Every patch must be **atomic and production-safe**.
 * **No transitional states** — no placeholders, incomplete refactors, or temporary inconsistencies.

 **Invariant:** After any single patch, the repository remains fully functional and buildable.
-
@@ -52,6 +52,10 @@ By submitting a PR, you confirm that:

 AI-generated code is treated as **draft** and must be validated like any other external contribution.

+The problem isn’t AI as a tool, but the dilution of responsibility. If the commit history says "Claude/GPT authored this", then who is accountable for the bug? Claude? GPT? Anthropic? OpenAI? Samuel Altman?
+
+The user who didn’t read the diff? No one? But, in a sensitive system, *"no one"* is an unacceptable maintainer model.
+
 PRs that look like unverified AI dumps WILL be closed

 ---
@@ -79,4 +83,4 @@ This includes (but is not limited to):
 - unverified or low-effort changes
 - inability to explain the change

-These actions follow the Code of Conduct and are intended to preserve signal, quality, and Telemt's integrity
+These actions follow the Code of Conduct and are intended to preserve signal, quality, and Telemt's integrity
@@ -90,9 +90,9 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"

 [[package]]
 name = "arc-swap"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a07d1f37ff60921c83bdfc7407723bdefe89b44b98a9b772f225c8f9d67141a6"
+checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"
 dependencies = [
 "rustversion",
 ]
@@ -173,9 +173,9 @@ checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"

 [[package]]
 name = "aws-lc-rs"
-version = "1.16.2"
+version = "1.16.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a054912289d18629dc78375ba2c3726a3afe3ff71b4edba9dedfca0e3446d1fc"
+checksum = "0ec6fb3fe69024a75fa7e1bfb48aa6cf59706a101658ea01bfd33b2b248a038f"
 dependencies = [
 "aws-lc-sys",
 "zeroize",
@@ -183,9 +183,9 @@ dependencies = [

 [[package]]
 name = "aws-lc-sys"
-version = "0.39.1"
+version = "0.40.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83a25cf98105baa966497416dbd42565ce3a8cf8dbfd59803ec9ad46f3126399"
+checksum = "f50037ee5e1e41e7b8f9d161680a725bd1626cb6f8c7e901f91f942850852fe7"
 dependencies = [
 "cc",
 "cmake",
@@ -228,9 +228,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"

 [[package]]
 name = "bitflags"
-version = "2.11.0"
+version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"

 [[package]]
 name = "blake3"
@@ -299,9 +299,9 @@ dependencies = [

 [[package]]
 name = "cc"
-version = "1.2.58"
+version = "1.2.60"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e1e928d4b69e3077709075a938a05ffbedfa53a84c8f766efbf8220bb1ff60e1"
+checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
 dependencies = [
 "find-msvc-tools",
 "jobserver",
@@ -346,7 +346,7 @@ checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
 dependencies = [
 "cfg-if",
 "cpufeatures 0.3.0",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
 ]

 [[package]]
@@ -416,9 +416,9 @@ dependencies = [

 [[package]]
 name = "clap"
-version = "4.6.0"
+version = "4.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
 dependencies = [
 "clap_builder",
 ]
@@ -805,9 +805,9 @@ dependencies = [

 [[package]]
 name = "fastrand"
-version = "2.3.0"
+version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"

 [[package]]
 name = "fiat-crypto"
@@ -997,7 +997,7 @@ dependencies = [
 "cfg-if",
 "libc",
 "r-efi 6.0.0",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
 "wasip2",
 "wasip3",
 ]
@@ -1068,6 +1068,12 @@ dependencies = [
 "foldhash 0.2.0",
 ]

+[[package]]
+name = "hashbrown"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"
+
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -1096,7 +1102,7 @@ dependencies = [
 "idna",
 "ipnet",
 "once_cell",
- "rand 0.9.2",
+ "rand 0.9.4",
 "ring",
 "thiserror 2.0.18",
 "tinyvec",
@@ -1118,7 +1124,7 @@ dependencies = [
 "moka",
 "once_cell",
 "parking_lot",
- "rand 0.9.2",
+ "rand 0.9.4",
 "resolv-conf",
 "smallvec",
 "thiserror 2.0.18",
@@ -1213,15 +1219,14 @@ dependencies = [

 [[package]]
 name = "hyper-rustls"
-version = "0.27.7"
+version = "0.27.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3c93eb611681b207e1fe55d5a71ecf91572ec8a6705cdb6857f7d8d5242cf58"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
 dependencies = [
 "http",
 "hyper",
 "hyper-util",
 "rustls",
- "rustls-pki-types",
 "tokio",
 "tokio-rustls",
 "tower-service",
@@ -1385,12 +1390,12 @@ dependencies = [

 [[package]]
 name = "indexmap"
-version = "2.13.0"
+version = "2.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
 "equivalent",
- "hashbrown 0.16.1",
+ "hashbrown 0.17.0",
 "serde",
 "serde_core",
 ]
@@ -1401,7 +1406,7 @@ version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bd5b3eaf1a28b758ac0faa5a4254e8ab2705605496f1b1f3fbbc3988ad73d199"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "inotify-sys",
 "libc",
 ]
@@ -1534,9 +1539,9 @@ dependencies = [

 [[package]]
 name = "js-sys"
-version = "0.3.94"
+version = "0.3.95"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e04e2ef80ce82e13552136fabeef8a5ed1f985a96805761cbb9a2c34e7664d9"
+checksum = "2964e92d1d9dc3364cae4d718d93f227e3abb088e747d92e0395bfdedf1c12ca"
 dependencies = [
 "cfg-if",
 "futures-util",
@@ -1578,9 +1583,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"

 [[package]]
 name = "libc"
-version = "0.2.184"
+version = "0.2.185"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"

 [[package]]
 name = "linux-raw-sys"
@@ -1611,9 +1616,9 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"

 [[package]]
 name = "lru"
-version = "0.16.3"
+version = "0.16.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a1dc47f592c06f33f8e3aea9591776ec7c9f9e4124778ff8a3c3b87159f7e593"
+checksum = "7f66e8d5d03f609abc3a39e6f08e4164ebf1447a732906d39eb9b99b7919ef39"
 dependencies = [
 "hashbrown 0.16.1",
 ]
@@ -1705,7 +1710,7 @@ version = "0.31.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d6d0705320c1e6ba1d912b5e37cf18071b6c2e9b7fa8215a1e8a7651966f5d3"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "cfg-if",
 "cfg_aliases",
 "libc",
@@ -1728,7 +1733,7 @@ version = "8.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "fsevent-sys",
 "inotify",
 "kqueue",
@@ -1746,7 +1751,7 @@ version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "42b8cfee0e339a0337359f3c88165702ac6e600dc01c0cc9579a92d62b08477a"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 ]

 [[package]]
@@ -2012,9 +2017,9 @@ checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
 dependencies = [
 "bit-set",
 "bit-vec",
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "num-traits",
- "rand 0.9.2",
+ "rand 0.9.4",
 "rand_chacha",
 "rand_xorshift",
 "regex-syntax",
@@ -2059,7 +2064,7 @@ dependencies = [
 "bytes",
 "getrandom 0.3.4",
 "lru-slab",
- "rand 0.9.2",
+ "rand 0.9.4",
 "ring",
 "rustc-hash",
 "rustls",
@@ -2108,9 +2113,9 @@ checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"

 [[package]]
 name = "rand"
-version = "0.9.2"
+version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
+checksum = "44c5af06bb1b7d3216d91932aed5265164bf384dc89cd6ba05cf59a35f5f76ea"
 dependencies = [
 "rand_chacha",
 "rand_core 0.9.5",
@@ -2118,13 +2123,13 @@ dependencies = [

 [[package]]
 name = "rand"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc266eb313df6c5c09c1c7b1fbe2510961e5bcd3add930c1e31f7ed9da0feff8"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
 dependencies = [
 "chacha20 0.10.0",
 "getrandom 0.4.2",
- "rand_core 0.10.0",
+ "rand_core 0.10.1",
 ]

 [[package]]
@@ -2157,9 +2162,9 @@ dependencies = [

 [[package]]
 name = "rand_core"
-version = "0.10.0"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c8d0fd677905edcbeedbf2edb6494d676f0e98d54d5cf9bda0b061cb8fb8aba"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"

 [[package]]
 name = "rand_xorshift"
@@ -2172,9 +2177,9 @@ dependencies = [

 [[package]]
 name = "rayon"
-version = "1.11.0"
+version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "368f01d005bf8fd9b1206fb6fa653e6c4a81ceb1466406b81792d87c5677a58f"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
 dependencies = [
 "either",
 "rayon-core",
@@ -2196,7 +2201,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 ]

 [[package]]
@@ -2326,7 +2331,7 @@ version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "errno",
 "libc",
 "linux-raw-sys",
@@ -2335,9 +2340,9 @@ dependencies = [

 [[package]]
 name = "rustls"
-version = "0.23.37"
+version = "0.23.38"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "758025cb5fccfd3bc2fd74708fd4682be41d99e5dff73c377c0646c6012c73a4"
+checksum = "69f9466fb2c14ea04357e91413efb882e2a6d4a406e625449bc0a5d360d53a21"
 dependencies = [
 "aws-lc-rs",
 "once_cell",
@@ -2399,9 +2404,9 @@ checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"

 [[package]]
 name = "rustls-webpki"
-version = "0.103.10"
+version = "0.103.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df33b2b81ac578cabaf06b89b0631153a3f416b0a886e8a7a1707fb51abbd1ef"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
 dependencies = [
 "aws-lc-rs",
 "ring",
@@ -2474,7 +2479,7 @@ version = "3.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "core-foundation",
 "core-foundation-sys",
 "libc",
@@ -2493,9 +2498,9 @@ dependencies = [

 [[package]]
 name = "semver"
-version = "1.0.27"
+version = "1.0.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d767eb0aabc880b29956c35734170f26ed551a859dbd361d140cdbeca61ab1e2"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"

 [[package]]
 name = "sendfd"
@@ -2615,7 +2620,7 @@ dependencies = [
 "notify",
 "percent-encoding",
 "pin-project",
- "rand 0.9.2",
+ "rand 0.9.4",
 "sealed",
 "sendfd",
 "serde",
@@ -2646,7 +2651,7 @@ dependencies = [
 "chacha20poly1305",
 "hkdf",
 "md-5",
- "rand 0.9.2",
+ "rand 0.9.4",
 "ring-compat",
 "sha1",
 ]
@@ -2741,6 +2746,12 @@ version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"

+[[package]]
+name = "symlink"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7973cce6668464ea31f176d85b13c7ab3bba2cb3b77a2ed26abd7801688010a"
+
 [[package]]
 name = "syn"
 version = "2.0.117"
@@ -2780,7 +2791,7 @@ checksum = "7b2093cf4c8eb1e67749a6762251bc9cd836b6fc171623bd0a9d324d37af2417"

 [[package]]
 name = "telemt"
-version = "3.3.39"
+version = "3.4.12"
 dependencies = [
 "aes",
 "anyhow",
@@ -2812,7 +2823,7 @@ dependencies = [
 "num-traits",
 "parking_lot",
 "proptest",
- "rand 0.10.0",
+ "rand 0.10.1",
 "regex",
 "reqwest",
 "rustls",
@@ -2970,9 +2981,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"

 [[package]]
 name = "tokio"
-version = "1.50.0"
+version = "1.52.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d"
+checksum = "b67dee974fe86fd92cc45b7a95fdd2f99a36a6d7b0d431a231178d3d670bbcc6"
 dependencies = [
 "bytes",
 "libc",
@@ -2988,9 +2999,9 @@ dependencies = [

 [[package]]
 name = "tokio-macros"
-version = "2.6.1"
+version = "2.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c55a2eff8b69ce66c84f85e1da1c233edc36ceb85a2058d11b0d6a3c7e7569c"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -3123,7 +3134,7 @@ version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "bytes",
 "futures-util",
 "http",
@@ -3160,11 +3171,12 @@ dependencies = [

 [[package]]
 name = "tracing-appender"
-version = "0.2.4"
+version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "786d480bce6247ab75f005b14ae1624ad978d3029d9113f0a22fa1ac773faeaf"
+checksum = "050686193eb999b4bb3bc2acfa891a13da00f79734704c4b8b4ef1a10b368a3c"
 dependencies = [
 "crossbeam-channel",
+ "symlink",
 "thiserror 2.0.18",
 "time",
 "tracing-subscriber",
@@ -3239,9 +3251,9 @@ checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"

 [[package]]
 name = "typenum"
-version = "1.19.0"
+version = "1.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"

 [[package]]
 name = "unarray"
@@ -3297,9 +3309,9 @@ checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"

 [[package]]
 name = "uuid"
-version = "1.23.0"
+version = "1.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ac8b6f42ead25368cf5b098aeb3dc8a1a2c05a3eee8a9a1a68c640edbfc79d9"
+checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
 dependencies = [
 "getrandom 0.4.2",
 "js-sys",
@@ -3354,11 +3366,11 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"

 [[package]]
 name = "wasip2"
-version = "1.0.2+wasi-0.2.9"
+version = "1.0.3+wasi-0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
+checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.57.1",
 ]

 [[package]]
@@ -3367,14 +3379,14 @@ version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.51.0",
 ]

 [[package]]
 name = "wasm-bindgen"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0551fc1bb415591e3372d0bc4780db7e587d84e2a7e79da121051c5c4b89d0b0"
+checksum = "0bf938a0bacb0469e83c1e148908bd7d5a6010354cf4fb73279b7447422e3a89"
 dependencies = [
 "cfg-if",
 "once_cell",
@@ -3385,9 +3397,9 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.67"
+version = "0.4.68"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "03623de6905b7206edd0a75f69f747f134b7f0a2323392d664448bf2d3c5d87e"
+checksum = "f371d383f2fb139252e0bfac3b81b265689bf45b6874af544ffa4c975ac1ebf8"
 dependencies = [
 "js-sys",
 "wasm-bindgen",
@@ -3395,9 +3407,9 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fbdf9a35adf44786aecd5ff89b4563a90325f9da0923236f6104e603c7e86be"
+checksum = "eeff24f84126c0ec2db7a449f0c2ec963c6a49efe0698c4242929da037ca28ed"
 dependencies = [
 "quote",
 "wasm-bindgen-macro-support",
@@ -3405,9 +3417,9 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dca9693ef2bab6d4e6707234500350d8dad079eb508dca05530c85dc3a529ff2"
+checksum = "9d08065faf983b2b80a79fd87d8254c409281cf7de75fc4b773019824196c904"
 dependencies = [
 "bumpalo",
 "proc-macro2",
@@ -3418,9 +3430,9 @@ dependencies = [

 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.117"
+version = "0.2.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "39129a682a6d2d841b6c429d0c51e5cb0ed1a03829d8b3d1e69a011e62cb3d3b"
+checksum = "5fd04d9e306f1907bd13c6361b5c6bfc7b3b3c095ed3f8a9246390f8dbdee129"
 dependencies = [
 "unicode-ident",
 ]
@@ -3453,7 +3465,7 @@ version = "0.244.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "hashbrown 0.15.5",
 "indexmap",
 "semver",
@@ -3461,9 +3473,9 @@ dependencies = [

 [[package]]
 name = "web-sys"
-version = "0.3.94"
+version = "0.3.95"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cd70027e39b12f0849461e08ffc50b9cd7688d942c1c8e3c7b22273236b4dd0a"
+checksum = "4f2dfbb17949fa2088e5d39408c48368947b86f7834484e87b73de55bc14d97d"
 dependencies = [
 "js-sys",
 "wasm-bindgen",
@@ -3481,18 +3493,18 @@ dependencies = [

 [[package]]
 name = "webpki-root-certs"
-version = "1.0.6"
+version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "804f18a4ac2676ffb4e8b5b5fa9ae38af06df08162314f96a68d2a363e21a8ca"
+checksum = "f31141ce3fc3e300ae89b78c0dd67f9708061d1d2eda54b8209346fd6be9a92c"
 dependencies = [
 "rustls-pki-types",
 ]

 [[package]]
 name = "webpki-roots"
-version = "1.0.6"
+version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22cfaf3c063993ff62e73cb4311efde4db1efb31ab78a3e5c457939ad5cc0bed"
+checksum = "52f5ee44c96cf55f1b349600768e3ece3a8f26010c05265ab73f945bb1a2eb9d"
 dependencies = [
 "rustls-pki-types",
 ]
@@ -3841,6 +3853,12 @@ dependencies = [
 "wit-bindgen-rust-macro",
 ]

+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
 [[package]]
 name = "wit-bindgen-core"
 version = "0.51.0"
@@ -3890,7 +3908,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
 "anyhow",
- "bitflags 2.11.0",
+ "bitflags 2.11.1",
 "indexmap",
 "log",
 "serde",
@@ -3922,9 +3940,9 @@ dependencies = [

 [[package]]
 name = "writeable"
-version = "0.6.2"
+version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"

 [[package]]
 name = "x25519-dalek"
@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.3.39"
+version = "3.4.12"
 edition = "2024"

 [features]
@@ -98,4 +98,3 @@ harness = false
 [profile.release]
 lto = "fat"
 codegen-units = 1
-
@@ -77,6 +77,34 @@ COPY config.toml /app/config.toml

 EXPOSE 443 9090 9091

+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
+ENTRYPOINT ["/app/telemt"]
+CMD ["config.toml"]
+
+# ==========================
+# Production Netfilter Profile
+# ==========================
+FROM debian:12-slim AS prod-netfilter
+
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        conntrack \
+        nftables \
+        iptables; \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=minimal /telemt /app/telemt
+COPY config.toml /app/config.toml
+
+EXPOSE 443 9090 9091
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
 ENTRYPOINT ["/app/telemt"]
 CMD ["config.toml"]

@@ -94,5 +122,7 @@ USER nonroot:nonroot

 EXPOSE 443 9090 9091

+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["/app/telemt", "healthcheck", "/app/config.toml", "--mode", "liveness"]
+
 ENTRYPOINT ["/app/telemt"]
 CMD ["config.toml"]
@@ -1,6 +1,8 @@
 # Telemt - MTProxy on Rust + Tokio

-![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon) ![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social) ![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social) [![Telegram](https://img.shields.io/badge/Telegram-Chat-24a1de?logo=telegram&logoColor=24a1de)](https://t.me/telemtrs)
+[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members)
+
+[🇷🇺 README на русском](https://github.com/telemt/telemt/blob/main/README.ru.md)

 ***Löst Probleme, bevor andere überhaupt wissen, dass sie existieren*** / ***It solves problems before others even realize they exist***

@@ -12,7 +14,7 @@

 <p align="center">
  <a href="https://t.me/telemtrs">
-    <img src="/docs/assets/telegram_button.svg" width="150"/>
+    <img src="https://github.com/user-attachments/assets/30b7e7b9-974a-4e3d-aab6-b58a85de4507" width="240"/>
  </a>
 </p>

@@ -25,6 +27,7 @@ curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
 - [Quick Start Guide](docs/Quick_start/QUICK_START_GUIDE.en.md)
 - [Инструкция по быстрому запуску](docs/Quick_start/QUICK_START_GUIDE.ru.md)

+## Features
 Our implementation of **TLS-fronting** is one of the most deeply debugged, focused, advanced and *almost* **"behaviorally consistent to real"**:  we are confident we have it right - [see evidence on our validation and traces](docs/FAQ.en.md#recognizability-for-dpi-and-crawler)

 Our ***Middle-End Pool*** is fastest by design in standard scenarios, compared to other implementations of connecting to the Middle-End Proxy: non dramatically, but usual
@@ -96,7 +99,7 @@ Monero (XMR) directly:
 8Bk4tZEYPQWSypeD2hrUXG2rKbAKF16GqEN942ZdAP5cFdSqW6h4DwkP5cJMAdszzuPeHeHZPTyjWWFwzeFdjuci3ktfMoB
 ```

-All donations go toward infrastructure, development, and research.
+All donations go toward infrastructure, development and research


 ![telemt_scheme](docs/assets/telemt.png)
@@ -1,6 +1,6 @@
 # Telemt — MTProxy на Rust + Tokio

-![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon) ![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social) ![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social) [![Telegram](https://img.shields.io/badge/Telegram-Chat-24a1de?logo=telegram&logoColor=24a1de)](https://t.me/telemtrs)
+[![Latest Release](https://img.shields.io/github/v/release/telemt/telemt?color=neon)](https://github.com/telemt/telemt/releases/latest) [![Stars](https://img.shields.io/github/stars/telemt/telemt?style=social)](https://github.com/telemt/telemt/stargazers) [![Forks](https://img.shields.io/github/forks/telemt/telemt?style=social)](https://github.com/telemt/telemt/network/members) [![Telegram](https://img.shields.io/badge/Telegram-Chat-24a1de?logo=telegram&logoColor=24a1de)](https://t.me/telemtrs)

 ***Решает проблемы раньше, чем другие узнают об их существовании***

@@ -54,7 +54,6 @@ curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
 - [FAQ EN](docs/FAQ.en.md)

 ## Сборка
-
 ```bash
 # Клонируйте репозиторий
 git clone https://github.com/telemt/telemt 
@@ -63,7 +62,6 @@ cd telemt
 # Начните процесс сборки
 cargo build --release

-# Устройства с небольшим объёмом оперативной памяти (1 ГБ, например NanoPi Neo3 / Raspberry Pi Zero 2):
 # В текущем release-профиле используется lto = "fat" для максимальной оптимизации (см. Cargo.toml).
 # На системах с малым объёмом RAM (~1 ГБ) можно переопределить это значение на "thin".

@@ -87,4 +85,25 @@ telemt config.toml
 - Безопасность памяти;
 - Асинхронная архитектура Tokio.

+## Поддержать Telemt
+
+Telemt — это бесплатное программное обеспечение с открытым исходным кодом, разработанное в свободное время.
+Если оно оказалось вам полезным, вы можете поддержать дальнейшую разработку.
+
+Принимаемые криптовалюты (BTC, ETH, USDT, 350+ и другие):
+
+<p align="center">
+  <a href="https://nowpayments.io/donation?api_key=2bf1afd2-abc2-49f9-a012-f1e715b37223" target="_blank" rel="noreferrer noopener">
+    <img src="https://nowpayments.io/images/embeds/donation-button-white.svg" alt="Cryptocurrency & Bitcoin donation button by NOWPayments" height="80">
+  </a>
+</p>
+
+Monero (XMR) напрямую:
+
+```
+8Bk4tZEYPQWSypeD2hrUXG2rKbAKF16GqEN942ZdAP5cFdSqW6h4DwkP5cJMAdszzuPeHeHZPTyjWWFwzeFdjuci3ktfMoB
+```
+
+Все пожертвования пойдут на инфраструктуру, разработку и исследования.
+
 ![telemt_scheme](docs/assets/telemt.png)
@@ -32,13 +32,13 @@ show = "*"
 port = 443
 # proxy_protocol = false           # Enable if behind HAProxy/nginx with PROXY protocol
 # metrics_port = 9090
-# metrics_listen = "0.0.0.0:9090"  # Listen address for metrics (overrides metrics_port)
-# metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
+# metrics_listen = "127.0.0.1:9090" # Listen address for metrics (overrides metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]

 [server.api]
 enabled = true
-listen = "0.0.0.0:9091"
-whitelist = ["127.0.0.0/8"]
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
 minimal_runtime_enabled = false
 minimal_runtime_cache_ttl_ms = 1000

@@ -48,9 +48,12 @@ ip = "0.0.0.0"

 # === Anti-Censorship & Masking ===
 [censorship]
+# Fake-TLS / SNI masking domain used in generated ee-links.
+# Changing tls_domain invalidates previously generated TLS links.
 tls_domain = "petrovich.ru"
+
 mask = true
-tls_emulation = true        # Fetch real cert lengths and emulate TLS records
+tls_emulation = true         # Fetch real cert lengths and emulate TLS records
 tls_front_dir = "tlsfront"   # Cache directory for TLS emulation

 [access.users]
@@ -0,0 +1,10 @@
+services:
+  telemt:
+    build:
+      context: .
+      target: prod-netfilter
+    network_mode: host
+    ports: []
+    cap_add:
+      - NET_BIND_SERVICE
+      - NET_ADMIN
@@ -0,0 +1,8 @@
+services:
+  telemt:
+    build:
+      context: .
+      target: prod-netfilter
+    cap_add:
+      - NET_BIND_SERVICE
+      - NET_ADMIN
@@ -1,7 +1,9 @@
 services:
  telemt:
    image: ghcr.io/telemt/telemt:latest
-    build: .
+    build:
+      context: .
+      target: prod
    container_name: telemt
    restart: unless-stopped
    ports:
@@ -16,13 +18,18 @@ services:
      - /etc/telemt:rw,mode=1777,size=4m
    environment:
      - RUST_LOG=info
+    healthcheck:
+      test: [ "CMD", "/app/telemt", "healthcheck", "/etc/telemt/config.toml", "--mode", "liveness" ]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 20s
    # Uncomment this line if you want to use host network for IPv6, but bridge is default and usually better
    # network_mode: host
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
-      - NET_ADMIN
    read_only: true
    security_opt:
      - no-new-privileges:true
@@ -9,12 +9,12 @@ API runtime is configured in `[server.api]`.

 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
-| `enabled` | `bool` | `false` | Enables REST API listener. |
-| `listen` | `string` (`IP:PORT`) | `127.0.0.1:9091` | API bind address. |
-| `whitelist` | `CIDR[]` | `127.0.0.1/32, ::1/128` | Source IP allowlist. Empty list means allow all. |
+| `enabled` | `bool` | `true` | Enables REST API listener. |
+| `listen` | `string` (`IP:PORT`) | `0.0.0.0:9091` | API bind address. |
+| `whitelist` | `CIDR[]` | `127.0.0.0/8` | Source IP allowlist. Empty list means allow all. |
 | `auth_header` | `string` | `""` | Exact value for `Authorization` header. Empty disables header auth. |
-| `request_body_limit_bytes` | `usize` | `65536` | Maximum request body size. Must be `> 0`. |
-| `minimal_runtime_enabled` | `bool` | `false` | Enables runtime snapshot endpoints requiring ME pool read-lock aggregation. |
+| `request_body_limit_bytes` | `usize` | `65536` | Maximum request body size. Must be within `[1, 1048576]`. |
+| `minimal_runtime_enabled` | `bool` | `true` | Enables runtime snapshot endpoints requiring ME pool read-lock aggregation. |
 | `minimal_runtime_cache_ttl_ms` | `u64` | `1000` | Cache TTL for minimal snapshots. `0` disables cache; valid range is `[0, 60000]`. |
 | `runtime_edge_enabled` | `bool` | `false` | Enables runtime edge endpoints with cached aggregation payloads. |
 | `runtime_edge_cache_ttl_ms` | `u64` | `1000` | Cache TTL for runtime edge summary payloads. `0` disables cache. |
@@ -26,7 +26,7 @@ API runtime is configured in `[server.api]`.

 Runtime validation for API config:
 - `server.api.listen` must be a valid `IP:PORT`.
- `server.api.request_body_limit_bytes` must be `> 0`.
+- `server.api.request_body_limit_bytes` must be within `[1, 1048576]`.
 - `server.api.minimal_runtime_cache_ttl_ms` must be within `[0, 60000]`.
 - `server.api.runtime_edge_cache_ttl_ms` must be within `[0, 60000]`.
 - `server.api.runtime_edge_top_n` must be within `[1, 1000]`.
@@ -76,13 +76,14 @@ Requests are processed in this order:

 Notes:
 - Whitelist is evaluated against the direct TCP peer IP (`SocketAddr::ip`), without `X-Forwarded-For` support.
- `Authorization` check is exact string equality against configured `auth_header`.
+- `Authorization` check is exact constant-time byte equality against configured `auth_header`.

 ## Endpoint Matrix

 | Method | Path | Body | Success | `data` contract |
 | --- | --- | --- | --- | --- |
 | `GET` | `/v1/health` | none | `200` | `HealthData` |
+| `GET` | `/v1/health/ready` | none | `200` or `503` | `HealthReadyData` |
 | `GET` | `/v1/system/info` | none | `200` | `SystemInfoData` |
 | `GET` | `/v1/runtime/gates` | none | `200` | `RuntimeGatesData` |
 | `GET` | `/v1/runtime/initialization` | none | `200` | `RuntimeInitializationData` |
@@ -102,13 +103,50 @@ Notes:
 | `GET` | `/v1/runtime/me-selftest` | none | `200` | `RuntimeMeSelftestData` |
 | `GET` | `/v1/runtime/connections/summary` | none | `200` | `RuntimeEdgeConnectionsSummaryData` |
 | `GET` | `/v1/runtime/events/recent` | none | `200` | `RuntimeEdgeEventsData` |
+| `GET` | `/v1/stats/users/active-ips` | none | `200` | `UserActiveIps[]` |
 | `GET` | `/v1/stats/users` | none | `200` | `UserInfo[]` |
 | `GET` | `/v1/users` | none | `200` | `UserInfo[]` |
-| `POST` | `/v1/users` | `CreateUserRequest` | `201` | `CreateUserResponse` |
+| `POST` | `/v1/users` | `CreateUserRequest` | `201` or `202` | `CreateUserResponse` |
 | `GET` | `/v1/users/{username}` | none | `200` | `UserInfo` |
-| `PATCH` | `/v1/users/{username}` | `PatchUserRequest` | `200` | `UserInfo` |
-| `DELETE` | `/v1/users/{username}` | none | `200` | `string` (deleted username) |
-| `POST` | `/v1/users/{username}/rotate-secret` | `RotateSecretRequest` or empty body | `404` | `ErrorResponse` (`not_found`, current runtime behavior) |
+| `PATCH` | `/v1/users/{username}` | `PatchUserRequest` | `200` or `202` | `UserInfo` |
+| `DELETE` | `/v1/users/{username}` | none | `200` or `202` | `DeleteUserResponse` |
+| `POST` | `/v1/users/{username}/rotate-secret` | `RotateSecretRequest` or empty body | `200` or `202` | `CreateUserResponse` |
+| `POST` | `/v1/users/{username}/reset-quota` | empty body | `200` | `ResetUserQuotaResponse` |
+
+## Endpoint Behavior
+
+| Endpoint | Function |
+| --- | --- |
+| `GET /v1/health` | Returns basic API liveness and current `read_only` flag. |
+| `GET /v1/health/ready` | Returns readiness based on admission state and upstream health; returns `503` when not ready. |
+| `GET /v1/system/info` | Returns binary/build metadata, process uptime, config path/hash, and reload counters. |
+| `GET /v1/runtime/gates` | Returns admission, ME readiness, fallback/reroute, and startup gate state. |
+| `GET /v1/runtime/initialization` | Returns startup progress, ME initialization status, and per-component timeline. |
+| `GET /v1/limits/effective` | Returns effective timeout, upstream, ME, unique-IP, and TCP policy values after config defaults/resolution. |
+| `GET /v1/security/posture` | Returns current API/security/telemetry posture flags. |
+| `GET /v1/security/whitelist` | Returns configured API whitelist CIDRs. |
+| `GET /v1/stats/summary` | Returns compact core counters and classed failure counters. |
+| `GET /v1/stats/zero/all` | Returns zero-cost core, upstream, ME, pool, and desync counters. |
+| `GET /v1/stats/upstreams` | Returns upstream zero counters and, when enabled/available, runtime upstream health rows. |
+| `GET /v1/stats/minimal/all` | Returns cached minimal ME writer/DC/runtime/network-path snapshot. |
+| `GET /v1/stats/me-writers` | Returns cached ME writer coverage and per-writer status rows. |
+| `GET /v1/stats/dcs` | Returns cached per-DC endpoint/writer/load status rows. |
+| `GET /v1/runtime/me_pool_state` | Returns active/warm/pending/draining generation state, writer contour/health, and refill state. |
+| `GET /v1/runtime/me_quality` | Returns ME lifecycle counters, route-drop counters, family states, drain gate, and per-DC RTT/coverage. |
+| `GET /v1/runtime/upstream_quality` | Returns upstream policy/counters plus runtime upstream health rows when available. |
+| `GET /v1/runtime/nat_stun` | Returns NAT/STUN runtime flags, configured/live STUN servers, reflection cache, and backoff. |
+| `GET /v1/runtime/me-selftest` | Returns ME self-test state for KDF, time skew, IP family, PID, and SOCKS BND observations. |
+| `GET /v1/runtime/connections/summary` | Returns runtime-edge connection totals and top-N users by connections/throughput. |
+| `GET /v1/runtime/events/recent` | Returns recent API/runtime event records with optional `limit` query. |
+| `GET /v1/stats/users/active-ips` | Returns users that currently have non-empty active source-IP lists. |
+| `GET /v1/stats/users` | Alias of `GET /v1/users`; returns disk-first user views with runtime lag flag. |
+| `GET /v1/users` | Returns disk-first user views sorted by username. |
+| `POST /v1/users` | Creates a user and returns the effective user view plus secret. |
+| `GET /v1/users/{username}` | Returns one disk-first user view or `404` when absent. |
+| `PATCH /v1/users/{username}` | Updates selected per-user fields with JSON Merge Patch semantics. |
+| `DELETE /v1/users/{username}` | Deletes one user and related per-user access-map entries. |
+| `POST /v1/users/{username}/rotate-secret` | Rotates one user's secret and returns the effective secret. |
+| `POST /v1/users/{username}/reset-quota` | Resets one user's runtime quota counter and persists quota state. |

 ## Common Error Codes

@@ -118,7 +156,7 @@ Notes:
 | `401` | `unauthorized` | Missing/invalid `Authorization` when `auth_header` is configured. |
 | `403` | `forbidden` | Source IP is not allowed by whitelist. |
 | `403` | `read_only` | Mutating endpoint called while `read_only=true`. |
-| `404` | `not_found` | Unknown route, unknown user, or unsupported sub-route (including current `rotate-secret` route). |
+| `404` | `not_found` | Unknown route, unknown user, or unsupported sub-route. |
 | `405` | `method_not_allowed` | Unsupported method for `/v1/users/{username}` route shape. |
 | `409` | `revision_conflict` | `If-Match` revision mismatch. |
 | `409` | `user_exists` | User already exists on create. |
@@ -132,11 +170,12 @@ Notes:
 | Case | Behavior |
 | --- | --- |
 | Path matching | Exact match on `req.uri().path()`. Query string does not affect route matching. |
-| Trailing slash | Not normalized. Example: `/v1/users/` is `404`. |
+| Trailing slash | Trimmed for route matching when path length is greater than 1. Example: `/v1/users/` matches `/v1/users`. |
 | Username route with extra slash | `/v1/users/{username}/...` is not treated as user route and returns `404`. |
 | `PUT /v1/users/{username}` | `405 method_not_allowed`. |
 | `POST /v1/users/{username}` | `404 not_found`. |
-| `POST /v1/users/{username}/rotate-secret` | `404 not_found` in current release due route matcher limitation. |
+| `POST /v1/users/{username}/rotate-secret/` | Trailing slash is trimmed and the route matches `rotate-secret`. |
+| `POST /v1/users/{username}/reset-quota/` | Trailing slash is trimmed and the route matches `reset-quota`. |

 ## Body and JSON Semantics

@@ -146,7 +185,7 @@ Notes:
 - Invalid JSON returns `400 bad_request` (`Invalid JSON body`).
 - `Content-Type` is not required for JSON parsing.
 - Unknown JSON fields are ignored by deserialization.
- `PATCH` updates only provided fields and does not support explicit clearing of optional fields.
+- `PATCH` uses JSON Merge Patch semantics for optional per-user fields: omitted means unchanged, explicit `null` removes the config entry, and a non-null value sets it.
 - `If-Match` supports both quoted and unquoted values; surrounding whitespace is trimmed.

 ## Query Parameters
@@ -166,24 +205,43 @@ Notes:
 | `max_tcp_conns` | `usize` | no | Per-user concurrent TCP limit. |
 | `expiration_rfc3339` | `string` | no | RFC3339 expiration timestamp. |
 | `data_quota_bytes` | `u64` | no | Per-user traffic quota. |
+| `rate_limit_up_bps` | `u64` | no | Per-user upload rate limit in bytes per second. |
+| `rate_limit_down_bps` | `u64` | no | Per-user download rate limit in bytes per second. |
 | `max_unique_ips` | `usize` | no | Per-user unique source IP limit. |

 ### `PatchUserRequest`
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `secret` | `string` | no | Exactly 32 hex chars. |
-| `user_ad_tag` | `string` | no | Exactly 32 hex chars. |
-| `max_tcp_conns` | `usize` | no | Per-user concurrent TCP limit. |
-| `expiration_rfc3339` | `string` | no | RFC3339 expiration timestamp. |
-| `data_quota_bytes` | `u64` | no | Per-user traffic quota. |
-| `max_unique_ips` | `usize` | no | Per-user unique source IP limit. |
+| `user_ad_tag` | `string|null` | no | Exactly 32 hex chars; `null` removes the per-user ad tag. |
+| `max_tcp_conns` | `usize|null` | no | Per-user concurrent TCP limit; `null` removes the per-user override. |
+| `expiration_rfc3339` | `string|null` | no | RFC3339 expiration timestamp; `null` removes the expiration. |
+| `data_quota_bytes` | `u64|null` | no | Per-user traffic quota; `null` removes the per-user quota. |
+| `rate_limit_up_bps` | `u64|null` | no | Per-user upload rate limit in bytes per second; `null` removes the upload direction limit. |
+| `rate_limit_down_bps` | `u64|null` | no | Per-user download rate limit in bytes per second; `null` removes the download direction limit. |
+| `max_unique_ips` | `usize|null` | no | Per-user unique source IP limit; `null` removes the per-user override. |
+
+### `access.user_source_deny` via API
+- In current API surface, per-user deny-list is **not** exposed as a dedicated field in `CreateUserRequest` / `PatchUserRequest`.
+- Configure it in `config.toml` under `[access.user_source_deny]` and apply via normal config reload path.
+- Runtime behavior after apply:
+  - auth succeeds for username/secret
+  - source IP is checked against `access.user_source_deny[username]`
+  - on match, handshake is rejected with the same fail-closed outcome as invalid auth
+
+Example config:
+```toml
+[access.user_source_deny]
+alice = ["203.0.113.0/24", "2001:db8:abcd::/48"]
+bob = ["198.51.100.42/32"]
+```

 ### `RotateSecretRequest`
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
 | `secret` | `string` | no | Exactly 32 hex chars. If missing, generated automatically. |

-Note: the request contract is defined, but the corresponding route currently returns `404` (see routing edge cases).
+An empty request body is accepted and generates a new secret automatically.

 ## Response Data Contracts

@@ -193,15 +251,33 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `status` | `string` | Always `"ok"`. |
 | `read_only` | `bool` | Mirrors current API `read_only` mode. |

+### `HealthReadyData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `ready` | `bool` | `true` when admission is open and at least one upstream is healthy. |
+| `status` | `string` | `"ready"` or `"not_ready"`. |
+| `reason` | `string?` | `admission_closed` or `no_healthy_upstreams` when not ready. |
+| `admission_open` | `bool` | Current admission-gate state. |
+| `healthy_upstreams` | `usize` | Number of healthy upstream entries. |
+| `total_upstreams` | `usize` | Number of configured upstream entries. |
+
 ### `SummaryData`
 | Field | Type | Description |
 | --- | --- | --- |
 | `uptime_seconds` | `f64` | Process uptime in seconds. |
 | `connections_total` | `u64` | Total accepted client connections. |
 | `connections_bad_total` | `u64` | Failed/invalid client connections. |
+| `connections_bad_by_class` | `ClassCount[]` | Failed/invalid connections grouped by class. |
+| `handshake_failures_by_class` | `ClassCount[]` | Handshake failures grouped by class. |
 | `handshake_timeouts_total` | `u64` | Handshake timeout count. |
 | `configured_users` | `usize` | Number of configured users in config. |

+#### `ClassCount`
+| Field | Type | Description |
+| --- | --- | --- |
+| `class` | `string` | Failure class label. |
+| `total` | `u64` | Counter value for this class. |
+
 ### `SystemInfoData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -226,7 +302,12 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `conditional_cast_enabled` | `bool` | Whether conditional ME admission logic is enabled (`general.use_middle_proxy`). |
 | `me_runtime_ready` | `bool` | Current ME runtime readiness status used for conditional gate decisions. |
 | `me2dc_fallback_enabled` | `bool` | Whether ME -> direct fallback is enabled. |
+| `me2dc_fast_enabled` | `bool` | Whether fast ME -> direct fallback is enabled. |
 | `use_middle_proxy` | `bool` | Current transport mode preference. |
+| `route_mode` | `string` | Current route mode label from route runtime controller. |
+| `reroute_active` | `bool` | `true` when ME fallback currently routes new sessions to Direct-DC. |
+| `reroute_to_direct_at_epoch_secs` | `u64?` | Unix timestamp when current direct reroute began. |
+| `reroute_reason` | `string?` | `startup_direct_fallback`, `fast_not_ready_fallback`, or `strict_grace_fallback` while reroute is active. |
 | `startup_status` | `string` | Startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
 | `startup_stage` | `string` | Current startup stage identifier. |
 | `startup_progress_pct` | `f64` | Startup progress percentage (`0..100`). |
@@ -277,11 +358,13 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `upstream` | `EffectiveUpstreamLimits` | Effective upstream connect/retry limits. |
 | `middle_proxy` | `EffectiveMiddleProxyLimits` | Effective ME pool/floor/reconnect limits. |
 | `user_ip_policy` | `EffectiveUserIpPolicyLimits` | Effective unique-IP policy mode/window. |
+| `user_tcp_policy` | `EffectiveUserTcpPolicyLimits` | Effective per-user TCP connection policy. |

 #### `EffectiveTimeoutLimits`
 | Field | Type | Description |
 | --- | --- | --- |
 | `client_handshake_secs` | `u64` | Client handshake timeout. |
+| `client_first_byte_idle_secs` | `u64` | First-byte idle timeout before protocol classification. |
 | `tg_connect_secs` | `u64` | Upstream Telegram connect timeout. |
 | `client_keepalive_secs` | `u64` | Client keepalive interval. |
 | `client_ack_secs` | `u64` | ACK timeout. |
@@ -320,13 +403,20 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `writer_pick_mode` | `string` | Writer picker mode (`sorted_rr`, `p2c`). |
 | `writer_pick_sample_size` | `u8` | Candidate sample size for `p2c` picker mode. |
 | `me2dc_fallback` | `bool` | Effective ME -> direct fallback flag. |
+| `me2dc_fast` | `bool` | Effective fast fallback flag. |

 #### `EffectiveUserIpPolicyLimits`
 | Field | Type | Description |
 | --- | --- | --- |
+| `global_each` | `usize` | Global per-user unique-IP limit applied when no per-user override exists. |
 | `mode` | `string` | Unique-IP policy mode (`active_window`, `time_window`, `combined`). |
 | `window_secs` | `u64` | Time window length used by unique-IP policy. |

+#### `EffectiveUserTcpPolicyLimits`
+| Field | Type | Description |
+| --- | --- | --- |
+| `global_each` | `usize` | Global per-user concurrent TCP limit applied when no per-user override exists. |
+
 ### `SecurityPostureData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -430,6 +520,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | --- | --- | --- |
 | `counters` | `RuntimeMeQualityCountersData` | Key ME lifecycle/error counters. |
 | `route_drops` | `RuntimeMeQualityRouteDropData` | Route drop counters by reason. |
+| `family_states` | `RuntimeMeQualityFamilyStateData[]` | Per-family ME route/recovery state rows. |
+| `drain_gate` | `RuntimeMeQualityDrainGateData` | Current ME drain-gate decision state. |
 | `dc_rtt` | `RuntimeMeQualityDcRttData[]` | Per-DC RTT and writer coverage rows. |

 #### `RuntimeMeQualityCountersData`
@@ -451,6 +543,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `queue_full_base_total` | `u64` | Route drops in base-queue path. |
 | `queue_full_high_total` | `u64` | Route drops in high-priority queue path. |

+#### `RuntimeMeQualityFamilyStateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `family` | `string` | Address family label. |
+| `state` | `string` | Current family state label. |
+| `state_since_epoch_secs` | `u64` | Unix timestamp when current state began. |
+| `suppressed_until_epoch_secs` | `u64?` | Unix timestamp until suppression remains active. |
+| `fail_streak` | `u32` | Consecutive failure count. |
+| `recover_success_streak` | `u32` | Consecutive recovery success count. |
+
+#### `RuntimeMeQualityDrainGateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `route_quorum_ok` | `bool` | Whether route quorum condition allows drain. |
+| `redundancy_ok` | `bool` | Whether redundancy condition allows drain. |
+| `block_reason` | `string` | Current drain block reason label. |
+| `updated_at_epoch_secs` | `u64` | Unix timestamp of the latest gate update. |
+
 #### `RuntimeMeQualityDcRttData`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -713,11 +823,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `uptime_seconds` | `f64` | Process uptime. |
 | `connections_total` | `u64` | Total accepted connections. |
 | `connections_bad_total` | `u64` | Failed/invalid connections. |
+| `connections_bad_by_class` | `ClassCount[]` | Failed/invalid connections grouped by class. |
+| `handshake_failures_by_class` | `ClassCount[]` | Handshake failures grouped by class. |
 | `handshake_timeouts_total` | `u64` | Handshake timeouts. |
+| `accept_permit_timeout_total` | `u64` | Listener admission permit acquisition timeouts. |
 | `configured_users` | `usize` | Configured user count. |
 | `telemetry_core_enabled` | `bool` | Core telemetry toggle. |
 | `telemetry_user_enabled` | `bool` | User telemetry toggle. |
 | `telemetry_me_level` | `string` | ME telemetry level (`off|normal|verbose`). |
+| `conntrack_control_enabled` | `bool` | Whether conntrack control is enabled by policy. |
+| `conntrack_control_available` | `bool` | Whether conntrack control backend is currently available. |
+| `conntrack_pressure_active` | `bool` | Current conntrack pressure flag. |
+| `conntrack_event_queue_depth` | `u64` | Current conntrack close-event queue depth. |
+| `conntrack_rule_apply_ok` | `bool` | Last conntrack rule application state. |
+| `conntrack_delete_attempt_total` | `u64` | Conntrack delete attempts. |
+| `conntrack_delete_success_total` | `u64` | Successful conntrack deletes. |
+| `conntrack_delete_not_found_total` | `u64` | Conntrack delete misses. |
+| `conntrack_delete_error_total` | `u64` | Conntrack delete errors. |
+| `conntrack_close_event_drop_total` | `u64` | Dropped conntrack close events. |

 #### `ZeroUpstreamData`
 | Field | Type | Description |
@@ -804,6 +927,24 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `route_drop_queue_full_total` | `u64` | Route drops due to full queue (total). |
 | `route_drop_queue_full_base_total` | `u64` | Route drops in base queue mode. |
 | `route_drop_queue_full_high_total` | `u64` | Route drops in high queue mode. |
+| `d2c_batches_total` | `u64` | ME D->C batch flushes. |
+| `d2c_batch_frames_total` | `u64` | ME D->C frames included in batches. |
+| `d2c_batch_bytes_total` | `u64` | ME D->C payload bytes included in batches. |
+| `d2c_flush_reason_queue_drain_total` | `u64` | Flushes caused by queue drain. |
+| `d2c_flush_reason_batch_frames_total` | `u64` | Flushes caused by frame-count batch limit. |
+| `d2c_flush_reason_batch_bytes_total` | `u64` | Flushes caused by byte-count batch limit. |
+| `d2c_flush_reason_max_delay_total` | `u64` | Flushes caused by max-delay budget. |
+| `d2c_flush_reason_ack_immediate_total` | `u64` | Flushes caused by immediate ACK policy. |
+| `d2c_flush_reason_close_total` | `u64` | Flushes caused by close path. |
+| `d2c_data_frames_total` | `u64` | ME D->C data frames. |
+| `d2c_ack_frames_total` | `u64` | ME D->C ACK frames. |
+| `d2c_payload_bytes_total` | `u64` | ME D->C payload bytes. |
+| `d2c_write_mode_coalesced_total` | `u64` | Coalesced D->C writes. |
+| `d2c_write_mode_split_total` | `u64` | Split D->C writes. |
+| `d2c_quota_reject_pre_write_total` | `u64` | D->C quota rejects before write. |
+| `d2c_quota_reject_post_write_total` | `u64` | D->C quota rejects after write. |
+| `d2c_frame_buf_shrink_total` | `u64` | D->C frame-buffer shrink operations. |
+| `d2c_frame_buf_shrink_bytes_total` | `u64` | Bytes released by D->C frame-buffer shrink operations. |
 | `socks_kdf_strict_reject_total` | `u64` | SOCKS KDF strict rejects. |
 | `socks_kdf_compat_fallback_total` | `u64` | SOCKS KDF compat fallbacks. |
 | `endpoint_quarantine_total` | `u64` | Endpoint quarantine activations. |
@@ -963,6 +1104,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `required_writers` | `usize` | Required writers based on current floor policy. |
 | `alive_writers` | `usize` | Writers currently alive. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+| `fresh_alive_writers` | `usize` | Alive writers that match freshness requirements. |
+| `fresh_coverage_pct` | `f64` | `fresh_alive_writers / required_writers * 100`. |

 #### `MeWriterStatus`
 | Field | Type | Description |
@@ -977,6 +1120,12 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `bound_clients` | `usize` | Number of currently bound clients. |
 | `idle_for_secs` | `u64?` | Idle age in seconds if idle. |
 | `rtt_ema_ms` | `f64?` | RTT exponential moving average. |
+| `matches_active_generation` | `bool` | Whether this writer belongs to the active pool generation. |
+| `in_desired_map` | `bool` | Whether this writer's endpoint remains in desired topology. |
+| `allow_drain_fallback` | `bool` | Whether drain fallback is allowed for this writer. |
+| `drain_started_at_epoch_secs` | `u64?` | Unix timestamp when drain started. |
+| `drain_deadline_epoch_secs` | `u64?` | Unix timestamp of drain deadline. |
+| `drain_over_ttl` | `bool` | Whether drain has exceeded its TTL. |

 ### `DcStatusData`
 | Field | Type | Description |
@@ -1001,6 +1150,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `floor_capped` | `bool` | `true` when computed floor target was capped by active limits. |
 | `alive_writers` | `usize` | Alive writers in this DC. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+| `fresh_alive_writers` | `usize` | Fresh alive writers in this DC. |
+| `fresh_coverage_pct` | `f64` | `fresh_alive_writers / required_writers * 100`. |
 | `rtt_ms` | `f64?` | Aggregated RTT for DC. |
 | `load` | `usize` | Active client sessions bound to this DC. |

@@ -1014,10 +1165,13 @@ Note: the request contract is defined, but the corresponding route currently ret
 | Field | Type | Description |
 | --- | --- | --- |
 | `username` | `string` | Username. |
+| `in_runtime` | `bool` | Whether current runtime config already contains this user. |
 | `user_ad_tag` | `string?` | Optional ad tag (32 hex chars). |
 | `max_tcp_conns` | `usize?` | Optional max concurrent TCP limit. |
 | `expiration_rfc3339` | `string?` | Optional expiration timestamp. |
 | `data_quota_bytes` | `u64?` | Optional data quota. |
+| `rate_limit_up_bps` | `u64?` | Optional upload rate limit in bytes per second. |
+| `rate_limit_down_bps` | `u64?` | Optional download rate limit in bytes per second. |
 | `max_unique_ips` | `usize?` | Optional unique IP limit. |
 | `current_connections` | `u64` | Current live connections. |
 | `active_unique_ips` | `usize` | Current active unique source IPs. |
@@ -1027,12 +1181,25 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `total_octets` | `u64` | Total traffic octets for this user. |
 | `links` | `UserLinks` | Active connection links derived from current config. |

+### `UserActiveIps`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Username with at least one active tracked source IP. |
+| `active_ips` | `ip[]` | Active source IPs for this user. |
+
 #### `UserLinks`
 | Field | Type | Description |
 | --- | --- | --- |
 | `classic` | `string[]` | Active `tg://proxy` links for classic mode. |
 | `secure` | `string[]` | Active `tg://proxy` links for secure/DD mode. |
 | `tls` | `string[]` | Active `tg://proxy` links for EE-TLS mode (for each host+TLS domain). |
+| `tls_domains` | `TlsDomainLink[]` | Extra TLS-domain links as explicit domain/link pairs for `censorship.tls_domains`. |
+
+#### `TlsDomainLink`
+| Field | Type | Description |
+| --- | --- | --- |
+| `domain` | `string` | TLS domain represented by the link. |
+| `link` | `string` | `tg://proxy` link for this domain. |

 Link generation uses active config and enabled modes:
 - Link port is `general.links.public_port` when configured; otherwise `server.port`.
@@ -1052,13 +1219,27 @@ Link generation uses active config and enabled modes:
 | `user` | `UserInfo` | Created or updated user view. |
 | `secret` | `string` | Effective user secret. |

+### `DeleteUserResponse`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Deleted username. |
+| `in_runtime` | `bool` | `true` when runtime config still contains the user and hot-reload has not applied deletion yet. |
+
+### `ResetUserQuotaResponse`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | User whose runtime quota counter was reset. |
+| `used_bytes` | `u64` | Current used bytes after reset; always `0` on success. |
+| `last_reset_epoch_secs` | `u64` | Unix timestamp of the reset operation. |
+
 ## Mutation Semantics

 | Endpoint | Notes |
 | --- | --- |
 | `POST /v1/users` | Creates user, validates config, then atomically updates only affected `access.*` TOML tables (`access.users` always, plus optional per-user tables present in request). |
-| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged. Current implementation persists full config document on success. |
-| `POST /v1/users/{username}/rotate-secret` | Currently returns `404` in runtime route matcher; request schema is reserved for intended behavior. |
+| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged; explicit `null` removes optional per-user entries. The write path updates only affected `access.*` TOML tables. |
+| `POST /v1/users/{username}/rotate-secret` | Replaces the user's secret with a provided valid 32-hex value or a generated value, then returns the effective secret in `CreateUserResponse`. |
+| `POST /v1/users/{username}/reset-quota` | Resets the runtime quota counter for the route username, persists quota state to `general.quota_state_path`, and does not modify user config. |
 | `DELETE /v1/users/{username}` | Deletes only specified user, removes this user from related optional `access.user_*` maps, blocks last-user deletion, and atomically updates only related `access.*` TOML tables. |

 All mutating endpoints:
@@ -1067,6 +1248,12 @@ All mutating endpoints:
 - Return new `revision` after successful write.
 - Use process-local mutation lock + atomic write (`tmp + rename`) for config persistence.

+Docker deployment note:
+- Mutating endpoints require `config.toml` to live inside a writable mounted directory.
+- Do not mount `config.toml` as a single bind-mounted file when API mutations are enabled; atomic `tmp + rename` writes can fail with `Device or resource busy`.
+- Mount the config directory instead, for example `./config:/etc/telemt:rw`, and start Telemt with `/etc/telemt/config.toml`.
+- A read-only single-file mount remains valid only for read-only deployments or when `[server.api].read_only=true`.
+
 Delete path cleanup guarantees:
 - Config cleanup removes only the requested username keys.
 - Runtime unique-IP cleanup removes only this user's limiter and tracked IP state.
@@ -1099,12 +1286,12 @@ Additional runtime endpoint behavior:
 ## ME Fallback Behavior Exposed Via API

 When `general.use_middle_proxy=true` and `general.me2dc_fallback=true`:
- Startup does not block on full ME pool readiness; initialization can continue in background.
+- Startup opens Direct-DC routing first, then initializes ME in background and switches new sessions to Middle mode after ME readiness is observed.
 - Runtime initialization payload can expose ME stage `background_init` until pool becomes ready.
 - Admission/routing decision uses two readiness grace windows for "ME not ready" periods:
-  `80s` before first-ever readiness is observed (startup grace),
+  direct startup fallback before first-ever readiness is observed,
  `6s` after readiness has been observed at least once (runtime failover timeout).
- While in fallback window breach, new sessions are routed via Direct-DC; when ME becomes ready, routing returns to Middle mode for new sessions.
+- While fallback is active, new sessions are routed via Direct-DC; when ME becomes ready, routing returns to Middle mode. Direct sessions affected by the cutover are closed with the existing staggered delay so clients reconnect through the current route.

 ## Serialization Rules

@@ -1133,5 +1320,4 @@ When `general.use_middle_proxy=true` and `general.me2dc_fallback=true`:

 ## Known Limitations (Current Release)

- `POST /v1/users/{username}/rotate-secret` is currently unreachable in route matcher and returns `404`.
 - API runtime controls under `server.api` are documented as restart-required; hot-reload behavior for these fields is not strictly uniform in all change combinations.
@@ -0,0 +1,266 @@
+# TLS Front Profile Fidelity
+
+## Overview
+
+This document describes how Telemt reuses captured TLS behavior in the FakeTLS server flight and how to validate the result on a real deployment.
+
+When TLS front emulation is enabled, Telemt can capture useful server-side TLS behavior from the selected origin and reuse that behavior in the emulated success path. The goal is not to reproduce the origin byte-for-byte, but to reduce stable synthetic traits and make the emitted server flight structurally closer to the captured profile.
+
+## Why this change exists
+
+The project already captures useful server-side TLS behavior in the TLS front fetch path:
+
+- `change_cipher_spec_count`
+- `app_data_record_sizes`
+- `ticket_record_sizes`
+
+Before this change, the emulator used only part of that information. This left a gap between captured origin behavior and emitted FakeTLS server flight.
+
+## What is implemented
+
+- The emulator now replays the observed `ChangeCipherSpec` count from the fetched behavior profile.
+- The emulator now replays observed ticket-like tail ApplicationData record sizes when raw or merged TLS profile data is available.
+- The emulator now preserves more of the profiled encrypted-flight structure instead of collapsing it into a smaller synthetic shape.
+- The emulator still falls back to the previous synthetic behavior when the cached profile does not contain raw TLS behavior information.
+- Operator-configured `tls_new_session_tickets` still works as an additive fallback when the profile does not provide enough tail records.
+
+## Practical benefit
+
+- Reduced distinguishability between profiled origin TLS behavior and emulated TLS behavior.
+- Lower chance of stable server-flight fingerprints caused by fixed CCS count or synthetic-only tail record sizes.
+- Better reuse of already captured TLS profile data without changing MTProto logic, KDF routing, or transport architecture.
+
+## Limitations
+
+This mechanism does not aim to make Telemt byte-identical to the origin server.
+
+It also does not change:
+
+- MTProto business logic;
+- KDF routing behavior;
+- the overall transport architecture.
+
+The practical goal is narrower:
+
+- reuse more captured profile data;
+- reduce fixed synthetic behavior in the server flight;
+- preserve a valid FakeTLS success path while changing the emitted shape on the wire.
+
+## Validation targets
+
+- Correct count of emulated `ChangeCipherSpec` records.
+- Correct replay of observed ticket-tail record sizes.
+- No regression in existing ALPN and payload-placement behavior.
+
+## How to validate the result
+
+Recommended validation consists of two layers:
+
+- focused unit and security tests for CCS-count replay and ticket-tail replay;
+- real packet-capture comparison for a selected origin and a successful FakeTLS session.
+
+When testing on the network, the expected result is:
+
+- a valid FakeTLS and MTProto success path is preserved;
+- the early encrypted server flight changes shape when richer profile data is available;
+- the change is visible on the wire without changing MTProto logic or transport architecture.
+
+This validation is intended to show better reuse of captured TLS profile data.
+It is not intended to prove byte-level equivalence with the real origin server.
+
+## How to test on a real deployment
+
+The strongest practical validation is a side-by-side trace comparison between:
+
+- a real TLS origin server used as `mask_host`;
+- a Telemt FakeTLS success-path connection for the same SNI;
+- optional captures from different Telemt builds or configurations.
+
+The purpose of the comparison is to inspect the shape of the server flight:
+
+- record order;
+- count of `ChangeCipherSpec` records;
+- count and grouping of early encrypted `ApplicationData` records;
+- lengths of tail or continuation `ApplicationData` records.
+
+## Recommended environment
+
+Use a Linux host or Docker container for the cleanest reproduction.
+
+Recommended setup:
+
+1. One Telemt instance.
+2. One real HTTPS origin as `mask_host`.
+3. One Telegram client configured with an `ee` proxy link for the Telemt instance.
+4. `tcpdump` or Wireshark available for capture analysis.
+
+## Step-by-step test procedure
+
+### 1. Prepare the origin
+
+1. Choose a real HTTPS origin.
+2. Set both `censorship.tls_domain` and `censorship.mask_host` to that hostname.
+3. Confirm that a direct TLS request works:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+### 2. Configure Telemt
+
+Use a configuration that enables:
+
+- `censorship.mask = true`
+- `censorship.tls_emulation = true`
+- `censorship.mask_host`
+- `censorship.mask_port`
+
+Recommended for cleaner testing:
+
+- keep `censorship.tls_new_session_tickets = 0`, so the result depends primarily on fetched profile data rather than operator-forced synthetic tail records;
+- keep `censorship.tls_fetch.strict_route = true`, if cleaner provenance for captured profile data is important.
+
+### 3. Refresh TLS profile data
+
+1. Start Telemt.
+2. Let it fetch TLS front profile data for the configured domain.
+3. If `tls_front_dir` is persisted, confirm that the TLS front cache is populated.
+
+Persisted cache artifacts are useful, but they are not required if packet captures already demonstrate the runtime result.
+
+### 4. Check TLS-front profile health metrics
+
+If the metrics endpoint is enabled, check the TLS-front profile health before packet-capture validation:
+
+```bash
+curl -s http://127.0.0.1:9999/metrics | grep -E 'telemt_tls_front_profile|telemt_tls_fetch_profile_cache|telemt_tls_front_full_cert'
+```
+
+The profile-health metrics expose the runtime state of configured TLS front domains:
+
+- `telemt_tls_front_profile_domains` shows configured, emitted, and suppressed domain series.
+- `telemt_tls_front_profile_info` shows profile source and feature flags per domain.
+- `telemt_tls_front_profile_age_seconds` shows cached profile age.
+- `telemt_tls_front_profile_app_data_records` shows cached AppData record count.
+- `telemt_tls_front_profile_ticket_records` shows cached ticket-like tail record count.
+- `telemt_tls_front_profile_change_cipher_spec_records` shows cached ChangeCipherSpec count.
+- `telemt_tls_front_profile_app_data_bytes` shows total cached AppData bytes.
+
+Interpretation:
+
+- `source="merged"` or `source="raw"` means real TLS profile data is being used.
+- `source="default"` or `is_default="true"` means the domain currently uses the synthetic default fallback.
+- `has_cert_payload="true"` means certificate payload data is available for TLS emulation.
+- Non-zero AppData/ticket/CCS counters show captured server-flight shape.
+
+Example healthy output:
+
+```text
+telemt_tls_front_profile_domains{status="configured"} 1
+telemt_tls_front_profile_domains{status="emitted"} 1
+telemt_tls_front_profile_domains{status="suppressed"} 0
+telemt_tls_front_profile_info{domain="itunes.apple.com",source="merged",is_default="false",has_cert_info="true",has_cert_payload="true"} 1
+telemt_tls_front_profile_age_seconds{domain="itunes.apple.com"} 20
+telemt_tls_front_profile_app_data_records{domain="itunes.apple.com"} 3
+telemt_tls_front_profile_ticket_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_change_cipher_spec_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_app_data_bytes{domain="itunes.apple.com"} 5240
+```
+
+These metrics do not prove byte-level origin equivalence. They are an operational health signal that the configured domain is backed by real cached profile data instead of default fallback data.
+
+### 5. Capture a direct-origin trace
+
+From a separate client host, connect directly to the origin:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+Capture with:
+
+```bash
+sudo tcpdump -i any -w origin-direct.pcap host ORIGIN_IP and port 443
+```
+
+### 6. Capture a Telemt FakeTLS success-path trace
+
+Now connect to Telemt with a real Telegram client through an `ee` proxy link that targets the Telemt instance.
+
+`openssl s_client` is useful for direct-origin capture and fallback sanity checks, but it does not exercise the successful FakeTLS and MTProto path.
+
+Capture with:
+
+```bash
+sudo tcpdump -i any -w telemt-emulated.pcap host TELEMT_IP and port 443
+```
+
+### 7. Decode TLS record structure
+
+Use `tshark` to print record-level structure:
+
+```bash
+tshark -r origin-direct.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+```bash
+tshark -r telemt-emulated.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+Focus on the server flight after ClientHello:
+
+- `22` = Handshake
+- `20` = ChangeCipherSpec
+- `23` = ApplicationData
+
+### 8. Build a comparison table
+
+A compact table like the following is usually enough:
+
+| Path | CCS count | AppData count in first encrypted flight | Tail AppData lengths |
+| --- | --- | --- | --- |
+| Origin | `N` | `M` | `[a, b, ...]` |
+| Telemt build A | `...` | `...` | `...` |
+| Telemt build B | `...` | `...` | `...` |
+
+The comparison should make it easy to see that:
+
+- the FakeTLS success path remains valid;
+- the early encrypted server flight changes when richer profile data is reused;
+- the result is backed by packet evidence.
+
+## Example capture set
+
+One practical example of this workflow uses:
+
+- `origin-direct-nginx.pcap`
+- `telemt-ee-before-nginx.pcap`
+- `telemt-ee-after-nginx.pcap`
+
+Practical notes:
+
+- `origin` was captured as a direct TLS 1.2 connection to `nginx.org`;
+- `before` and `after` were captured on the Telemt FakeTLS success path with a real Telegram client;
+- the first server-side FakeTLS response remains valid in both cases;
+- the early encrypted server-flight segmentation differs between `before` and `after`, which is consistent with better reuse of captured profile data;
+- this kind of result shows a wire-visible effect without breaking the success path, but it does not claim full indistinguishability from the origin.
+
+## Stronger validation
+
+For broader confidence, repeat the same comparison on:
+
+1. one CDN-backed origin;
+2. one regular nginx origin;
+3. one origin with a multi-record encrypted flight and visible ticket-like tails.
+
+If the same directional improvement appears across all three, confidence in the result will be much higher than for a single-origin example.
@@ -0,0 +1,266 @@
+# Fidelity TLS Front Profile
+
+## Обзор
+
+Этот документ описывает, как Telemt переиспользует захваченное TLS-поведение в FakeTLS server flight и как проверять результат на реальной инсталляции.
+
+Когда включена TLS front emulation, Telemt может собирать полезное серверное TLS-поведение выбранного origin и использовать его в emulated success path. Цель здесь не в побайтном копировании origin, а в уменьшении устойчивых synthetic признаков и в том, чтобы emitted server flight был структурно ближе к захваченному profile.
+
+## Зачем нужно это изменение
+
+Проект уже умеет собирать полезное серверное TLS-поведение в пути TLS front fetch:
+
+- `change_cipher_spec_count`
+- `app_data_record_sizes`
+- `ticket_record_sizes`
+
+До этого изменения эмулятор использовал только часть этой информации. Из-за этого оставался разрыв между захваченным поведением origin и тем FakeTLS server flight, который реально уходил на провод.
+
+## Что реализовано
+
+- Эмулятор теперь воспроизводит наблюдаемое значение `ChangeCipherSpec` из полученного `behavior_profile`.
+- Эмулятор теперь воспроизводит наблюдаемые размеры ticket-like tail ApplicationData records, когда доступны raw или merged TLS profile data.
+- Эмулятор теперь сохраняет больше структуры профилированного encrypted flight, а не схлопывает его в более маленькую synthetic форму.
+- Для профилей без raw TLS behavior по-прежнему сохраняется прежний synthetic fallback.
+- Операторский `tls_new_session_tickets` по-прежнему работает как дополнительный fallback, если профиль не даёт достаточного количества tail records.
+
+## Практическая польза
+
+- Снижается различимость между профилированным origin TLS-поведением и эмулируемым TLS-поведением.
+- Уменьшается шанс устойчивых server-flight fingerprint, вызванных фиксированным CCS count или полностью synthetic tail record sizes.
+- Уже собранные TLS profile data используются лучше, без изменения MTProto logic, KDF routing или transport architecture.
+
+## Ограничения
+
+Этот механизм не ставит целью сделать Telemt побайтно идентичным origin server.
+
+Он также не меняет:
+
+- MTProto business logic;
+- поведение KDF routing;
+- общую transport architecture.
+
+Практическая цель уже:
+
+- использовать больше уже собранных profile data;
+- уменьшить fixed synthetic behavior в server flight;
+- сохранить валидный FakeTLS success path, одновременно меняя форму emitted traffic на проводе.
+
+## Цели валидации
+
+- Корректное количество эмулируемых `ChangeCipherSpec` records.
+- Корректное воспроизведение наблюдаемых ticket-tail record sizes.
+- Отсутствие регрессии в существующем ALPN и payload-placement behavior.
+
+## Как проверять результат
+
+Рекомендуемая валидация состоит из двух слоёв:
+
+- focused unit и security tests для CCS-count replay и ticket-tail replay;
+- сравнение реальных packet capture для выбранного origin и успешной FakeTLS session.
+
+При проверке на сети ожидаемый результат такой:
+
+- валидный FakeTLS и MTProto success path сохраняется;
+- форма раннего encrypted server flight меняется, когда доступно более богатое profile data;
+- изменение видно на проводе без изменения MTProto logic и transport architecture.
+
+Такая проверка нужна для подтверждения того, что уже собранные TLS profile data используются лучше.
+Она не предназначена для доказательства побайтной эквивалентности с реальным origin server.
+
+## Как проверить на реальной инсталляции
+
+Самая сильная практическая проверка — side-by-side trace comparison между:
+
+- реальным TLS origin server, используемым как `mask_host`;
+- Telemt FakeTLS success-path connection для того же SNI;
+- при необходимости capture от разных Telemt builds или configurations.
+
+Смысл сравнения состоит в том, чтобы посмотреть на форму server flight:
+
+- порядок records;
+- количество `ChangeCipherSpec` records;
+- количество и группировку ранних encrypted `ApplicationData` records;
+- размеры tail или continuation `ApplicationData` records.
+
+## Рекомендуемое окружение
+
+Для самой чистой проверки лучше использовать Linux host или Docker container.
+
+Рекомендуемый setup:
+
+1. Один экземпляр Telemt.
+2. Один реальный HTTPS origin как `mask_host`.
+3. Один Telegram client, настроенный на `ee` proxy link для Telemt instance.
+4. `tcpdump` или Wireshark для анализа capture.
+
+## Пошаговая процедура проверки
+
+### 1. Подготовить origin
+
+1. Выберите реальный HTTPS origin.
+2. Установите и `censorship.tls_domain`, и `censorship.mask_host` в hostname этого origin.
+3. Убедитесь, что прямой TLS request работает:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+### 2. Настроить Telemt
+
+Используйте config, где включены:
+
+- `censorship.mask = true`
+- `censorship.tls_emulation = true`
+- `censorship.mask_host`
+- `censorship.mask_port`
+
+Для более чистой проверки рекомендуется:
+
+- держать `censorship.tls_new_session_tickets = 0`, чтобы результат в первую очередь зависел от fetched profile data, а не от операторских synthetic tail records;
+- держать `censorship.tls_fetch.strict_route = true`, если важна более чистая provenance для captured profile data.
+
+### 3. Обновить TLS profile data
+
+1. Запустите Telemt.
+2. Дайте ему получить TLS front profile data для выбранного домена.
+3. Если `tls_front_dir` хранится persistently, убедитесь, что TLS front cache заполнен.
+
+Сохранённые артефакты кэша полезны, но не обязательны, если packet capture уже показывает результат в runtime.
+
+### 4. Проверить метрики состояния TLS-front profile
+
+Если endpoint метрик включён, перед проверкой через packet capture можно быстро проверить состояние TLS-front profile:
+
+```bash
+curl -s http://127.0.0.1:9999/metrics | grep -E 'telemt_tls_front_profile|telemt_tls_fetch_profile_cache|telemt_tls_front_full_cert'
+```
+
+Метрики состояния профиля показывают runtime-состояние настроенных TLS-front доменов:
+
+- `telemt_tls_front_profile_domains` показывает количество настроенных, экспортируемых и скрытых из-за лимита доменов.
+- `telemt_tls_front_profile_info` показывает источник профиля и флаги доступных данных по каждому домену.
+- `telemt_tls_front_profile_age_seconds` показывает возраст закешированного профиля.
+- `telemt_tls_front_profile_app_data_records` показывает количество закешированных AppData records.
+- `telemt_tls_front_profile_ticket_records` показывает количество закешированных ticket-like tail records.
+- `telemt_tls_front_profile_change_cipher_spec_records` показывает закешированное количество ChangeCipherSpec records.
+- `telemt_tls_front_profile_app_data_bytes` показывает общий размер закешированных AppData bytes.
+
+Интерпретация:
+
+- `source="merged"` или `source="raw"` означает, что используются реальные данные TLS-профиля.
+- `source="default"` или `is_default="true"` означает, что домен сейчас работает на synthetic default fallback.
+- `has_cert_payload="true"` означает, что certificate payload доступен для TLS emulation.
+- Ненулевые AppData/ticket/CCS counters показывают захваченную форму server flight.
+
+Пример здорового состояния:
+
+```text
+telemt_tls_front_profile_domains{status="configured"} 1
+telemt_tls_front_profile_domains{status="emitted"} 1
+telemt_tls_front_profile_domains{status="suppressed"} 0
+telemt_tls_front_profile_info{domain="itunes.apple.com",source="merged",is_default="false",has_cert_info="true",has_cert_payload="true"} 1
+telemt_tls_front_profile_age_seconds{domain="itunes.apple.com"} 20
+telemt_tls_front_profile_app_data_records{domain="itunes.apple.com"} 3
+telemt_tls_front_profile_ticket_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_change_cipher_spec_records{domain="itunes.apple.com"} 1
+telemt_tls_front_profile_app_data_bytes{domain="itunes.apple.com"} 5240
+```
+
+Эти метрики не доказывают побайтную эквивалентность с origin. Это эксплуатационный сигнал состояния: настроенный домен действительно основан на реальных закешированных данных профиля, а не на default fallback.
+
+### 5. Снять direct-origin trace
+
+С отдельной клиентской машины подключитесь напрямую к origin:
+
+```bash
+openssl s_client -connect ORIGIN_IP:443 -servername YOUR_DOMAIN </dev/null
+```
+
+Capture:
+
+```bash
+sudo tcpdump -i any -w origin-direct.pcap host ORIGIN_IP and port 443
+```
+
+### 6. Снять Telemt FakeTLS success-path trace
+
+Теперь подключитесь к Telemt через реальный Telegram client с `ee` proxy link, который указывает на Telemt instance.
+
+`openssl s_client` полезен для direct-origin capture и для fallback sanity checks, но он не проходит успешный FakeTLS и MTProto path.
+
+Capture:
+
+```bash
+sudo tcpdump -i any -w telemt-emulated.pcap host TELEMT_IP and port 443
+```
+
+### 7. Декодировать структуру TLS records
+
+Используйте `tshark`, чтобы вывести record-level structure:
+
+```bash
+tshark -r origin-direct.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+```bash
+tshark -r telemt-emulated.pcap -Y "tls.record" -T fields \
+  -e frame.number \
+  -e ip.src \
+  -e ip.dst \
+  -e tls.record.content_type \
+  -e tls.record.length
+```
+
+Смотрите на server flight после ClientHello:
+
+- `22` = Handshake
+- `20` = ChangeCipherSpec
+- `23` = ApplicationData
+
+### 8. Собрать сравнительную таблицу
+
+Обычно достаточно короткой таблицы такого вида:
+
+| Path | CCS count | AppData count in first encrypted flight | Tail AppData lengths |
+| --- | --- | --- | --- |
+| Origin | `N` | `M` | `[a, b, ...]` |
+| Telemt build A | `...` | `...` | `...` |
+| Telemt build B | `...` | `...` | `...` |
+
+По такой таблице должно быть легко увидеть, что:
+
+- FakeTLS success path остаётся валидным;
+- ранний encrypted server flight меняется, когда переиспользуется более богатое profile data;
+- результат подтверждён packet evidence.
+
+## Пример набора capture
+
+Один практический пример такой проверки использует:
+
+- `origin-direct-nginx.pcap`
+- `telemt-ee-before-nginx.pcap`
+- `telemt-ee-after-nginx.pcap`
+
+Практические замечания:
+
+- `origin` снимался как прямое TLS 1.2 connection к `nginx.org`;
+- `before` и `after` снимались на Telemt FakeTLS success path с реальным Telegram client;
+- первый server-side FakeTLS response остаётся валидным в обоих случаях;
+- сегментация раннего encrypted server flight отличается между `before` и `after`, что согласуется с лучшим использованием captured profile data;
+- такой результат показывает заметный эффект на проводе без поломки success path, но не заявляет полной неотличимости от origin.
+
+## Более сильная валидация
+
+Для более широкой проверки повторите ту же процедуру ещё на:
+
+1. одном CDN-backed origin;
+2. одном regular nginx origin;
+3. одном origin с multi-record encrypted flight и заметными ticket-like tails.
+
+Если одно и то же направление улучшения повторится на всех трёх, уверенность в результате будет значительно выше, чем для одного origin example.
@@ -36,8 +36,11 @@ hello2 = "ad_tag2"
 On April 1, 2026, we became aware of a method for detecting MTProxy Fake-TLS, 
 based on the ECH extension and the ordering of cipher suites, 
 as well as an overall unique JA3/JA4 fingerprint 
-that does not occur in modern browsers: 
-we have already submitted initial changes to the Telegram Desktop developers and are working on updates for other clients.
+that does not occur in modern browsers.
+
+> [!IMPORTANT]
+> TLS fingerprint has been fixed in latest version of clients for Desktop / Android / iOS.  
+> Please update your client for MTProxy Fake-TLS to work correctly.

 - We consider this a breakthrough aspect, which has no stable analogues today
 - Based on this: if `telemt` configured correctly, **TLS mode is completely identical to real-life handshake + communication** with a specified host
@@ -154,6 +157,24 @@ Keep-Alive: timeout=60
 ### Why do you need a middle proxy (ME)
 https://github.com/telemt/telemt/discussions/167

+## How clients interact with Telegram DCs
+When you register a Telegram account, it gets permanently bound to one of Telegram's data centers (DCs).  
+It is deciced beforehand by Telegram based on the phone number's region.  
+This DC becomes your **home DC**: all content you upload (photos, videos, files, messages) is stored there.  
+Your client authenticates on it with every connection.  
+
+For example, if your account is registered on **DC2**, your client will always connect to DC2 first.  
+When you open a chat with another user whose home DC is **DC5**, your client opens an additional connection to DC5 to download their media.  
+Those cross-DC requests are normal and happen constantly.  
+
+> [!WARNING]
+> Because every session is anchored to your home DC, an outage there causes other DCs to be unavaliable.  
+> If your home DC is DC2 and DC2 goes down, you **cannot** reach DC5 even though DC5 itself is perfectly healthy.  
+> The client has no valid session to route the request through.  
+
+This is also why an MTProxy only needs to reach Telegram's DC infrastructure as a whole.  
+The proxy itself doesn't care which DC your account lives on. The client negotiates the correct DC through the proxy after connecting.
+
 ### How many people can use one link
 By default, an unlimited number of people can use a single link.  
 However, you can limit the number of unique IP addresses for each user:
@@ -161,7 +182,8 @@ However, you can limit the number of unique IP addresses for each user:
 [access.user_max_unique_ips]
 hello = 1
 ```
-This parameter sets the maximum number of unique IP addresses from which a single link can be used simultaneously. If the first user disconnects, a second one can connect. At the same time, multiple users can connect from a single IP address simultaneously (for example, devices on the same Wi-Fi network).
+This parameter sets the maximum number of unique IP addresses from which a single link can be used simultaneously. If the first user disconnects, a second one can connect.
+At the same time, multiple users can connect from a single IP address simultaneously (for example, devices on the same Wi-Fi network).

 ### How to create multiple different links
 1. Generate the required number of secrets using the command: `openssl rand -hex 16`.
@@ -188,6 +210,13 @@ If you need to allow connections with any domains (ignoring SNI mismatches), add
 unknown_sni_action = "mask"
 ```

+Alternatively, if you want telemt to behave like a vanilla nginx with `ssl_reject_handshake on;` on unknown SNI (emit a TLS `unrecognized_name` alert and close the connection), use:
+```toml
+[censorship]
+unknown_sni_action = "reject_handshake"
+```
+This does not recover stale clients, but it makes port 443 wire-indistinguishable from a stock web server that simply does not host the requested vhost.
+
 ### How to view metrics

 1. Open the configuration file: `nano /etc/telemt/telemt.toml`.
@@ -33,9 +33,12 @@ hello = "ad_tag"
 hello2 = "ad_tag2"
 ```
 ## Распознаваемость для DPI и сканеров
+1 апреля 2026 года нам стало известно о методе обнаружения MTProxy Fake-TLS, основанном на расширении ECH и порядке набора шифров,
+а также об общем уникальном отпечатке JA3/JA4, который не встречается в современных браузерах.

-1 апреля 2026 года нам стало известно о методе обнаружения MTProxy Fake-TLS, основанном на расширении ECH и порядке набора шифров, 
-а также об общем уникальном отпечатке JA3/JA4, который не встречается в современных браузерах: мы уже отправили первоначальные изменения разработчикам Telegram Desktop и работаем над обновлениями для других клиентов.
+> [!IMPORTANT]
+> Проблема с TLS отпечатком исправлена в последних версиях клиентов Telegram для Desktop / Android / iOS.  
+> Обновите свой клиент для корректной работы с MTProxy Fake-TLS!

 - Мы считаем это прорывом, которому на сегодняшний день нет стабильных аналогов;
 - Исходя из этого: если `telemt` настроен правильно, **режим TLS полностью идентичен реальному «рукопожатию» + обмену данными** с указанным хостом;
@@ -152,6 +155,23 @@ Keep-Alive: timeout=60
 ## Зачем нужен middle proxy (ME)
 https://github.com/telemt/telemt/discussions/167

+## Как клиенты взаимодействуют с дата-центрами Telegram
+При регистрации аккаунта Telegram он навсегда привязывается к одному из дата-центров (DC).  
+Telegram заранее определяет к какому DC привязать аккаунт исходя из региона, к которому относиться номер телефона.  
+Этот DC становится вашим **домашним**: именно там хранится весь контент, который вы загружаете (фото, видео, файлы, сообщения).  
+И именно на нем клиент авторизуется при каждом подключении.  
+
+Например, если ваш аккаунт зарегистрирован на **DC2**, клиент всегда будет подключаться в первую очередь к DC2.  
+Когда вы открываете переписку с пользователем, чей домашний DC — **DC5**, клиент устанавливает доп. соединение с DC5, чтобы загрузить его контент.  
+Такие кросс-запросы к DC — это нормальная часть работы Telegram.  
+
+> [!WARNING]
+> Поскольку аккаунт всегда привязан к домашнему DC, при его падении контент с других DC будет недоступен.  
+> Если ваш домашний DC — DC2, и DC2 лежит, вы **не сможете** достучаться  и до DC5, даже если сам DC5 полностью исправен.  
+> У клиента просто нет валидной сессии, через которую можно было бы направить запрос.  
+
+По той же причине MTProxy достаточно иметь доступ к инфраструктуре Telegram в целом.  
+Cамому MTProxy всё равно, на каком DC живёт ваш аккаунт. Клиент cам договаривается о нужном DC через прокси уже после подключения.  

 ## Что такое dd и ee в контексте MTProxy?

@@ -207,6 +227,13 @@ curl -s http://127.0.0.1:9091/v1/users | jq
 unknown_sni_action = "mask"
 ```

+Альтернатива: если вы хотите, чтобы telemt на неизвестный SNI вёл себя как обычный nginx с `ssl_reject_handshake on;` (отдавал TLS-alert `unrecognized_name` и закрывал соединение), используйте:
+```toml
+[censorship]
+unknown_sni_action = "reject_handshake"
+```
+Это не пропускает старых клиентов, но делает поведение на 443-м порту неотличимым от стокового веб-сервера, у которого просто нет такого виртуального хоста.
+
 ## Как посмотреть метрики

 1. Откройте файл конфигурации: `nano /etc/telemt/telemt.toml`.
@@ -27,7 +27,8 @@ cargo build --release
 ./target/release/telemt --version
 ```

-For low-RAM systems, this repository already uses `lto = "thin"` in release profile.
+For low-RAM systems, note that this repository currently uses `lto = "fat"` in release profile.  
+On constrained builders, a local override to `lto = "thin"` may be more practical.

 ## 3. Install binary and config

@@ -1,9 +1,36 @@
+# Installation Options 
+There are three options for installing Telemt:
+ - [Automated installation using a script](#very-quick-start).
+ - [Manual installation of Telemt as a service](#telemt-via-systemd).
+ - [Installation using Docker Compose](#telemt-via-docker-compose).
+
 # Very quick start

 ### One-command installation / update on re-run
 ```bash
 curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
 ```
+
+After starting, the script will prompt for:
+ - Your language (1 - English, 2 - Russian);
+ - Your TLS domain (press Enter for petrovich.ru).
+
+The script checks if the port (default **443**) is free. If the port is already in use, installation will fail. You need to free up the port or use the **-p** flag with a different port to retry the installation.
+
+To modify the script’s startup parameters, you can use the following flags:
+ - **-d, --domain** - TLS domain;
+ - **-p, --port** - server port (1–65535);
+ - **-s, --secret** - 32 hex secret;
+ - **-a, --ad-tag** - ad_tag;
+ - **-l, --lan**g - language (1/en or 2/ru);
+
+Providing all options skips interactive prompts.
+
+After completion, the script will provide a link for client connections:
+```bash
+tg://proxy?server=IP&port=PORT&secret=SECRET
+```
+
 ### Installing a specific version
 ```bash
 curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- 3.3.39
@@ -110,15 +137,15 @@ show = "*"
 # === Server Binding ===
 [server]
 port = 443
-# proxy_protocol = false           # Enable if behind HAProxy/nginx with PROXY protocol
+# proxy_protocol = false            # Enable if behind HAProxy/nginx with PROXY protocol
 # metrics_port = 9090
-# metrics_listen = "0.0.0.0:9090"  # Listen address for metrics (overrides metrics_port)
-# metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
+# metrics_listen = "127.0.0.1:9090" # Listen address for metrics (overrides metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]

 [server.api]
 enabled = true
-listen = "0.0.0.0:9091"
-whitelist = ["127.0.0.0/8"]
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
 minimal_runtime_enabled = false
 minimal_runtime_cache_ttl_ms = 1000

@@ -128,9 +155,9 @@ ip = "0.0.0.0"

 # === Anti-Censorship & Masking ===
 [censorship]
-tls_domain = "petrovich.ru"
+tls_domain = "petrovich.ru"  # Fake-TLS / SNI masking domain used in generated ee-links
 mask = true
-tls_emulation = true        # Fetch real cert lengths and emulate TLS records
+tls_emulation = true         # Fetch real cert lengths and emulate TLS records
 tls_front_dir = "tlsfront"   # Cache directory for TLS emulation

 [access.users]
@@ -141,9 +168,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.  
-> 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!
+> 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!

 ---

@@ -227,6 +254,19 @@ docker compose down
 > - `docker-compose.yml` maps `./config.toml` to `/app/config.toml` (read-only)
 > - By default it publishes `443:443` and runs with dropped capabilities (only `NET_BIND_SERVICE` is added)
 > - If you really need host networking (usually only for some IPv6 setups) uncomment `network_mode: host`
+> - If you enable mutating Control API endpoints, mount a writable config directory instead of a single `config.toml` file. Telemt persists config changes with atomic `tmp + rename` writes, and a single bind-mounted file can fail with `Device or resource busy`.
+
+Example writable config mount for Control API mutations:
+```yaml
+services:
+  telemt:
+    working_dir: /run/telemt
+    volumes:
+      - ./config:/etc/telemt:rw
+    tmpfs:
+      - /run/telemt:rw,mode=1777,size=4m
+    command: /usr/local/bin/telemt /etc/telemt/config.toml
+```

 **Run without Compose**
 ```bash
@@ -1,9 +1,35 @@
+# Варианты установки
+Имеется три варианта установки Telemt:
+ - [Автоматизированная установка с помощью скрипта](#очень-быстрый-старт).
+ - [Ручная установка Telemt в качестве службы](#telemt-через-systemd-вручную).
+ - [Установка через Docker Compose](#telemt-через-docker-compose).
+
 # Очень быстрый старт

 ### Установка одной командой / обновление при повторном запуске
 ```bash
 curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh
 ```
+После запуска скрипт запросит:
+ - ваш язык (1 - English, 2 - Русский);
+ - ваш TLS-домен (нажмите Enter для petrovich.ru).
+
+Во время установки скрипт проверяет, свободен ли порт (по умолчанию **443**). Если порт занят другим процессом - установка завершится с ошибкой. Для повторной установки необходимо освободить порт или указать другой через флаг **-p**.
+
+Для изменения параметров запуска скрипта можно использовать следующие флаги:
+ - **-d, --domain** - TLS-домен;
+ - **-p, --port** - порт (1–65535);
+ - **-s, --secret** - секрет (32 hex символа);
+ - **-a, --ad-tag** - ad_tag;
+ - **-l, --lang** - язык (1/en или 2/ru).
+
+Если заданы флаги для языка и домена, интерактивных вопросов не будет.
+
+После завершения установки скрипт выдаст ссылку для подключения клиентов:
+```bash
+tg://proxy?server=IP&port=PORT&secret=SECRET
+```
+
 ### Установка нужной версии
 ```bash
 curl -fsSL https://raw.githubusercontent.com/telemt/telemt/main/install.sh | sh -s -- 3.3.39
@@ -103,22 +129,22 @@ tls = true
 [general.links]
 show = "*"
 # show = ["alice", "bob"] # Показывать ссылки только для alice и bob
-# show = "*"              # Показывать ссылки для всех пользователей
-# public_host = "proxy.example.com"  # Хост (IP-адрес или домен) для ссылок tg://
-# public_port = 443                  # Порт для ссылок tg:// (по умолчанию: server.port)
+# show = "*"              # Показывать ссылки для всех пользователей
+# public_host = "proxy.example.com"  # Хост (IP-адрес или домен) для ссылок tg://
+# public_port = 443                  # Порт для ссылок tg:// (по умолчанию: server.port)

 # === Привязка сервера ===
 [server]
 port = 443
-# proxy_protocol = false           # Включите, если сервер находится за HAProxy/nginx с протоколом PROXY
+# proxy_protocol = false           # Включите, если сервер находится за HAProxy/nginx с протоколом PROXY
 # metrics_port = 9090
-# metrics_listen = "0.0.0.0:9090"  # Адрес прослушивания для метрик (переопределяет metrics_port)
-# metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
+# metrics_listen = "127.0.0.1:9090"  # Адрес прослушивания для метрик (переопределяет metrics_port)
+# metrics_whitelist = ["127.0.0.1/32", "::1/128"]

 [server.api]
 enabled = true
-listen = "0.0.0.0:9091"
-whitelist = ["127.0.0.0/8"]
+listen = "127.0.0.1:9091"
+whitelist = ["127.0.0.1/32", "::1/128"]
 minimal_runtime_enabled = false
 minimal_runtime_cache_ttl_ms = 1000

@@ -128,9 +154,9 @@ ip = "0.0.0.0"

 # === Обход блокировок и маскировка ===
 [censorship]
-tls_domain = "petrovich.ru"
+tls_domain = "petrovich.ru"  # Домен Fake-TLS / SNI, который будет использоваться в сгенерированных ee-ссылках
 mask = true
-tls_emulation = true        # Получить реальную длину сертификата и эмулировать запись TLS
+tls_emulation = true         # Получить реальную длину сертификата и эмулировать запись TLS
 tls_front_dir = "tlsfront"   # Директория кэша для эмуляции TLS

 [access.users]
@@ -138,12 +164,12 @@ tls_front_dir = "tlsfront"   # Директория кэша для эмуляц
 hello = "00000000000000000000000000000000"
 ```

-Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
+Затем нажмите Ctrl+O -> Ctrl+X, чтобы сохранить

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

 ---

@@ -0,0 +1,273 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Concept
+- **Server A** (_e.g., RU_):\
+  Entry point, accepts Telegram proxy user traffic via **Xray** (port `443\tcp`)\
+  and sends it through the tunnel to Server **B**.\
+  Public port for Telegram clients — `443\tcp`
+- **Server B** (_e.g., NL_):\
+  Exit point, runs the **Xray server** (to terminate the tunnel entry point) and **telemt**.\
+  The server must have unrestricted access to Telegram Data Centers.\
+  Public port for VLESS/REALITY (incoming) — `443\tcp`\
+  Internal telemt port (where decrypted Xray traffic ends up) — `8443\tcp`
+
+The tunnel works over the `VLESS-XTLS-Reality` (or `VLESS/xhttp/reality`) protocol. The original client IP address is preserved thanks to the PROXYv2 protocol, which Xray on Server A dynamically injects via a local loopback before wrapping the traffic into Reality, transparently delivering the real IPs to telemt on Server B.
+
+---
+
+## Step 1. Setup Xray Tunnel (A <-> B)
+
+You must install **Xray-core** (version 1.8.4 or newer recommended) on both servers.
+Official installation script (run on both servers):
+```bash
+bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
+```
+
+### Key and Parameter Generation (Run Once)
+For configuration, you need a unique UUID and Xray Reality keys. Run on any server with Xray installed:
+1. **Client UUID:**
+```bash
+xray uuid
+# Save the output (e.g.: 12345678-abcd-1234-abcd-1234567890ab) — this is <XRAY_UUID>
+```
+2. **X25519 Keypair (Private & Public) for Reality:**
+```bash
+xray x25519
+# Save the Private key (<SERVER_B_PRIVATE_KEY>) and Public key (<SERVER_B_PUBLIC_KEY>)
+```
+3. **Short ID (Reality identifier):**
+```bash
+openssl rand -hex 8
+# Save the output (e.g.: abc123def456) — this is <SHORT_ID>
+```
+4. **Random Path (for xhttp):**
+```bash
+openssl rand -hex 16
+# Save the output (e.g., 0123456789abcdef0123456789abcdef) to replace <YOUR_RANDOM_PATH> in configs
+```
+
+---
+
+### Configuration for Server B (_EU_):
+
+Create or edit the file `/usr/local/etc/xray/config.json`.
+This Xray instance will listen on the public `443` port and proxy valid Reality traffic, while routing "disguised" traffic (e.g., direct web browser scans) to `yahoo.com`.
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+File content:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "vless-in",
+      "port": 443,
+      "protocol": "vless",
+      "settings": {
+        "clients": [
+          {
+            "id": "<XRAY_UUID>"
+          }
+        ],
+        "decryption": "none"
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "dest": "yahoo.com:443",
+          "serverNames": [
+            "yahoo.com"
+          ],
+          "privateKey": "<SERVER_B_PRIVATE_KEY>",
+          "shortIds": [
+            "<SHORT_ID>"
+          ]
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>",
+          "mode": "auto"
+        }
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "tunnel-to-telemt",
+      "protocol": "freedom",
+      "settings": {
+        "destination": "127.0.0.1:8443"
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": [
+          "vless-in"
+        ],
+        "outboundTag": "tunnel-to-telemt"
+      }
+    ]
+  }
+}
+```
+
+Open the firewall port (if enabled):
+```bash
+sudo ufw allow 443/tcp
+```
+Restart and setup Xray to run at boot:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+### Configuration for Server A (_RU_):
+
+Similarly, edit `/usr/local/etc/xray/config.json`.
+Here Xray acts as the public entry point: it listens on `443\tcp`, uses a local loopback (via internal port `10444`) to prepend the `PROXYv2` header, and encapsulates the payload via Reality to Server B, instructing Server B to deliver it to its *local* `127.0.0.1:8443` port (where telemt will listen).
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+File content:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "public-in",
+      "port": 443,
+      "listen": "0.0.0.0",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 10444,
+        "network": "tcp"
+      }
+    },
+    {
+      "tag": "tunnel-in",
+      "port": 10444,
+      "listen": "127.0.0.1",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 8443,
+        "network": "tcp"
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "local-injector",
+      "protocol": "freedom",
+      "settings": {
+        "proxyProtocol": 2
+      }
+    },
+    {
+      "tag": "vless-out",
+      "protocol": "vless",
+      "settings": {
+        "vnext": [
+          {
+            "address": "<PUBLIC_IP_SERVER_B>",
+            "port": 443,
+            "users": [
+              {
+                "id": "<XRAY_UUID>",
+                "encryption": "none"
+              }
+            ]
+          }
+        ]
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "serverName": "yahoo.com",
+          "publicKey": "<SERVER_B_PUBLIC_KEY>",
+          "shortId": "<SHORT_ID>",
+          "spiderX": "/",
+          "fingerprint": "chrome"
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>"
+        }
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": ["public-in"],
+        "outboundTag": "local-injector"
+      },
+      {
+        "type": "field",
+        "inboundTag": ["tunnel-in"],
+        "outboundTag": "vless-out"
+      }
+    ]
+  }
+}
+```
+*Replace `<PUBLIC_IP_SERVER_B>` with the public IP address of Server B.*
+
+Open the firewall port for clients (if enabled):
+```bash
+sudo ufw allow 443/tcp
+```
+
+Restart and setup Xray to run at boot:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+## Step 2. Install telemt on Server B (_EU_)
+
+telemt installation is heavily covered in the [Quick Start Guide](../Quick_start/QUICK_START_GUIDE.en.md).
+By contrast to standard setups, telemt must listen strictly _locally_ (since Xray occupies the public `443` interface) and must expect `PROXYv2` packets.
+
+Edit the configuration file (`config.toml`) on Server B accordingly:
+
+```toml
+[server]
+port = 8443
+listen_addr_ipv4 = "127.0.0.1"
+proxy_protocol = true
+
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+- Address `127.0.0.1` and `port = 8443` instructs the core proxy router to process connections unpacked locally via Xray-server.
+- `proxy_protocol = true` commands telemt to parse the injected PROXY header (from Server A's Xray local loopback) and log genuine end-user IPs.
+- Under `public_host`, place Server A's public IP address or FQDN to ensure working links are generated for Telegram users.
+
+Restart `telemt`. Your server is now robust against DPI scanners, passing traffic optimally.
+
@@ -0,0 +1,272 @@
+<img src="https://gist.githubusercontent.com/avbor/1f8a128e628f47249aae6e058a57610b/raw/19013276c035e91058e0a9799ab145f8e70e3ff5/scheme.svg">
+
+## Концепция
+- **Сервер A** (_РФ_):\
+  Точка входа, принимает трафик пользователей Telegram-прокси напрямую через **Xray** (порт `443\tcp`)\
+  и отправляет его в туннель на Сервер **B**.\
+  Порт для клиентов Telegram — `443\tcp`
+- **Сервер B** (_условно Нидерланды_):\
+  Точка выхода, на нем работает **Xray-сервер** (принимает подключения точки входа) и **telemt**.\
+  На сервере должен быть неограниченный доступ до серверов Telegram.\
+  Порт для VLESS/REALITY (вход) — `443\tcp`\
+  Внутренний порт telemt (куда пробрасывается трафик) — `8443\tcp`
+
+Туннель работает по протоколу VLESS-XTLS-Reality (или VLESS/xhttp/reality). Оригинальный IP-адрес клиента сохраняется благодаря протоколу PROXYv2, который Xray на Сервере А добавляет через локальный loopback перед упаковкой в туннель, благодаря чему прозрачно доходит до telemt.
+
+---
+
+## Шаг 1. Настройка туннеля Xray (A <-> B)
+
+На обоих серверах необходимо установить **Xray-core** (рекомендуется версия 1.8.4 или новее).
+Официальный скрипт установки (выполнить на обоих серверах):
+```bash
+bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
+```
+
+### Генерация ключей и параметров (выполнить один раз)
+Для конфигурации потребуются уникальные ID и ключи Xray Reality. Выполните на любом сервере с установленным Xray:
+1. **UUID клиента:**
+```bash
+xray uuid
+# Сохраните вывод (например: 12345678-abcd-1234-abcd-1234567890ab) — это <XRAY_UUID>
+```
+2. **Пара ключей X25519 (Private & Public) для Reality:**
+```bash
+xray x25519
+# Сохраните Private key (<SERVER_B_PRIVATE_KEY>) и Public key (<SERVER_B_PUBLIC_KEY>)
+```
+3. **Short ID (идентификатор Reality):**
+```bash
+openssl rand -hex 8
+# Сохраните вывод (например: abc123def456) — это <SHORT_ID>
+```
+4. **Random Path (путь для xhttp):**
+```bash
+openssl rand -hex 16
+# Сохраните вывод (например, 0123456789abcdef0123456789abcdef), чтобы заменить <YOUR_RANDOM_PATH> в конфигах
+```
+
+---
+
+### Конфигурация Сервера B (_Нидерланды_):
+
+Создаем или редактируем файл `/usr/local/etc/xray/config.json`.
+Этот Xray-сервер будет слушать порт `443` и прозрачно пропускать валидный Reality трафик дальше, а "замаскированный" трафик (например, если кто-то стучится в лоб веб-браузером) пойдет на `yahoo.com`.
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+Содержимое файла:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "vless-in",
+      "port": 443,
+      "protocol": "vless",
+      "settings": {
+        "clients": [
+          {
+            "id": "<XRAY_UUID>"
+          }
+        ],
+        "decryption": "none"
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "dest": "yahoo.com:443",
+          "serverNames": [
+            "yahoo.com"
+          ],
+          "privateKey": "<SERVER_B_PRIVATE_KEY>",
+          "shortIds": [
+            "<SHORT_ID>"
+          ]
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>",
+          "mode": "auto"
+        }
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "tunnel-to-telemt",
+      "protocol": "freedom",
+      "settings": {
+        "destination": "127.0.0.1:8443"
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": [
+          "vless-in"
+        ],
+        "outboundTag": "tunnel-to-telemt"
+      }
+    ]
+  }
+}
+```
+
+Открываем порт на фаерволе (если включен):
+```bash
+sudo ufw allow 443/tcp
+```
+Перезапускаем Xray:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+### Конфигурация Сервера A (_РФ_):
+
+Аналогично, редактируем `/usr/local/etc/xray/config.json`.
+Здесь Xray выступает публичной точкой: он принимает трафик на внешний порт `443\tcp`, пропускает через локальный loopback (порт `10444`) для добавления PROXYv2-заголовка, и упаковывает в Reality до Сервера B, прося тот доставить данные на *свой локальный* порт `127.0.0.1:8443` (именно там будет слушать telemt).
+
+```bash
+nano /usr/local/etc/xray/config.json
+```
+
+Содержимое файла:
+```json
+{
+  "log": {
+    "loglevel": "error",
+    "access": "none"
+  },
+  "inbounds": [
+    {
+      "tag": "public-in",
+      "port": 443,
+      "listen": "0.0.0.0",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 10444,
+        "network": "tcp"
+      }
+    },
+    {
+      "tag": "tunnel-in",
+      "port": 10444,
+      "listen": "127.0.0.1",
+      "protocol": "dokodemo-door",
+      "settings": {
+        "address": "127.0.0.1",
+        "port": 8443,
+        "network": "tcp"
+      }
+    }
+  ],
+  "outbounds": [
+    {
+      "tag": "local-injector",
+      "protocol": "freedom",
+      "settings": {
+        "proxyProtocol": 2
+      }
+    },
+    {
+      "tag": "vless-out",
+      "protocol": "vless",
+      "settings": {
+        "vnext": [
+          {
+            "address": "<PUBLIC_IP_SERVER_B>",
+            "port": 443,
+            "users": [
+              {
+                "id": "<XRAY_UUID>",
+                "encryption": "none"
+              }
+            ]
+          }
+        ]
+      },
+      "streamSettings": {
+        "network": "xhttp",
+        "security": "reality",
+        "realitySettings": {
+          "serverName": "yahoo.com",
+          "publicKey": "<SERVER_B_PUBLIC_KEY>",
+          "shortId": "<SHORT_ID>",
+          "spiderX": "/",
+          "fingerprint": "chrome"
+        },
+        "xhttpSettings": {
+          "path": "/<YOUR_RANDOM_PATH>"
+        }
+      }
+    }
+  ],
+  "routing": {
+    "domainStrategy": "AsIs",
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": ["public-in"],
+        "outboundTag": "local-injector"
+      },
+      {
+        "type": "field",
+        "inboundTag": ["tunnel-in"],
+        "outboundTag": "vless-out"
+      }
+    ]
+  }
+}
+```
+*Замените `<PUBLIC_IP_SERVER_B>` на внешний IP-адрес Сервера B.*
+
+Открываем порт на фаерволе для клиентов:
+```bash
+sudo ufw allow 443/tcp
+```
+
+Перезапускаем Xray:
+```bash
+sudo systemctl restart xray
+sudo systemctl enable xray
+```
+
+---
+
+## Шаг 2. Установка и настройка telemt на Сервере B (_Нидерланды_)
+
+Установка telemt описана [в основной инструкции](../Quick_start/QUICK_START_GUIDE.ru.md).
+Отличие в том, что telemt должен слушать *внутренний* порт (так как 443 занят Xray-сервером), а также ожидать `PROXY` протокол из Xray туннеля.
+
+В конфиге `config.toml` прокси (на Сервере B) укажите:
+```toml
+[server]
+port = 8443
+listen_addr_ipv4 = "127.0.0.1"
+proxy_protocol = true
+
+[general.links]
+show = "*"
+public_host = "<FQDN_OR_IP_SERVER_A>"
+public_port = 443
+```
+
+- `port = 8443` и `listen_addr_ipv4 = "127.0.0.1"` означают, что telemt принимает подключения только изнутри (приходящие от локального Xray-процесса).
+- `proxy_protocol = true` заставляет telemt парсить PROXYv2-заголовок (который добавил Xray на Сервере A через loopback), восстанавливая IP-адрес конечного пользователя (РФ).
+- В `public_host` укажите публичный IP-адрес или домен Сервера A, чтобы ссылки на подключение генерировались корректно.
+
+Перезапустите `telemt`, и клиенты смогут подключаться по выданным ссылкам.
+
@@ -27,6 +27,8 @@ ACTION="install"
 TARGET_VERSION="${VERSION:-latest}"
 LANG_CHOICE="en"

+PATH="${PATH}:/usr/sbin:/sbin"
+
 set_language() {
    case "$1" in
        ru)
@@ -102,6 +104,8 @@ set_language() {
            L_OUT_SUCC_H="УСТАНОВКА УСПЕШНО ЗАВЕРШЕНА"
            L_OUT_UNINST_H="УДАЛЕНИЕ ЗАВЕРШЕНО"
            L_OUT_LINK="Ваша ссылка для подключения к Telegram Proxy:\n"
+            L_ERR_INCORR_ROOT_LOGIN="Используйте 'su -' или 'sudo -i' для входа под пользователем root"
+            L_OUT_LOGS="Чтобы посмотреть логи (в случае проблем), используйте команду:"
            ;;
        *)
            L_ERR_DOMAIN_REQ="requires a domain argument."
@@ -176,6 +180,8 @@ set_language() {
            L_OUT_SUCC_H="INSTALLATION SUCCESS"
            L_OUT_UNINST_H="UNINSTALLATION COMPLETE"
            L_OUT_LINK="Your Telegram Proxy connection link:\n"
+            L_ERR_INCORR_ROOT_LOGIN="Use 'su -' or 'sudo -i' to login under root"
+            L_OUT_LOGS="To view logs (in case of issues), use the following command:"
            ;;
    esac
 }
@@ -388,6 +394,9 @@ verify_common() {

    if [ "$(id -u)" -eq 0 ]; then
        SUDO=""
+        if [ "${USER:-}" != "root" ] && [ "${LOGNAME:-}" != "root" ]; then
+            die "$L_ERR_INCORR_ROOT_LOGIN"
+        fi
    else
        command -v sudo >/dev/null 2>&1 || die "$L_ERR_ROOT"
        SUDO="sudo"
@@ -532,7 +541,7 @@ install_binary() {
    fi

    $SUDO mkdir -p "$INSTALL_DIR" || die "$L_ERR_MKDIR"
-    
+
    $SUDO rm -f "$bin_dst" 2>/dev/null || true

    if command -v install >/dev/null 2>&1; then
@@ -602,33 +611,33 @@ install_config() {

        tmp_conf="${TEMP_DIR}/config.tmp"
        $SUDO cat "$CONFIG_FILE" > "$tmp_conf"
-        
+
        escaped_domain="$(printf '%s\n' "$TLS_DOMAIN" | tr -d '[:cntrl:]' | sed 's/\\/\\\\/g; s/"/\\"/g')"

        awk -v port="$SERVER_PORT" -v secret="$USER_SECRET" -v domain="$escaped_domain" -v ad_tag="$AD_TAG" \
            -v flag_p="$PORT_PROVIDED" -v flag_s="$SECRET_PROVIDED" -v flag_d="$DOMAIN_PROVIDED" -v flag_a="$AD_TAG_PROVIDED" '
        BEGIN { ad_tag_handled = 0 }
-        
+
        flag_p == "1" && /^[ \t]*port[ \t]*=/ { print "port = " port; next }
        flag_s == "1" && /^[ \t]*hello[ \t]*=/ { print "hello = \"" secret "\""; next }
        flag_d == "1" && /^[ \t]*tls_domain[ \t]*=/ { print "tls_domain = \"" domain "\""; next }
-        
-        flag_a == "1" && /^[ \t]*ad_tag[ \t]*=/ { 
-            if (!ad_tag_handled) { 
-                print "ad_tag = \"" ad_tag "\""; 
-                ad_tag_handled = 1; 
-            } 
-            next 
+
+        flag_a == "1" && /^[ \t]*ad_tag[ \t]*=/ {
+            if (!ad_tag_handled) {
+                print "ad_tag = \"" ad_tag "\"";
+                ad_tag_handled = 1;
+            }
+            next
        }
-        flag_a == "1" && /^\[general\]/ { 
-            print; 
-            if (!ad_tag_handled) { 
-                print "ad_tag = \"" ad_tag "\""; 
-                ad_tag_handled = 1; 
-            } 
-            next 
+        flag_a == "1" && /^\[general\]/ {
+            print;
+            if (!ad_tag_handled) {
+                print "ad_tag = \"" ad_tag "\"";
+                ad_tag_handled = 1;
+            }
+            next
        }
-        
+
        { print }
        ' "$tmp_conf" > "${tmp_conf}.new" && mv "${tmp_conf}.new" "$tmp_conf"

@@ -778,11 +787,11 @@ uninstall() {
        say "$L_U_STAGE_5"
        $SUDO rm -rf "$CONFIG_DIR" "$WORK_DIR"
        $SUDO rm -f "$CONFIG_FILE"
-        
+
        if check_os_entity passwd telemt; then
            $SUDO userdel telemt 2>/dev/null || $SUDO deluser telemt 2>/dev/null || true
        fi
-        
+
        if check_os_entity group telemt; then
            $SUDO groupdel telemt 2>/dev/null || $SUDO delgroup telemt 2>/dev/null || true
        fi
@@ -909,7 +918,7 @@ case "$ACTION" in
        if command -v curl >/dev/null 2>&1; then SERVER_IP="$(curl -s4 -m 3 ifconfig.me 2>/dev/null || curl -s4 -m 3 api.ipify.org 2>/dev/null || true)"
        elif command -v wget >/dev/null 2>&1; then SERVER_IP="$(wget -qO- -T 3 ifconfig.me 2>/dev/null || wget -qO- -T 3 api.ipify.org 2>/dev/null || true)"; fi
        [ -z "$SERVER_IP" ] && SERVER_IP="<YOUR_SERVER_IP>"
-        
+
        if command -v xxd >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | xxd -p | tr -d '\n')"
        elif command -v hexdump >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | hexdump -v -e '/1 "%02x"')"
        elif command -v od >/dev/null 2>&1; then HEX_DOMAIN="$(printf '%s' "$TLS_DOMAIN" | od -A n -t x1 | tr -d ' \n')"
@@ -920,6 +929,15 @@ case "$ACTION" in
        printf '%b\n' "$L_OUT_LINK"
        printf '  tg://proxy?server=%s&port=%s&secret=%s\n\n' "$SERVER_IP" "$SERVER_PORT" "$CLIENT_SECRET"

+        svc="$(get_svc_mgr)"
+        if [ "$svc" = "systemd" ]; then
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo journalctl -u %s -f\n\n' "$SERVICE_NAME"
+        elif [ "$svc" = "openrc" ]; then
+            printf '%s\n' "$L_OUT_LOGS"
+            printf '  sudo tail -f /var/log/messages /var/log/syslog 2>/dev/null | grep -i %s\n\n' "$SERVICE_NAME"
+        fi
+
        printf '====================================================================\n'
        ;;
 esac
@@ -7,7 +7,7 @@ use hyper::header::IF_MATCH;
 use serde::Serialize;
 use sha2::{Digest, Sha256};

-use crate::config::ProxyConfig;
+use crate::config::{ProxyConfig, RateLimitBps};

 use super::model::ApiFailure;

@@ -18,6 +18,7 @@ pub(super) enum AccessSection {
    UserMaxTcpConns,
    UserExpirations,
    UserDataQuota,
+    UserRateLimits,
    UserMaxUniqueIps,
 }

@@ -29,6 +30,7 @@ impl AccessSection {
            Self::UserMaxTcpConns => "access.user_max_tcp_conns",
            Self::UserExpirations => "access.user_expirations",
            Self::UserDataQuota => "access.user_data_quota",
+            Self::UserRateLimits => "access.user_rate_limits",
            Self::UserMaxUniqueIps => "access.user_max_unique_ips",
        }
    }
@@ -82,6 +84,7 @@ pub(super) async fn load_config_from_disk(config_path: &Path) -> Result<ProxyCon
        .map_err(|e| ApiFailure::internal(format!("failed to load config: {}", e)))
 }

+#[allow(dead_code)]
 pub(super) async fn save_config_to_disk(
    config_path: &Path,
    cfg: &ProxyConfig,
@@ -106,6 +109,12 @@ pub(super) async fn save_access_sections_to_disk(
        if applied.contains(section) {
            continue;
        }
+        if find_toml_table_bounds(&content, section.table_name()).is_none()
+            && access_section_is_empty(cfg, *section)
+        {
+            applied.push(*section);
+            continue;
+        }
        let rendered = render_access_section(cfg, *section)?;
        content = upsert_toml_table(&content, section.table_name(), &rendered);
        applied.push(*section);
@@ -162,6 +171,15 @@ fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<St
                .collect();
            serialize_table_body(&rows)?
        }
+        AccessSection::UserRateLimits => {
+            let rows: BTreeMap<String, RateLimitBps> = cfg
+                .access
+                .user_rate_limits
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_rate_limit_body(&rows)?
+        }
        AccessSection::UserMaxUniqueIps => {
            let rows: BTreeMap<String, usize> = cfg
                .access
@@ -183,11 +201,45 @@ fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<St
    Ok(out)
 }

+fn access_section_is_empty(cfg: &ProxyConfig, section: AccessSection) -> bool {
+    match section {
+        AccessSection::Users => cfg.access.users.is_empty(),
+        AccessSection::UserAdTags => cfg.access.user_ad_tags.is_empty(),
+        AccessSection::UserMaxTcpConns => cfg.access.user_max_tcp_conns.is_empty(),
+        AccessSection::UserExpirations => cfg.access.user_expirations.is_empty(),
+        AccessSection::UserDataQuota => cfg.access.user_data_quota.is_empty(),
+        AccessSection::UserRateLimits => cfg.access.user_rate_limits.is_empty(),
+        AccessSection::UserMaxUniqueIps => cfg.access.user_max_unique_ips.is_empty(),
+    }
+}
+
 fn serialize_table_body<T: Serialize>(value: &T) -> Result<String, ApiFailure> {
    toml::to_string(value)
        .map_err(|e| ApiFailure::internal(format!("failed to serialize access section: {}", e)))
 }

+fn serialize_rate_limit_body(rows: &BTreeMap<String, RateLimitBps>) -> Result<String, ApiFailure> {
+    let mut out = String::new();
+    for (key, value) in rows {
+        let key = serialize_toml_key(key)?;
+        out.push_str(&format!(
+            "{key} = {{ up_bps = {}, down_bps = {} }}\n",
+            value.up_bps, value.down_bps
+        ));
+    }
+    Ok(out)
+}
+
+fn serialize_toml_key(key: &str) -> Result<String, ApiFailure> {
+    let mut row = BTreeMap::new();
+    row.insert(key.to_string(), 0_u8);
+    let rendered = serialize_table_body(&row)?;
+    rendered
+        .split_once(" = ")
+        .map(|(key, _)| key.to_string())
+        .ok_or_else(|| ApiFailure::internal("failed to serialize TOML key"))
+}
+
 fn upsert_toml_table(source: &str, table_name: &str, replacement: &str) -> String {
    if let Some((start, end)) = find_toml_table_bounds(source, table_name) {
        let mut out = String::with_capacity(source.len() + replacement.len());
@@ -267,3 +319,26 @@ fn write_atomic_sync(path: &Path, contents: &str) -> std::io::Result<()> {
    }
    write_result
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn render_user_rate_limits_section() {
+        let mut cfg = ProxyConfig::default();
+        cfg.access.user_rate_limits.insert(
+            "alice".to_string(),
+            RateLimitBps {
+                up_bps: 1024,
+                down_bps: 2048,
+            },
+        );
+
+        let rendered = render_access_section(&cfg, AccessSection::UserRateLimits)
+            .expect("section must render");
+
+        assert!(rendered.starts_with("[access.user_rate_limits]\n"));
+        assert!(rendered.contains("alice = { up_bps = 1024, down_bps = 2048 }"));
+    }
+}
@@ -1,10 +1,11 @@
 #![allow(clippy::too_many_arguments)]

-use std::convert::Infallible;
+use std::io::{Error as IoError, ErrorKind};
 use std::net::{IpAddr, SocketAddr};
 use std::path::PathBuf;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::time::Duration;

 use http_body_util::Full;
 use hyper::body::{Bytes, Incoming};
@@ -12,11 +13,13 @@ use hyper::header::AUTHORIZATION;
 use hyper::server::conn::http1;
 use hyper::service::service_fn;
 use hyper::{Method, Request, Response, StatusCode};
+use subtle::ConstantTimeEq;
 use tokio::net::TcpListener;
-use tokio::sync::{Mutex, RwLock, watch};
+use tokio::sync::{Mutex, RwLock, Semaphore, watch};
+use tokio::time::timeout;
 use tracing::{debug, info, warn};

-use crate::config::ProxyConfig;
+use crate::config::{ApiGrayAction, ProxyConfig};
 use crate::ip_tracker::UserIpTracker;
 use crate::proxy::route_mode::RouteRuntimeController;
 use crate::startup::StartupTracker;
@@ -28,6 +31,7 @@ mod config_store;
 mod events;
 mod http_utils;
 mod model;
+mod patch;
 mod runtime_edge;
 mod runtime_init;
 mod runtime_min;
@@ -41,8 +45,9 @@ use config_store::{current_revision, load_config_from_disk, parse_if_match};
 use events::ApiEventStore;
 use http_utils::{error_response, read_json, read_optional_json, success_response};
 use model::{
-    ApiFailure, CreateUserRequest, DeleteUserResponse, HealthData, PatchUserRequest,
-    RotateSecretRequest, SummaryData, UserActiveIps,
+    ApiFailure, ClassCount, CreateUserRequest, DeleteUserResponse, HealthData, HealthReadyData,
+    PatchUserRequest, ResetUserQuotaResponse, RotateSecretRequest, SummaryData, UserActiveIps,
+    is_valid_username,
 };
 use runtime_edge::{
    EdgeConnectionsCacheEntry, build_runtime_connections_summary_data,
@@ -63,7 +68,13 @@ use runtime_zero::{
    build_limits_effective_data, build_runtime_gates_data, build_security_posture_data,
    build_system_info_data,
 };
-use users::{create_user, delete_user, patch_user, rotate_secret, users_from_config};
+use users::{
+    build_user_quota_list, create_user, delete_user, patch_user, rotate_secret, users_from_config,
+};
+
+const API_MAX_CONTROL_CONNECTIONS: usize = 1024;
+const API_HTTP_CONNECTION_TIMEOUT: Duration = Duration::from_secs(15);
+const ROUTE_USERNAME_ERROR: &str = "username must match [A-Za-z0-9_.-] and be 1..64 chars";

 pub(super) struct ApiRuntimeState {
    pub(super) process_started_at_epoch_secs: u64,
@@ -79,6 +90,7 @@ pub(super) struct ApiShared {
    pub(super) me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
    pub(super) upstream_manager: Arc<UpstreamManager>,
    pub(super) config_path: PathBuf,
+    pub(super) quota_state_path: PathBuf,
    pub(super) detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
    pub(super) mutation_lock: Arc<Mutex<()>>,
    pub(super) minimal_cache: Arc<Mutex<Option<MinimalCacheEntry>>>,
@@ -101,6 +113,18 @@ impl ApiShared {
    }
 }

+fn auth_header_matches(actual: &str, expected: &str) -> bool {
+    actual.as_bytes().ct_eq(expected.as_bytes()).into()
+}
+
+fn parse_route_username(user: &str) -> Result<&str, ApiFailure> {
+    if is_valid_username(user) {
+        Ok(user)
+    } else {
+        Err(ApiFailure::bad_request(ROUTE_USERNAME_ERROR))
+    }
+}
+
 pub async fn serve(
    listen: SocketAddr,
    stats: Arc<Stats>,
@@ -111,6 +135,7 @@ pub async fn serve(
    config_rx: watch::Receiver<Arc<ProxyConfig>>,
    admission_rx: watch::Receiver<bool>,
    config_path: PathBuf,
+    quota_state_path: PathBuf,
    detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
    process_started_at_epoch_secs: u64,
    startup_tracker: Arc<StartupTracker>,
@@ -142,6 +167,7 @@ pub async fn serve(
        me_pool,
        upstream_manager,
        config_path,
+        quota_state_path,
        detected_ips_rx,
        mutation_lock: Arc::new(Mutex::new(())),
        minimal_cache: Arc::new(Mutex::new(None)),
@@ -163,6 +189,8 @@ pub async fn serve(
        shared.runtime_events.clone(),
    );

+    let connection_permits = Arc::new(Semaphore::new(API_MAX_CONTROL_CONNECTIONS));
+
    loop {
        let (stream, peer) = match listener.accept().await {
            Ok(v) => v,
@@ -172,19 +200,46 @@ pub async fn serve(
            }
        };

+        let connection_permit = match connection_permits.clone().try_acquire_owned() {
+            Ok(permit) => permit,
+            Err(_) => {
+                debug!(
+                    peer = %peer,
+                    max_connections = API_MAX_CONTROL_CONNECTIONS,
+                    "Dropping API connection: control-plane connection budget exhausted"
+                );
+                continue;
+            }
+        };
+
        let shared_conn = shared.clone();
        let config_rx_conn = config_rx.clone();
        tokio::spawn(async move {
+            let _connection_permit = connection_permit;
            let svc = service_fn(move |req: Request<Incoming>| {
                let shared_req = shared_conn.clone();
                let config_rx_req = config_rx_conn.clone();
                async move { handle(req, peer, shared_req, config_rx_req).await }
            });
-            if let Err(error) = http1::Builder::new()
-                .serve_connection(hyper_util::rt::TokioIo::new(stream), svc)
-                .await
+            match timeout(
+                API_HTTP_CONNECTION_TIMEOUT,
+                http1::Builder::new().serve_connection(hyper_util::rt::TokioIo::new(stream), svc),
+            )
+            .await
            {
-                debug!(error = %error, "API connection error");
+                Ok(Ok(())) => {}
+                Ok(Err(error)) => {
+                    if !error.is_user() {
+                        debug!(error = %error, "API connection error");
+                    }
+                }
+                Err(_) => {
+                    debug!(
+                        peer = %peer,
+                        timeout_ms = API_HTTP_CONNECTION_TIMEOUT.as_millis() as u64,
+                        "API connection timed out"
+                    );
+                }
            }
        });
    }
@@ -195,7 +250,7 @@ async fn handle(
    peer: SocketAddr,
    shared: Arc<ApiShared>,
    config_rx: watch::Receiver<Arc<ProxyConfig>>,
-) -> Result<Response<Full<Bytes>>, Infallible> {
+) -> Result<Response<Full<Bytes>>, IoError> {
    let request_id = shared.next_request_id();
    let cfg = config_rx.borrow().clone();
    let api_cfg = &cfg.server.api;
@@ -213,14 +268,25 @@ async fn handle(

    if !api_cfg.whitelist.is_empty() && !api_cfg.whitelist.iter().any(|net| net.contains(peer.ip()))
    {
-        return Ok(error_response(
-            request_id,
-            ApiFailure::new(
-                StatusCode::FORBIDDEN,
-                "forbidden",
-                "Source IP is not allowed",
-            ),
-        ));
+        return match api_cfg.gray_action {
+            ApiGrayAction::Api => Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::FORBIDDEN,
+                    "forbidden",
+                    "Source IP is not allowed",
+                ),
+            )),
+            ApiGrayAction::Ok200 => Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("content-type", "text/html; charset=utf-8")
+                .body(Full::new(Bytes::new()))
+                .unwrap()),
+            ApiGrayAction::Drop => Err(IoError::new(
+                ErrorKind::ConnectionAborted,
+                "api request dropped by gray_action=drop",
+            )),
+        };
    }

    if !api_cfg.auth_header.is_empty() {
@@ -228,7 +294,7 @@ async fn handle(
            .headers()
            .get(AUTHORIZATION)
            .and_then(|v| v.to_str().ok())
-            .map(|v| v == api_cfg.auth_header)
+            .map(|v| auth_header_matches(v, &api_cfg.auth_header))
            .unwrap_or(false);
        if !auth_ok {
            return Ok(error_response(
@@ -244,11 +310,16 @@ async fn handle(

    let method = req.method().clone();
    let path = req.uri().path().to_string();
+    let normalized_path = if path.len() > 1 {
+        path.trim_end_matches('/')
+    } else {
+        path.as_str()
+    };
    let query = req.uri().query().map(str::to_string);
    let body_limit = api_cfg.request_body_limit_bytes;

    let result: Result<Response<Full<Bytes>>, ApiFailure> = async {
-        match (method.as_str(), path.as_str()) {
+        match (method.as_str(), normalized_path) {
            ("GET", "/v1/health") => {
                let revision = current_revision(&shared.config_path).await?;
                let data = HealthData {
@@ -257,6 +328,33 @@ async fn handle(
                };
                Ok(success_response(StatusCode::OK, data, revision))
            }
+            ("GET", "/v1/health/ready") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let admission_open = shared.runtime_state.admission_open.load(Ordering::Relaxed);
+                let upstream_health = shared.upstream_manager.api_health_summary().await;
+                let ready = admission_open && upstream_health.healthy_total > 0;
+                let reason = if ready {
+                    None
+                } else if !admission_open {
+                    Some("admission_closed")
+                } else {
+                    Some("no_healthy_upstreams")
+                };
+                let data = HealthReadyData {
+                    ready,
+                    status: if ready { "ready" } else { "not_ready" },
+                    reason,
+                    admission_open,
+                    healthy_upstreams: upstream_health.healthy_total,
+                    total_upstreams: upstream_health.configured_total,
+                };
+                let status_code = if ready {
+                    StatusCode::OK
+                } else {
+                    StatusCode::SERVICE_UNAVAILABLE
+                };
+                Ok(success_response(status_code, data, revision))
+            }
            ("GET", "/v1/system/info") => {
                let revision = current_revision(&shared.config_path).await?;
                let data = build_system_info_data(shared.as_ref(), cfg.as_ref(), &revision);
@@ -289,10 +387,24 @@ async fn handle(
            }
            ("GET", "/v1/stats/summary") => {
                let revision = current_revision(&shared.config_path).await?;
+                let connections_bad_by_class = shared
+                    .stats
+                    .get_connects_bad_class_counts()
+                    .into_iter()
+                    .map(|(class, total)| ClassCount { class, total })
+                    .collect();
+                let handshake_failures_by_class = shared
+                    .stats
+                    .get_handshake_failure_class_counts()
+                    .into_iter()
+                    .map(|(class, total)| ClassCount { class, total })
+                    .collect();
                let data = SummaryData {
                    uptime_seconds: shared.stats.uptime_secs(),
                    connections_total: shared.stats.get_connects_all(),
                    connections_bad_total: shared.stats.get_connects_bad(),
+                    connections_bad_by_class,
+                    handshake_failures_by_class,
                    handshake_timeouts_total: shared.stats.get_handshake_timeouts(),
                    configured_users: cfg.access.users.len(),
                };
@@ -394,6 +506,12 @@ async fn handle(
                .await;
                Ok(success_response(StatusCode::OK, users, revision))
            }
+            ("GET", "/v1/users/quota") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let disk_cfg = load_config_from_disk(&shared.config_path).await?;
+                let data = build_user_quota_list(&disk_cfg, shared.stats.as_ref());
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
            ("POST", "/v1/users") => {
                if api_cfg.read_only {
                    return Ok(error_response(
@@ -431,10 +549,115 @@ async fn handle(
                Ok(success_response(status, data, revision))
            }
            _ => {
-                if let Some(user) = path.strip_prefix("/v1/users/")
+                if method == Method::POST
+                    && let Some(user) = normalized_path
+                        .strip_prefix("/v1/users/")
+                        .and_then(|path| path.strip_suffix("/reset-quota"))
                    && !user.is_empty()
                    && !user.contains('/')
                {
+                    let user = parse_route_username(user)?;
+                    if api_cfg.read_only {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(
+                                StatusCode::FORBIDDEN,
+                                "read_only",
+                                "API runs in read-only mode",
+                            ),
+                        ));
+                    }
+                    let snapshot = match crate::quota_state::reset_user_quota(
+                        &shared.quota_state_path,
+                        shared.stats.as_ref(),
+                        user,
+                    )
+                    .await
+                    {
+                        Ok(snapshot) => snapshot,
+                        Err(error) => {
+                            shared.runtime_events.record(
+                                "api.user.reset_quota.failed",
+                                format!("username={} error={}", user, error),
+                            );
+                            return Err(ApiFailure::internal(format!(
+                                "Failed to reset user quota: {}",
+                                error
+                            )));
+                        }
+                    };
+                    shared
+                        .runtime_events
+                        .record("api.user.reset_quota.ok", format!("username={}", user));
+                    let revision = current_revision(&shared.config_path).await?;
+                    return Ok(success_response(
+                        StatusCode::OK,
+                        ResetUserQuotaResponse {
+                            username: user.to_string(),
+                            used_bytes: snapshot.used_bytes,
+                            last_reset_epoch_secs: snapshot.last_reset_epoch_secs,
+                        },
+                        revision,
+                    ));
+                }
+                if method == Method::POST
+                    && let Some(base_user) = normalized_path
+                        .strip_prefix("/v1/users/")
+                        .and_then(|path| path.strip_suffix("/rotate-secret"))
+                    && !base_user.is_empty()
+                    && !base_user.contains('/')
+                {
+                    let base_user = parse_route_username(base_user)?;
+                    if api_cfg.read_only {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(
+                                StatusCode::FORBIDDEN,
+                                "read_only",
+                                "API runs in read-only mode",
+                            ),
+                        ));
+                    }
+                    let expected_revision = parse_if_match(req.headers());
+                    let body =
+                        read_optional_json::<RotateSecretRequest>(req.into_body(), body_limit)
+                            .await?;
+                    let result = rotate_secret(
+                        base_user,
+                        body.unwrap_or_default(),
+                        expected_revision,
+                        &shared,
+                    )
+                    .await;
+                    let (mut data, revision) = match result {
+                        Ok(ok) => ok,
+                        Err(error) => {
+                            shared.runtime_events.record(
+                                "api.user.rotate_secret.failed",
+                                format!("username={} code={}", base_user, error.code),
+                            );
+                            return Err(error);
+                        }
+                    };
+                    let runtime_cfg = config_rx.borrow().clone();
+                    data.user.in_runtime =
+                        runtime_cfg.access.users.contains_key(&data.user.username);
+                    shared.runtime_events.record(
+                        "api.user.rotate_secret.ok",
+                        format!("username={}", base_user),
+                    );
+                    let status = if data.user.in_runtime {
+                        StatusCode::OK
+                    } else {
+                        StatusCode::ACCEPTED
+                    };
+                    return Ok(success_response(status, data, revision));
+                }
+                if let Some(user) = normalized_path.strip_prefix("/v1/users/")
+                    && !user.is_empty()
+                    && !user.contains('/')
+                {
+                    let user = parse_route_username(user)?;
                    if method == Method::GET {
                        let revision = current_revision(&shared.config_path).await?;
                        let disk_cfg = load_config_from_disk(&shared.config_path).await?;
@@ -535,56 +758,6 @@ async fn handle(
                        };
                        return Ok(success_response(status, response, revision));
                    }
-                    if method == Method::POST
-                        && let Some(base_user) = user.strip_suffix("/rotate-secret")
-                        && !base_user.is_empty()
-                        && !base_user.contains('/')
-                    {
-                        if api_cfg.read_only {
-                            return Ok(error_response(
-                                request_id,
-                                ApiFailure::new(
-                                    StatusCode::FORBIDDEN,
-                                    "read_only",
-                                    "API runs in read-only mode",
-                                ),
-                            ));
-                        }
-                        let expected_revision = parse_if_match(req.headers());
-                        let body =
-                            read_optional_json::<RotateSecretRequest>(req.into_body(), body_limit)
-                                .await?;
-                        let result = rotate_secret(
-                            base_user,
-                            body.unwrap_or_default(),
-                            expected_revision,
-                            &shared,
-                        )
-                        .await;
-                        let (mut data, revision) = match result {
-                            Ok(ok) => ok,
-                            Err(error) => {
-                                shared.runtime_events.record(
-                                    "api.user.rotate_secret.failed",
-                                    format!("username={} code={}", base_user, error.code),
-                                );
-                                return Err(error);
-                            }
-                        };
-                        let runtime_cfg = config_rx.borrow().clone();
-                        data.user.in_runtime =
-                            runtime_cfg.access.users.contains_key(&data.user.username);
-                        shared.runtime_events.record(
-                            "api.user.rotate_secret.ok",
-                            format!("username={}", base_user),
-                        );
-                        let status = if data.user.in_runtime {
-                            StatusCode::OK
-                        } else {
-                            StatusCode::ACCEPTED
-                        };
-                        return Ok(success_response(status, data, revision));
-                    }
                    if method == Method::POST {
                        return Ok(error_response(
                            request_id,
@@ -600,6 +773,12 @@ async fn handle(
                        ),
                    ));
                }
+                debug!(
+                    method = method.as_str(),
+                    path = %path,
+                    normalized_path = %normalized_path,
+                    "API route not found"
+                );
                Ok(error_response(
                    request_id,
                    ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "Route not found"),
@@ -5,6 +5,7 @@ use chrono::{DateTime, Utc};
 use hyper::StatusCode;
 use serde::{Deserialize, Serialize};

+use super::patch::{Patch, patch_field};
 use crate::crypto::SecureRandom;

 const MAX_USERNAME_LEN: usize = 64;
@@ -60,11 +61,30 @@ pub(super) struct HealthData {
    pub(super) read_only: bool,
 }

+#[derive(Serialize)]
+pub(super) struct HealthReadyData {
+    pub(super) ready: bool,
+    pub(super) status: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) admission_open: bool,
+    pub(super) healthy_upstreams: usize,
+    pub(super) total_upstreams: usize,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ClassCount {
+    pub(super) class: String,
+    pub(super) total: u64,
+}
+
 #[derive(Serialize)]
 pub(super) struct SummaryData {
    pub(super) uptime_seconds: f64,
    pub(super) connections_total: u64,
    pub(super) connections_bad_total: u64,
+    pub(super) connections_bad_by_class: Vec<ClassCount>,
+    pub(super) handshake_failures_by_class: Vec<ClassCount>,
    pub(super) handshake_timeouts_total: u64,
    pub(super) configured_users: usize,
 }
@@ -80,6 +100,8 @@ pub(super) struct ZeroCoreData {
    pub(super) uptime_seconds: f64,
    pub(super) connections_total: u64,
    pub(super) connections_bad_total: u64,
+    pub(super) connections_bad_by_class: Vec<ClassCount>,
+    pub(super) handshake_failures_by_class: Vec<ClassCount>,
    pub(super) handshake_timeouts_total: u64,
    pub(super) accept_permit_timeout_total: u64,
    pub(super) configured_users: usize,
@@ -434,6 +456,13 @@ pub(super) struct UserLinks {
    pub(super) classic: Vec<String>,
    pub(super) secure: Vec<String>,
    pub(super) tls: Vec<String>,
+    pub(super) tls_domains: Vec<TlsDomainLink>,
+}
+
+#[derive(Serialize)]
+pub(super) struct TlsDomainLink {
+    pub(super) domain: String,
+    pub(super) link: String,
 }

 #[derive(Serialize)]
@@ -444,6 +473,8 @@ pub(super) struct UserInfo {
    pub(super) max_tcp_conns: Option<usize>,
    pub(super) expiration_rfc3339: Option<String>,
    pub(super) data_quota_bytes: Option<u64>,
+    pub(super) rate_limit_up_bps: Option<u64>,
+    pub(super) rate_limit_down_bps: Option<u64>,
    pub(super) max_unique_ips: Option<usize>,
    pub(super) current_connections: u64,
    pub(super) active_unique_ips: usize,
@@ -472,6 +503,26 @@ pub(super) struct DeleteUserResponse {
    pub(super) in_runtime: bool,
 }

+#[derive(Serialize)]
+pub(super) struct ResetUserQuotaResponse {
+    pub(super) username: String,
+    pub(super) used_bytes: u64,
+    pub(super) last_reset_epoch_secs: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct UserQuotaListData {
+    pub(super) users: Vec<UserQuotaEntry>,
+}
+
+#[derive(Serialize)]
+pub(super) struct UserQuotaEntry {
+    pub(super) username: String,
+    pub(super) data_quota_bytes: u64,
+    pub(super) used_bytes: u64,
+    pub(super) last_reset_epoch_secs: u64,
+}
+
 #[derive(Deserialize)]
 pub(super) struct CreateUserRequest {
    pub(super) username: String,
@@ -480,17 +531,28 @@ pub(super) struct CreateUserRequest {
    pub(super) max_tcp_conns: Option<usize>,
    pub(super) expiration_rfc3339: Option<String>,
    pub(super) data_quota_bytes: Option<u64>,
+    pub(super) rate_limit_up_bps: Option<u64>,
+    pub(super) rate_limit_down_bps: Option<u64>,
    pub(super) max_unique_ips: Option<usize>,
 }

 #[derive(Deserialize)]
 pub(super) struct PatchUserRequest {
    pub(super) secret: Option<String>,
-    pub(super) user_ad_tag: Option<String>,
-    pub(super) max_tcp_conns: Option<usize>,
-    pub(super) expiration_rfc3339: Option<String>,
-    pub(super) data_quota_bytes: Option<u64>,
-    pub(super) max_unique_ips: Option<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) user_ad_tag: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) max_tcp_conns: Patch<usize>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) expiration_rfc3339: Patch<String>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) data_quota_bytes: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) rate_limit_up_bps: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) rate_limit_down_bps: Patch<u64>,
+    #[serde(default, deserialize_with = "patch_field")]
+    pub(super) max_unique_ips: Patch<usize>,
 }

 #[derive(Default, Deserialize)]
@@ -509,6 +571,20 @@ pub(super) fn parse_optional_expiration(
    Ok(Some(parsed.with_timezone(&Utc)))
 }

+pub(super) fn parse_patch_expiration(
+    value: &Patch<String>,
+) -> Result<Patch<DateTime<Utc>>, ApiFailure> {
+    match value {
+        Patch::Unchanged => Ok(Patch::Unchanged),
+        Patch::Remove => Ok(Patch::Remove),
+        Patch::Set(raw) => {
+            let parsed = DateTime::parse_from_rfc3339(raw)
+                .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
+            Ok(Patch::Set(parsed.with_timezone(&Utc)))
+        }
+    }
+}
+
 pub(super) fn is_valid_user_secret(secret: &str) -> bool {
    secret.len() == 32 && secret.chars().all(|c| c.is_ascii_hexdigit())
 }
@@ -0,0 +1,134 @@
+use serde::Deserialize;
+
+/// Three-state field for JSON Merge Patch semantics on the `PATCH /v1/users/{user}`
+/// endpoint.
+///
+/// `Unchanged` is produced when the JSON body omits the field entirely and tells the
+/// handler to leave the corresponding configuration entry untouched. `Remove` is
+/// produced when the JSON body sets the field to `null` and instructs the handler to
+/// drop the entry from the corresponding access HashMap. `Set` carries an explicit
+/// new value, including zero, which is preserved verbatim in the configuration.
+#[derive(Debug)]
+pub(super) enum Patch<T> {
+    Unchanged,
+    Remove,
+    Set(T),
+}
+
+impl<T> Default for Patch<T> {
+    fn default() -> Self {
+        Self::Unchanged
+    }
+}
+
+/// Serde deserializer adapter for fields that follow JSON Merge Patch semantics.
+///
+/// Pair this with `#[serde(default, deserialize_with = "patch_field")]` on a
+/// `Patch<T>` field. An omitted field falls back to `Patch::Unchanged` via
+/// `Default`; an explicit JSON `null` becomes `Patch::Remove`; any other value
+/// becomes `Patch::Set(v)`.
+pub(super) fn patch_field<'de, D, T>(deserializer: D) -> Result<Patch<T>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+    T: serde::Deserialize<'de>,
+{
+    Option::<T>::deserialize(deserializer).map(|opt| match opt {
+        Some(value) => Patch::Set(value),
+        None => Patch::Remove,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api::model::{PatchUserRequest, parse_patch_expiration};
+    use chrono::{TimeZone, Utc};
+    use serde::Deserialize;
+
+    #[derive(Deserialize)]
+    struct Holder {
+        #[serde(default, deserialize_with = "patch_field")]
+        value: Patch<u64>,
+    }
+
+    fn parse(json: &str) -> Holder {
+        serde_json::from_str(json).expect("valid json")
+    }
+
+    #[test]
+    fn omitted_field_yields_unchanged() {
+        let h = parse("{}");
+        assert!(matches!(h.value, Patch::Unchanged));
+    }
+
+    #[test]
+    fn explicit_null_yields_remove() {
+        let h = parse(r#"{"value": null}"#);
+        assert!(matches!(h.value, Patch::Remove));
+    }
+
+    #[test]
+    fn explicit_value_yields_set() {
+        let h = parse(r#"{"value": 42}"#);
+        assert!(matches!(h.value, Patch::Set(42)));
+    }
+
+    #[test]
+    fn explicit_zero_yields_set_zero() {
+        let h = parse(r#"{"value": 0}"#);
+        assert!(matches!(h.value, Patch::Set(0)));
+    }
+
+    #[test]
+    fn parse_patch_expiration_passes_unchanged_and_remove_through() {
+        assert!(matches!(
+            parse_patch_expiration(&Patch::Unchanged),
+            Ok(Patch::Unchanged)
+        ));
+        assert!(matches!(
+            parse_patch_expiration(&Patch::Remove),
+            Ok(Patch::Remove)
+        ));
+    }
+
+    #[test]
+    fn parse_patch_expiration_parses_set_value() {
+        let parsed =
+            parse_patch_expiration(&Patch::Set("2030-01-02T03:04:05Z".into())).expect("valid");
+        match parsed {
+            Patch::Set(dt) => {
+                assert_eq!(dt, Utc.with_ymd_and_hms(2030, 1, 2, 3, 4, 5).unwrap());
+            }
+            other => panic!("expected Patch::Set, got {:?}", other),
+        }
+    }
+
+    #[test]
+    fn parse_patch_expiration_rejects_invalid_set_value() {
+        assert!(parse_patch_expiration(&Patch::Set("not-a-date".into())).is_err());
+    }
+
+    #[test]
+    fn patch_user_request_deserializes_mixed_states() {
+        let raw = r#"{
+            "secret": "00112233445566778899aabbccddeeff",
+            "max_tcp_conns": 0,
+            "max_unique_ips": null,
+            "data_quota_bytes": 1024,
+            "rate_limit_up_bps": 4096,
+            "rate_limit_down_bps": null
+        }"#;
+        let req: PatchUserRequest = serde_json::from_str(raw).expect("valid json");
+        assert_eq!(
+            req.secret.as_deref(),
+            Some("00112233445566778899aabbccddeeff")
+        );
+        assert!(matches!(req.max_tcp_conns, Patch::Set(0)));
+        assert!(matches!(req.max_unique_ips, Patch::Remove));
+        assert!(matches!(req.data_quota_bytes, Patch::Set(1024)));
+        assert!(matches!(req.rate_limit_up_bps, Patch::Set(4096)));
+        assert!(matches!(req.rate_limit_down_bps, Patch::Remove));
+        assert!(matches!(req.expiration_rfc3339, Patch::Unchanged));
+        assert!(matches!(req.user_ad_tag, Patch::Unchanged));
+    }
+}
@@ -7,8 +7,8 @@ use crate::transport::upstream::IpPreference;

 use super::ApiShared;
 use super::model::{
-    DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData, MeWritersSummary,
-    MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
+    ClassCount, DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData,
+    MeWritersSummary, MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
    MinimalQuarantineData, UpstreamDcStatus, UpstreamStatus, UpstreamSummaryData, UpstreamsData,
    ZeroAllData, ZeroCodeCount, ZeroCoreData, ZeroDesyncData, ZeroMiddleProxyData, ZeroPoolData,
    ZeroUpstreamData,
@@ -26,6 +26,16 @@ pub(crate) struct MinimalCacheEntry {

 pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> ZeroAllData {
    let telemetry = stats.telemetry_policy();
+    let bad_connection_classes = stats
+        .get_connects_bad_class_counts()
+        .into_iter()
+        .map(|(class, total)| ClassCount { class, total })
+        .collect();
+    let handshake_failure_classes = stats
+        .get_handshake_failure_class_counts()
+        .into_iter()
+        .map(|(class, total)| ClassCount { class, total })
+        .collect();
    let handshake_error_codes = stats
        .get_me_handshake_error_code_counts()
        .into_iter()
@@ -38,6 +48,8 @@ pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> Zer
            uptime_seconds: stats.uptime_secs(),
            connections_total: stats.get_connects_all(),
            connections_bad_total: stats.get_connects_bad(),
+            connections_bad_by_class: bad_connection_classes,
+            handshake_failures_by_class: handshake_failure_classes,
            handshake_timeouts_total: stats.get_handshake_timeouts(),
            accept_permit_timeout_total: stats.get_accept_permit_timeout_total(),
            configured_users,
@@ -178,6 +178,7 @@ pub(super) async fn build_runtime_gates_data(
    cfg: &ProxyConfig,
 ) -> RuntimeGatesData {
    let startup_summary = build_runtime_startup_summary(shared).await;
+    let startup_snapshot = shared.startup_tracker.snapshot().await;
    let route_state = shared.route_runtime.snapshot();
    let route_mode = route_state.mode.as_str();
    let fast_fallback_enabled =
@@ -191,7 +192,9 @@ pub(super) async fn build_runtime_gates_data(
        None
    };
    let reroute_reason = if reroute_active {
-        if fast_fallback_enabled {
+        if startup_snapshot.me.status.as_str() != "ready" {
+            Some("startup_direct_fallback")
+        } else if fast_fallback_enabled {
            Some("fast_not_ready_fallback")
        } else {
            Some("strict_grace_fallback")
@@ -3,19 +3,22 @@ use std::net::IpAddr;
 use hyper::StatusCode;

 use crate::config::ProxyConfig;
+use crate::config::RateLimitBps;
 use crate::ip_tracker::UserIpTracker;
 use crate::stats::Stats;

 use super::ApiShared;
 use super::config_store::{
-    AccessSection, ensure_expected_revision, load_config_from_disk, save_access_sections_to_disk,
-    save_config_to_disk,
+    AccessSection, current_revision, ensure_expected_revision, load_config_from_disk,
+    save_access_sections_to_disk,
 };
 use super::model::{
    ApiFailure, CreateUserRequest, CreateUserResponse, PatchUserRequest, RotateSecretRequest,
-    UserInfo, UserLinks, is_valid_ad_tag, is_valid_user_secret, is_valid_username,
-    parse_optional_expiration, random_user_secret,
+    TlsDomainLink, UserInfo, UserLinks, UserQuotaEntry, UserQuotaListData, is_valid_ad_tag,
+    is_valid_user_secret, is_valid_username, parse_optional_expiration, parse_patch_expiration,
+    random_user_secret,
 };
+use super::patch::Patch;

 pub(super) async fn create_user(
    body: CreateUserRequest,
@@ -26,6 +29,8 @@ pub(super) async fn create_user(
    let touches_user_max_tcp_conns = body.max_tcp_conns.is_some();
    let touches_user_expirations = body.expiration_rfc3339.is_some();
    let touches_user_data_quota = body.data_quota_bytes.is_some();
+    let touches_user_rate_limits =
+        body.rate_limit_up_bps.is_some() || body.rate_limit_down_bps.is_some();
    let touches_user_max_unique_ips = body.max_unique_ips.is_some();

    if !is_valid_username(&body.username) {
@@ -90,6 +95,15 @@ pub(super) async fn create_user(
            .user_data_quota
            .insert(body.username.clone(), quota);
    }
+    if touches_user_rate_limits {
+        cfg.access.user_rate_limits.insert(
+            body.username.clone(),
+            RateLimitBps {
+                up_bps: body.rate_limit_up_bps.unwrap_or(0),
+                down_bps: body.rate_limit_down_bps.unwrap_or(0),
+            },
+        );
+    }

    let updated_limit = body.max_unique_ips;
    if let Some(limit) = updated_limit {
@@ -114,6 +128,9 @@ pub(super) async fn create_user(
    if touches_user_data_quota {
        touched_sections.push(AccessSection::UserDataQuota);
    }
+    if touches_user_rate_limits {
+        touched_sections.push(AccessSection::UserRateLimits);
+    }
    if touches_user_max_unique_ips {
        touched_sections.push(AccessSection::UserMaxUniqueIps);
    }
@@ -156,6 +173,8 @@ pub(super) async fn create_user(
                    .then_some(cfg.access.user_max_tcp_conns_global_each)),
            expiration_rfc3339: None,
            data_quota_bytes: None,
+            rate_limit_up_bps: body.rate_limit_up_bps.filter(|limit| *limit > 0),
+            rate_limit_down_bps: body.rate_limit_down_bps.filter(|limit| *limit > 0),
            max_unique_ips: updated_limit,
            current_connections: 0,
            active_unique_ips: 0,
@@ -175,6 +194,15 @@ pub(super) async fn patch_user(
    expected_revision: Option<String>,
    shared: &ApiShared,
 ) -> Result<(UserInfo, String), ApiFailure> {
+    let touches_users = body.secret.is_some();
+    let touches_user_ad_tags = !matches!(&body.user_ad_tag, Patch::Unchanged);
+    let touches_user_max_tcp_conns = !matches!(&body.max_tcp_conns, Patch::Unchanged);
+    let touches_user_expirations = !matches!(&body.expiration_rfc3339, Patch::Unchanged);
+    let touches_user_data_quota = !matches!(&body.data_quota_bytes, Patch::Unchanged);
+    let touches_user_rate_limits = !matches!(&body.rate_limit_up_bps, Patch::Unchanged)
+        || !matches!(&body.rate_limit_down_bps, Patch::Unchanged);
+    let touches_user_max_unique_ips = !matches!(&body.max_unique_ips, Patch::Unchanged);
+
    if let Some(secret) = body.secret.as_ref()
        && !is_valid_user_secret(secret)
    {
@@ -182,14 +210,14 @@ pub(super) async fn patch_user(
            "secret must be exactly 32 hex characters",
        ));
    }
-    if let Some(ad_tag) = body.user_ad_tag.as_ref()
+    if let Patch::Set(ad_tag) = &body.user_ad_tag
        && !is_valid_ad_tag(ad_tag)
    {
        return Err(ApiFailure::bad_request(
            "user_ad_tag must be exactly 32 hex characters",
        ));
    }
-    let expiration = parse_optional_expiration(body.expiration_rfc3339.as_deref())?;
+    let expiration = parse_patch_expiration(&body.expiration_rfc3339)?;
    let _guard = shared.mutation_lock.lock().await;
    let mut cfg = load_config_from_disk(&shared.config_path).await?;
    ensure_expected_revision(&shared.config_path, expected_revision.as_deref()).await?;
@@ -205,38 +233,123 @@ pub(super) async fn patch_user(
    if let Some(secret) = body.secret {
        cfg.access.users.insert(user.to_string(), secret);
    }
-    if let Some(ad_tag) = body.user_ad_tag {
-        cfg.access.user_ad_tags.insert(user.to_string(), ad_tag);
+    match body.user_ad_tag {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_ad_tags.remove(user);
+        }
+        Patch::Set(ad_tag) => {
+            cfg.access.user_ad_tags.insert(user.to_string(), ad_tag);
+        }
    }
-    if let Some(limit) = body.max_tcp_conns {
-        cfg.access
-            .user_max_tcp_conns
-            .insert(user.to_string(), limit);
+    match body.max_tcp_conns {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_max_tcp_conns.remove(user);
+        }
+        Patch::Set(limit) => {
+            cfg.access
+                .user_max_tcp_conns
+                .insert(user.to_string(), limit);
+        }
    }
-    if let Some(expiration) = expiration {
-        cfg.access
-            .user_expirations
-            .insert(user.to_string(), expiration);
+    match expiration {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_expirations.remove(user);
+        }
+        Patch::Set(expiration) => {
+            cfg.access
+                .user_expirations
+                .insert(user.to_string(), expiration);
+        }
    }
-    if let Some(quota) = body.data_quota_bytes {
-        cfg.access.user_data_quota.insert(user.to_string(), quota);
+    match body.data_quota_bytes {
+        Patch::Unchanged => {}
+        Patch::Remove => {
+            cfg.access.user_data_quota.remove(user);
+        }
+        Patch::Set(quota) => {
+            cfg.access.user_data_quota.insert(user.to_string(), quota);
+        }
    }
-
-    let mut updated_limit = None;
-    if let Some(limit) = body.max_unique_ips {
-        cfg.access
-            .user_max_unique_ips
-            .insert(user.to_string(), limit);
-        updated_limit = Some(limit);
+    if touches_user_rate_limits {
+        let mut rate_limit = cfg
+            .access
+            .user_rate_limits
+            .get(user)
+            .copied()
+            .unwrap_or_default();
+        match body.rate_limit_up_bps {
+            Patch::Unchanged => {}
+            Patch::Remove => rate_limit.up_bps = 0,
+            Patch::Set(limit) => rate_limit.up_bps = limit,
+        }
+        match body.rate_limit_down_bps {
+            Patch::Unchanged => {}
+            Patch::Remove => rate_limit.down_bps = 0,
+            Patch::Set(limit) => rate_limit.down_bps = limit,
+        }
+        if rate_limit.up_bps == 0 && rate_limit.down_bps == 0 {
+            cfg.access.user_rate_limits.remove(user);
+        } else {
+            cfg.access
+                .user_rate_limits
+                .insert(user.to_string(), rate_limit);
+        }
    }
+    // Capture how the per-user IP limit changed, so the in-memory ip_tracker
+    // can be synced (set or removed) after the config is persisted.
+    let max_unique_ips_change = match body.max_unique_ips {
+        Patch::Unchanged => None,
+        Patch::Remove => {
+            cfg.access.user_max_unique_ips.remove(user);
+            Some(None)
+        }
+        Patch::Set(limit) => {
+            cfg.access
+                .user_max_unique_ips
+                .insert(user.to_string(), limit);
+            Some(Some(limit))
+        }
+    };

    cfg.validate()
        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;

-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let mut touched_sections = Vec::new();
+    if touches_users {
+        touched_sections.push(AccessSection::Users);
+    }
+    if touches_user_ad_tags {
+        touched_sections.push(AccessSection::UserAdTags);
+    }
+    if touches_user_max_tcp_conns {
+        touched_sections.push(AccessSection::UserMaxTcpConns);
+    }
+    if touches_user_expirations {
+        touched_sections.push(AccessSection::UserExpirations);
+    }
+    if touches_user_data_quota {
+        touched_sections.push(AccessSection::UserDataQuota);
+    }
+    if touches_user_rate_limits {
+        touched_sections.push(AccessSection::UserRateLimits);
+    }
+    if touches_user_max_unique_ips {
+        touched_sections.push(AccessSection::UserMaxUniqueIps);
+    }
+
+    let revision = if touched_sections.is_empty() {
+        current_revision(&shared.config_path).await?
+    } else {
+        save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?
+    };
    drop(_guard);
-    if let Some(limit) = updated_limit {
-        shared.ip_tracker.set_user_limit(user, limit).await;
+    match max_unique_ips_change {
+        Some(Some(limit)) => shared.ip_tracker.set_user_limit(user, limit).await,
+        Some(None) => shared.ip_tracker.remove_user_limit(user).await,
+        None => {}
    }
    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
    let users = users_from_config(
@@ -290,6 +403,7 @@ pub(super) async fn rotate_secret(
        AccessSection::UserMaxTcpConns,
        AccessSection::UserExpirations,
        AccessSection::UserDataQuota,
+        AccessSection::UserRateLimits,
        AccessSection::UserMaxUniqueIps,
    ];
    let revision =
@@ -349,6 +463,7 @@ pub(super) async fn delete_user(
    cfg.access.user_max_tcp_conns.remove(user);
    cfg.access.user_expirations.remove(user);
    cfg.access.user_data_quota.remove(user);
+    cfg.access.user_rate_limits.remove(user);
    cfg.access.user_max_unique_ips.remove(user);

    cfg.validate()
@@ -359,6 +474,7 @@ pub(super) async fn delete_user(
        AccessSection::UserMaxTcpConns,
        AccessSection::UserExpirations,
        AccessSection::UserDataQuota,
+        AccessSection::UserRateLimits,
        AccessSection::UserMaxUniqueIps,
    ];
    let revision =
@@ -400,11 +516,7 @@ pub(super) async fn users_from_config(
            .map(|secret| {
                build_user_links(cfg, secret, startup_detected_ip_v4, startup_detected_ip_v6)
            })
-            .unwrap_or(UserLinks {
-                classic: Vec::new(),
-                secure: Vec::new(),
-                tls: Vec::new(),
-            });
+            .unwrap_or_else(empty_user_links);
        users.push(UserInfo {
            in_runtime: runtime_cfg
                .map(|runtime| runtime.access.users.contains_key(&username))
@@ -424,6 +536,18 @@ pub(super) async fn users_from_config(
                .get(&username)
                .map(chrono::DateTime::<chrono::Utc>::to_rfc3339),
            data_quota_bytes: cfg.access.user_data_quota.get(&username).copied(),
+            rate_limit_up_bps: cfg
+                .access
+                .user_rate_limits
+                .get(&username)
+                .map(|limit| limit.up_bps)
+                .filter(|limit| *limit > 0),
+            rate_limit_down_bps: cfg
+                .access
+                .user_rate_limits
+                .get(&username)
+                .map(|limit| limit.down_bps)
+                .filter(|limit| *limit > 0),
            max_unique_ips: cfg
                .access
                .user_max_unique_ips
@@ -445,6 +569,42 @@ pub(super) async fn users_from_config(
    users
 }

+pub(super) fn build_user_quota_list(cfg: &ProxyConfig, stats: &Stats) -> UserQuotaListData {
+    let mut names = cfg.access.users.keys().cloned().collect::<Vec<_>>();
+    names.sort();
+
+    let snapshot = stats.user_quota_snapshot();
+    let mut users = Vec::with_capacity(names.len());
+    for username in names {
+        let Some(&data_quota_bytes) = cfg.access.user_data_quota.get(&username) else {
+            continue;
+        };
+        if data_quota_bytes == 0 {
+            continue;
+        }
+        let (used_bytes, last_reset_epoch_secs) = snapshot
+            .get(&username)
+            .map(|entry| (entry.used_bytes, entry.last_reset_epoch_secs))
+            .unwrap_or((0, 0));
+        users.push(UserQuotaEntry {
+            username,
+            data_quota_bytes,
+            used_bytes,
+            last_reset_epoch_secs,
+        });
+    }
+    UserQuotaListData { users }
+}
+
+fn empty_user_links() -> UserLinks {
+    UserLinks {
+        classic: Vec::new(),
+        secure: Vec::new(),
+        tls: Vec::new(),
+        tls_domains: Vec::new(),
+    }
+}
+
 fn build_user_links(
    cfg: &ProxyConfig,
    secret: &str,
@@ -452,12 +612,18 @@ fn build_user_links(
    startup_detected_ip_v6: Option<IpAddr>,
 ) -> UserLinks {
    let hosts = resolve_link_hosts(cfg, startup_detected_ip_v4, startup_detected_ip_v6);
-    let port = cfg.general.links.public_port.unwrap_or(cfg.server.port);
+    let port = cfg
+        .general
+        .links
+        .public_port
+        .unwrap_or(resolve_default_link_port(cfg));
    let tls_domains = resolve_tls_domains(cfg);
+    let extra_tls_domains = resolve_extra_tls_domains(cfg);

    let mut classic = Vec::new();
    let mut secure = Vec::new();
    let mut tls = Vec::new();
+    let mut tls_domain_links = Vec::new();

    for host in &hosts {
        if cfg.general.modes.classic {
@@ -480,6 +646,17 @@ fn build_user_links(
                    host, port, secret, domain_hex
                ));
            }
+            for domain in &extra_tls_domains {
+                let domain_hex = hex::encode(domain);
+                let link = format!(
+                    "tg://proxy?server={}&port={}&secret=ee{}{}",
+                    host, port, secret, domain_hex
+                );
+                tls_domain_links.push(TlsDomainLink {
+                    domain: (*domain).to_string(),
+                    link,
+                });
+            }
        }
    }

@@ -487,9 +664,18 @@ fn build_user_links(
        classic,
        secure,
        tls,
+        tls_domains: tls_domain_links,
    }
 }

+fn resolve_default_link_port(cfg: &ProxyConfig) -> u16 {
+    cfg.server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(cfg.server.port)
+}
+
 fn resolve_link_hosts(
    cfg: &ProxyConfig,
    startup_detected_ip_v4: Option<IpAddr>,
@@ -595,6 +781,19 @@ fn resolve_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
    domains
 }

+fn resolve_extra_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
+    let mut domains = Vec::with_capacity(cfg.censorship.tls_domains.len());
+    let primary = cfg.censorship.tls_domain.as_str();
+    for domain in &cfg.censorship.tls_domains {
+        let value = domain.as_str();
+        if value.is_empty() || value == primary || domains.contains(&value) {
+            continue;
+        }
+        domains.push(value);
+    }
+    domains
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -649,6 +848,34 @@ mod tests {
        assert_eq!(alice.max_tcp_conns, None);
    }

+    #[tokio::test]
+    async fn users_from_config_reports_user_rate_limits() {
+        let mut cfg = ProxyConfig::default();
+        cfg.access.users.insert(
+            "alice".to_string(),
+            "0123456789abcdef0123456789abcdef".to_string(),
+        );
+        cfg.access.user_rate_limits.insert(
+            "alice".to_string(),
+            RateLimitBps {
+                up_bps: 1024,
+                down_bps: 0,
+            },
+        );
+
+        let stats = Stats::new();
+        let tracker = UserIpTracker::new();
+
+        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+        let alice = users
+            .iter()
+            .find(|entry| entry.username == "alice")
+            .expect("alice must be present");
+
+        assert_eq!(alice.rate_limit_up_bps, Some(1024));
+        assert_eq!(alice.rate_limit_down_bps, None);
+    }
+
    #[tokio::test]
    async fn users_from_config_marks_runtime_membership_when_snapshot_is_provided() {
        let mut disk_cfg = ProxyConfig::default();
@@ -684,4 +911,144 @@ mod tests {
        assert!(alice.in_runtime);
        assert!(!bob.in_runtime);
    }
+
+    #[tokio::test]
+    async fn users_from_config_returns_tls_link_for_each_tls_domain() {
+        let mut cfg = ProxyConfig::default();
+        cfg.access.users.insert(
+            "alice".to_string(),
+            "0123456789abcdef0123456789abcdef".to_string(),
+        );
+        cfg.general.modes.classic = false;
+        cfg.general.modes.secure = false;
+        cfg.general.modes.tls = true;
+        cfg.general.links.public_host = Some("proxy.example.net".to_string());
+        cfg.general.links.public_port = Some(443);
+        cfg.censorship.tls_domain = "front-a.example.com".to_string();
+        cfg.censorship.tls_domains = vec![
+            "front-b.example.com".to_string(),
+            "front-c.example.com".to_string(),
+            "front-b.example.com".to_string(),
+            "front-a.example.com".to_string(),
+        ];
+
+        let stats = Stats::new();
+        let tracker = UserIpTracker::new();
+        let users = users_from_config(&cfg, &stats, &tracker, None, None, None).await;
+        let alice = users
+            .iter()
+            .find(|entry| entry.username == "alice")
+            .expect("alice must be present");
+
+        assert_eq!(alice.links.tls.len(), 3);
+        assert!(
+            alice
+                .links
+                .tls
+                .iter()
+                .any(|link| link.ends_with(&hex::encode("front-a.example.com")))
+        );
+        assert!(
+            alice
+                .links
+                .tls
+                .iter()
+                .any(|link| link.ends_with(&hex::encode("front-b.example.com")))
+        );
+        assert!(
+            alice
+                .links
+                .tls
+                .iter()
+                .any(|link| link.ends_with(&hex::encode("front-c.example.com")))
+        );
+        assert_eq!(alice.links.tls_domains.len(), 2);
+        assert!(
+            alice
+                .links
+                .tls_domains
+                .iter()
+                .any(|entry| entry.domain == "front-b.example.com"
+                    && entry.link.ends_with(&hex::encode("front-b.example.com")))
+        );
+        assert!(
+            alice
+                .links
+                .tls_domains
+                .iter()
+                .any(|entry| entry.domain == "front-c.example.com"
+                    && entry.link.ends_with(&hex::encode("front-c.example.com")))
+        );
+        assert!(
+            !alice
+                .links
+                .tls_domains
+                .iter()
+                .any(|entry| entry.domain == "front-a.example.com")
+        );
+    }
+
+    #[test]
+    fn build_user_quota_list_skips_users_without_positive_quota_and_sorts_by_username() {
+        let mut cfg = ProxyConfig::default();
+        cfg.access.users.insert(
+            "alice".to_string(),
+            "0123456789abcdef0123456789abcdef".to_string(),
+        );
+        cfg.access.users.insert(
+            "bob".to_string(),
+            "fedcba9876543210fedcba9876543210".to_string(),
+        );
+        cfg.access.users.insert(
+            "carol".to_string(),
+            "aaaabbbbccccddddeeeeffff00001111".to_string(),
+        );
+        // alice has a positive quota and should be listed.
+        cfg.access
+            .user_data_quota
+            .insert("alice".to_string(), 1 << 20);
+        // bob has no quota entry at all (None) — should be skipped.
+        // carol has an explicit zero quota — should be skipped.
+        cfg.access.user_data_quota.insert("carol".to_string(), 0);
+
+        let stats = Stats::new();
+        // Charge some traffic against alice; carol gets traffic too but should
+        // still be filtered out by the quota check.
+        let alice_stats = stats.get_or_create_user_stats_handle("alice");
+        stats.quota_charge_post_write(&alice_stats, 4096);
+        let carol_stats = stats.get_or_create_user_stats_handle("carol");
+        stats.quota_charge_post_write(&carol_stats, 99);
+
+        let data = build_user_quota_list(&cfg, &stats);
+
+        assert_eq!(data.users.len(), 1);
+        let entry = &data.users[0];
+        assert_eq!(entry.username, "alice");
+        assert_eq!(entry.data_quota_bytes, 1 << 20);
+        assert_eq!(entry.used_bytes, 4096);
+        assert_eq!(entry.last_reset_epoch_secs, 0);
+    }
+
+    #[test]
+    fn build_user_quota_list_orders_multiple_users_by_username_ascending() {
+        let mut cfg = ProxyConfig::default();
+        for name in ["charlie", "alice", "bob"] {
+            cfg.access.users.insert(
+                name.to_string(),
+                "0123456789abcdef0123456789abcdef".to_string(),
+            );
+            cfg.access.user_data_quota.insert(name.to_string(), 1 << 30);
+        }
+
+        let stats = Stats::new();
+        let data = build_user_quota_list(&cfg, &stats);
+
+        let names: Vec<&str> = data.users.iter().map(|e| e.username.as_str()).collect();
+        assert_eq!(names, vec!["alice", "bob", "charlie"]);
+        for entry in &data.users {
+            assert_eq!(entry.used_bytes, 0);
+            assert_eq!(entry.last_reset_epoch_secs, 0);
+            assert_eq!(entry.data_quota_bytes, 1 << 30);
+        }
+    }
 }
@@ -6,12 +6,15 @@
 //! - `reload [--pid-file PATH]` - Reload configuration (SIGHUP)
 //! - `status [--pid-file PATH]` - Check daemon status
 //! - `run [OPTIONS] [config.toml]` - Run in foreground (default behavior)
+//! - `healthcheck [OPTIONS] [config.toml]` - Run control-plane health probe

 use rand::RngExt;
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::process::Command;

+use crate::healthcheck::{self, HealthcheckMode};
+
 #[cfg(unix)]
 use crate::daemon::{self, DEFAULT_PID_FILE, DaemonOptions};

@@ -28,6 +31,8 @@ pub enum Subcommand {
    Reload,
    /// Check daemon status (`status` subcommand).
    Status,
+    /// Run health probe and exit with status code.
+    Healthcheck,
    /// Fire-and-forget setup (`--init`).
    Init,
 }
@@ -38,6 +43,8 @@ pub struct ParsedCommand {
    pub subcommand: Subcommand,
    pub pid_file: PathBuf,
    pub config_path: String,
+    pub healthcheck_mode: HealthcheckMode,
+    pub healthcheck_mode_invalid: Option<String>,
    #[cfg(unix)]
    pub daemon_opts: DaemonOptions,
    pub init_opts: Option<InitOptions>,
@@ -52,6 +59,8 @@ impl Default for ParsedCommand {
            #[cfg(not(unix))]
            pid_file: PathBuf::from("/var/run/telemt.pid"),
            config_path: "config.toml".to_string(),
+            healthcheck_mode: HealthcheckMode::Liveness,
+            healthcheck_mode_invalid: None,
            #[cfg(unix)]
            daemon_opts: DaemonOptions::default(),
            init_opts: None,
@@ -91,6 +100,9 @@ pub fn parse_command(args: &[String]) -> ParsedCommand {
            "status" => {
                cmd.subcommand = Subcommand::Status;
            }
+            "healthcheck" => {
+                cmd.subcommand = Subcommand::Healthcheck;
+            }
            "run" => {
                cmd.subcommand = Subcommand::Run;
                #[cfg(unix)]
@@ -113,7 +125,35 @@ pub fn parse_command(args: &[String]) -> ParsedCommand {
    while i < args.len() {
        match args[i].as_str() {
            // Skip subcommand names
-            "start" | "stop" | "reload" | "status" | "run" => {}
+            "start" | "stop" | "reload" | "status" | "run" | "healthcheck" => {}
+            "--mode" => {
+                i += 1;
+                if i < args.len() {
+                    match HealthcheckMode::from_cli_arg(&args[i]) {
+                        Some(mode) => {
+                            cmd.healthcheck_mode = mode;
+                            cmd.healthcheck_mode_invalid = None;
+                        }
+                        None => {
+                            cmd.healthcheck_mode_invalid = Some(args[i].clone());
+                        }
+                    }
+                } else {
+                    cmd.healthcheck_mode_invalid = Some(String::new());
+                }
+            }
+            s if s.starts_with("--mode=") => {
+                let raw = s.trim_start_matches("--mode=");
+                match HealthcheckMode::from_cli_arg(raw) {
+                    Some(mode) => {
+                        cmd.healthcheck_mode = mode;
+                        cmd.healthcheck_mode_invalid = None;
+                    }
+                    None => {
+                        cmd.healthcheck_mode_invalid = Some(raw.to_string());
+                    }
+                }
+            }
            // PID file option (for stop/reload/status)
            "--pid-file" => {
                i += 1;
@@ -152,6 +192,20 @@ pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
        Subcommand::Stop => Some(cmd_stop(&cmd.pid_file)),
        Subcommand::Reload => Some(cmd_reload(&cmd.pid_file)),
        Subcommand::Status => Some(cmd_status(&cmd.pid_file)),
+        Subcommand::Healthcheck => {
+            if let Some(invalid_mode) = cmd.healthcheck_mode_invalid.as_ref() {
+                if invalid_mode.is_empty() {
+                    eprintln!("[telemt] Missing value for --mode (supported: liveness, ready)");
+                } else {
+                    eprintln!(
+                        "[telemt] Invalid --mode value '{invalid_mode}' (supported: liveness, ready)"
+                    );
+                }
+                Some(2)
+            } else {
+                Some(healthcheck::run(&cmd.config_path, cmd.healthcheck_mode))
+            }
+        }
        Subcommand::Init => {
            if let Some(opts) = cmd.init_opts.clone() {
                match run_init(opts) {
@@ -177,6 +231,20 @@ pub fn execute_subcommand(cmd: &ParsedCommand) -> Option<i32> {
            eprintln!("[telemt] Subcommand not supported on this platform");
            Some(1)
        }
+        Subcommand::Healthcheck => {
+            if let Some(invalid_mode) = cmd.healthcheck_mode_invalid.as_ref() {
+                if invalid_mode.is_empty() {
+                    eprintln!("[telemt] Missing value for --mode (supported: liveness, ready)");
+                } else {
+                    eprintln!(
+                        "[telemt] Invalid --mode value '{invalid_mode}' (supported: liveness, ready)"
+                    );
+                }
+                Some(2)
+            } else {
+                Some(healthcheck::run(&cmd.config_path, cmd.healthcheck_mode))
+            }
+        }
        Subcommand::Init => {
            if let Some(opts) = cmd.init_opts.clone() {
                match run_init(opts) {
@@ -598,16 +666,17 @@ secure = false
 tls = true

 [server]
-port = {port}
 listen_addr_ipv4 = "0.0.0.0"
 listen_addr_ipv6 = "::"

 [[server.listeners]]
 ip = "0.0.0.0"
+port = {port}
 # reuse_allow = false # Set true only when intentionally running multiple telemt instances on same port

 [[server.listeners]]
 ip = "::"
+port = {port}

 [timeouts]
 client_first_byte_idle_secs = 300
@@ -620,6 +689,7 @@ tls_domain = "{domain}"
 mask = true
 mask_port = 443
 fake_cert_len = 2048
+serverhello_compact = false
 tls_full_cert_ttl_secs = 90

 [access]
@@ -21,6 +21,8 @@ const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_PER_CORE: u16 = 64;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_GLOBAL: u32 = 256;
 const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_GLOBAL: u32 = 256;
+const DEFAULT_ME_ROUTE_BACKPRESSURE_ENABLED: bool = false;
+const DEFAULT_ME_ROUTE_FAIRSHARE_ENABLED: bool = false;
 const DEFAULT_ME_WRITER_CMD_CHANNEL_CAPACITY: usize = 4096;
 const DEFAULT_ME_ROUTE_CHANNEL_CAPACITY: usize = 768;
 const DEFAULT_ME_C2ME_CHANNEL_CAPACITY: usize = 1024;
@@ -100,7 +102,7 @@ pub(crate) fn default_fake_cert_len() -> usize {
 }

 pub(crate) fn default_tls_front_dir() -> String {
-    "/etc/telemt/tlsfront".to_string()
+    "tlsfront".to_string()
 }

 pub(crate) fn default_replay_check_len() -> usize {
@@ -529,6 +531,14 @@ pub(crate) fn default_me_route_backpressure_base_timeout_ms() -> u64 {
    25
 }

+pub(crate) fn default_me_route_backpressure_enabled() -> bool {
+    DEFAULT_ME_ROUTE_BACKPRESSURE_ENABLED
+}
+
+pub(crate) fn default_me_route_fairshare_enabled() -> bool {
+    DEFAULT_ME_ROUTE_FAIRSHARE_ENABLED
+}
+
 pub(crate) fn default_me_route_backpressure_high_timeout_ms() -> u64 {
    120
 }
@@ -558,13 +568,17 @@ pub(crate) fn default_beobachten_flush_secs() -> u64 {
 }

 pub(crate) fn default_beobachten_file() -> String {
-    "/etc/telemt/beobachten.txt".to_string()
+    "beobachten.txt".to_string()
 }

 pub(crate) fn default_tls_new_session_tickets() -> u8 {
    0
 }

+pub(crate) fn default_serverhello_compact() -> bool {
+    false
+}
+
 pub(crate) fn default_tls_full_cert_ttl_secs() -> u64 {
    90
 }
@@ -615,6 +629,26 @@ pub(crate) fn default_mask_relay_max_bytes() -> usize {
    32 * 1024
 }

+#[cfg(not(test))]
+pub(crate) fn default_mask_relay_timeout_ms() -> u64 {
+    60_000
+}
+
+#[cfg(test)]
+pub(crate) fn default_mask_relay_timeout_ms() -> u64 {
+    200
+}
+
+#[cfg(not(test))]
+pub(crate) fn default_mask_relay_idle_timeout_ms() -> u64 {
+    5_000
+}
+
+#[cfg(test)]
+pub(crate) fn default_mask_relay_idle_timeout_ms() -> u64 {
+    100
+}
+
 pub(crate) fn default_mask_classifier_prefetch_timeout_ms() -> u64 {
    5
 }
@@ -17,8 +17,9 @@
 //! | `network` | `dns_overrides`                | Applied immediately                            |
 //! | `access`  | All user/quota fields          | Effective immediately                          |
 //!
-//! Fields that require re-binding sockets (`server.port`, `censorship.*`,
-//! `network.*`, `use_middle_proxy`) are **not** applied; a warning is emitted.
+//! Fields that require re-binding sockets (`server.listeners`, legacy
+//! `server.port`, `censorship.*`, `network.*`, `use_middle_proxy`) are **not**
+//! applied; a warning is emitted.
 //! Non-hot changes are never mixed into the runtime config snapshot.

 use std::collections::BTreeSet;
@@ -85,6 +86,8 @@ pub struct HotFields {
    pub telemetry_user_enabled: bool,
    pub telemetry_me_level: MeTelemetryLevel,
    pub me_socks_kdf_policy: MeSocksKdfPolicy,
+    pub me_route_backpressure_enabled: bool,
+    pub me_route_fairshare_enabled: bool,
    pub me_floor_mode: MeFloorMode,
    pub me_adaptive_floor_idle_secs: u64,
    pub me_adaptive_floor_min_writers_single_endpoint: u8,
@@ -120,6 +123,9 @@ pub struct HotFields {
    pub user_max_tcp_conns_global_each: usize,
    pub user_expirations: std::collections::HashMap<String, chrono::DateTime<chrono::Utc>>,
    pub user_data_quota: std::collections::HashMap<String, u64>,
+    pub user_rate_limits: std::collections::HashMap<String, crate::config::RateLimitBps>,
+    pub cidr_rate_limits:
+        std::collections::HashMap<ipnetwork::IpNetwork, crate::config::RateLimitBps>,
    pub user_max_unique_ips: std::collections::HashMap<String, usize>,
    pub user_max_unique_ips_global_each: usize,
    pub user_max_unique_ips_mode: crate::config::UserMaxUniqueIpsMode,
@@ -183,6 +189,8 @@ impl HotFields {
            telemetry_user_enabled: cfg.general.telemetry.user_enabled,
            telemetry_me_level: cfg.general.telemetry.me_level,
            me_socks_kdf_policy: cfg.general.me_socks_kdf_policy,
+            me_route_backpressure_enabled: cfg.general.me_route_backpressure_enabled,
+            me_route_fairshare_enabled: cfg.general.me_route_fairshare_enabled,
            me_floor_mode: cfg.general.me_floor_mode,
            me_adaptive_floor_idle_secs: cfg.general.me_adaptive_floor_idle_secs,
            me_adaptive_floor_min_writers_single_endpoint: cfg
@@ -244,6 +252,8 @@ impl HotFields {
            user_max_tcp_conns_global_each: cfg.access.user_max_tcp_conns_global_each,
            user_expirations: cfg.access.user_expirations.clone(),
            user_data_quota: cfg.access.user_data_quota.clone(),
+            user_rate_limits: cfg.access.user_rate_limits.clone(),
+            cidr_rate_limits: cfg.access.cidr_rate_limits.clone(),
            user_max_unique_ips: cfg.access.user_max_unique_ips.clone(),
            user_max_unique_ips_global_each: cfg.access.user_max_unique_ips_global_each,
            user_max_unique_ips_mode: cfg.access.user_max_unique_ips_mode,
@@ -299,6 +309,7 @@ fn listeners_equal(
    }
    lhs.iter().zip(rhs.iter()).all(|(a, b)| {
        a.ip == b.ip
+            && a.port == b.port
            && a.announce == b.announce
            && a.announce_ip == b.announce_ip
            && a.proxy_protocol == b.proxy_protocol
@@ -306,6 +317,14 @@ fn listeners_equal(
    })
 }

+fn resolve_default_link_port(cfg: &ProxyConfig) -> u16 {
+    cfg.server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(cfg.server.port)
+}
+
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 struct WatchManifest {
    files: BTreeSet<PathBuf>,
@@ -514,6 +533,8 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
        new.general.me_route_backpressure_high_timeout_ms;
    cfg.general.me_route_backpressure_high_watermark_pct =
        new.general.me_route_backpressure_high_watermark_pct;
+    cfg.general.me_route_backpressure_enabled = new.general.me_route_backpressure_enabled;
+    cfg.general.me_route_fairshare_enabled = new.general.me_route_fairshare_enabled;
    cfg.general.me_reader_route_data_wait_ms = new.general.me_reader_route_data_wait_ms;
    cfg.general.me_d2c_flush_batch_max_frames = new.general.me_d2c_flush_batch_max_frames;
    cfg.general.me_d2c_flush_batch_max_bytes = new.general.me_d2c_flush_batch_max_bytes;
@@ -535,6 +556,8 @@ fn overlay_hot_fields(old: &ProxyConfig, new: &ProxyConfig) -> ProxyConfig {
    cfg.access.user_max_tcp_conns_global_each = new.access.user_max_tcp_conns_global_each;
    cfg.access.user_expirations = new.access.user_expirations.clone();
    cfg.access.user_data_quota = new.access.user_data_quota.clone();
+    cfg.access.user_rate_limits = new.access.user_rate_limits.clone();
+    cfg.access.cidr_rate_limits = new.access.cidr_rate_limits.clone();
    cfg.access.user_max_unique_ips = new.access.user_max_unique_ips.clone();
    cfg.access.user_max_unique_ips_global_each = new.access.user_max_unique_ips_global_each;
    cfg.access.user_max_unique_ips_mode = new.access.user_max_unique_ips_mode;
@@ -560,6 +583,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
    if old.server.api.enabled != new.server.api.enabled
        || old.server.api.listen != new.server.api.listen
        || old.server.api.whitelist != new.server.api.whitelist
+        || old.server.api.gray_action != new.server.api.gray_action
        || old.server.api.auth_header != new.server.api.auth_header
        || old.server.api.request_body_limit_bytes != new.server.api.request_body_limit_bytes
        || old.server.api.minimal_runtime_enabled != new.server.api.minimal_runtime_enabled
@@ -593,6 +617,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
        || old.censorship.mask != new.censorship.mask
        || old.censorship.mask_host != new.censorship.mask_host
        || old.censorship.mask_port != new.censorship.mask_port
+        || old.censorship.exclusive_mask != new.censorship.exclusive_mask
        || old.censorship.mask_unix_sock != new.censorship.mask_unix_sock
        || old.censorship.fake_cert_len != new.censorship.fake_cert_len
        || old.censorship.tls_emulation != new.censorship.tls_emulation
@@ -600,6 +625,7 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
        || old.censorship.server_hello_delay_min_ms != new.censorship.server_hello_delay_min_ms
        || old.censorship.server_hello_delay_max_ms != new.censorship.server_hello_delay_max_ms
        || old.censorship.tls_new_session_tickets != new.censorship.tls_new_session_tickets
+        || old.censorship.serverhello_compact != new.censorship.serverhello_compact
        || old.censorship.tls_full_cert_ttl_secs != new.censorship.tls_full_cert_ttl_secs
        || old.censorship.alpn_enforce != new.censorship.alpn_enforce
        || old.censorship.mask_proxy_protocol != new.censorship.mask_proxy_protocol
@@ -611,6 +637,8 @@ fn warn_non_hot_changes(old: &ProxyConfig, new: &ProxyConfig, non_hot_changed: b
        || old.censorship.mask_shape_above_cap_blur_max_bytes
            != new.censorship.mask_shape_above_cap_blur_max_bytes
        || old.censorship.mask_relay_max_bytes != new.censorship.mask_relay_max_bytes
+        || old.censorship.mask_relay_timeout_ms != new.censorship.mask_relay_timeout_ms
+        || old.censorship.mask_relay_idle_timeout_ms != new.censorship.mask_relay_idle_timeout_ms
        || old.censorship.mask_classifier_prefetch_timeout_ms
            != new.censorship.mask_classifier_prefetch_timeout_ms
        || old.censorship.mask_timing_normalization_enabled
@@ -1033,6 +1061,8 @@ fn log_changes(
            != new_hot.me_route_backpressure_high_timeout_ms
        || old_hot.me_route_backpressure_high_watermark_pct
            != new_hot.me_route_backpressure_high_watermark_pct
+        || old_hot.me_route_backpressure_enabled != new_hot.me_route_backpressure_enabled
+        || old_hot.me_route_fairshare_enabled != new_hot.me_route_fairshare_enabled
        || old_hot.me_reader_route_data_wait_ms != new_hot.me_reader_route_data_wait_ms
        || old_hot.me_health_interval_ms_unhealthy != new_hot.me_health_interval_ms_unhealthy
        || old_hot.me_health_interval_ms_healthy != new_hot.me_health_interval_ms_healthy
@@ -1040,10 +1070,12 @@ fn log_changes(
        || old_hot.me_warn_rate_limit_ms != new_hot.me_warn_rate_limit_ms
    {
        info!(
-            "config reload: me_route_backpressure: base={}ms high={}ms watermark={}%; me_reader_route_data_wait_ms={}; me_health_interval: unhealthy={}ms healthy={}ms; me_admission_poll={}ms; me_warn_rate_limit={}ms",
+            "config reload: me_route_backpressure: enabled={} base={}ms high={}ms watermark={}%; me_route_fairshare_enabled={}; me_reader_route_data_wait_ms={}; me_health_interval: unhealthy={}ms healthy={}ms; me_admission_poll={}ms; me_warn_rate_limit={}ms",
+            new_hot.me_route_backpressure_enabled,
            new_hot.me_route_backpressure_base_timeout_ms,
            new_hot.me_route_backpressure_high_timeout_ms,
            new_hot.me_route_backpressure_high_watermark_pct,
+            new_hot.me_route_fairshare_enabled,
            new_hot.me_reader_route_data_wait_ms,
            new_hot.me_health_interval_ms_unhealthy,
            new_hot.me_health_interval_ms_healthy,
@@ -1117,7 +1149,7 @@ fn log_changes(
                .general
                .links
                .public_port
-                .unwrap_or(new_cfg.server.port);
+                .unwrap_or(resolve_default_link_port(new_cfg));
            for user in &added {
                if let Some(secret) = new_hot.users.get(*user) {
                    print_user_links(user, secret, &host, port, new_cfg);
@@ -1170,6 +1202,18 @@ fn log_changes(
            new_hot.user_data_quota.len()
        );
    }
+    if old_hot.user_rate_limits != new_hot.user_rate_limits {
+        info!(
+            "config reload: user_rate_limits updated ({} entries)",
+            new_hot.user_rate_limits.len()
+        );
+    }
+    if old_hot.cidr_rate_limits != new_hot.cidr_rate_limits {
+        info!(
+            "config reload: cidr_rate_limits updated ({} entries)",
+            new_hot.cidr_rate_limits.len()
+        );
+    }
    if old_hot.user_max_unique_ips != new_hot.user_max_unique_ips {
        info!(
            "config reload: user_max_unique_ips updated ({} entries)",
@@ -238,7 +238,7 @@ mask_shape_above_cap_blur_max_bytes = 8
 }

 #[test]
-fn load_rejects_zero_mask_relay_max_bytes() {
+fn load_accepts_zero_mask_relay_max_bytes_as_unlimited() {
    let path = write_temp_config(
        r#"
 [censorship]
@@ -246,12 +246,9 @@ mask_relay_max_bytes = 0
 "#,
    );

-    let err = ProxyConfig::load(&path).expect_err("mask_relay_max_bytes must be > 0");
-    let msg = err.to_string();
-    assert!(
-        msg.contains("censorship.mask_relay_max_bytes must be > 0"),
-        "error must explain non-zero relay cap invariant, got: {msg}"
-    );
+    let cfg = ProxyConfig::load(&path)
+        .expect("mask_relay_max_bytes=0 must be accepted as unlimited relay cap");
+    assert_eq!(cfg.censorship.mask_relay_max_bytes, 0);

    remove_temp_config(&path);
 }
@@ -21,11 +21,14 @@ pub enum LogLevel {
    #[default]
    Normal,
    /// Minimal output: only warnings and errors (warn + error).
-    /// Startup messages (config, DC connectivity, proxy links) are always shown
-    /// via info! before the filter is applied.
+    /// Proxy links may still be emitted through their dedicated target.
    Silent,
 }

+fn default_quota_state_path() -> PathBuf {
+    PathBuf::from("telemt.limit.json")
+}
+
 impl LogLevel {
    /// Convert to tracing EnvFilter directive string.
    pub fn to_filter_str(&self) -> &'static str {
@@ -375,6 +378,15 @@ pub struct GeneralConfig {
    #[serde(default)]
    pub data_path: Option<PathBuf>,

+    /// JSON state file for runtime per-user quota consumption.
+    #[serde(default = "default_quota_state_path")]
+    pub quota_state_path: PathBuf,
+
+    /// Reject unknown TOML config keys during load.
+    /// Startup fails fast; hot-reload rejects the new snapshot and keeps the current config.
+    #[serde(default)]
+    pub config_strict: bool,
+
    #[serde(default)]
    pub modes: ProxyModes,

@@ -392,14 +404,26 @@ pub struct GeneralConfig {
    #[serde(default = "default_proxy_secret_path")]
    pub proxy_secret_path: Option<String>,

+    /// Optional custom URL for infrastructure secret (https://core.telegram.org/getProxySecret if absent).
+    #[serde(default)]
+    pub proxy_secret_url: Option<String>,
+
    /// Optional path to cache raw getProxyConfig (IPv4) snapshot for startup fallback.
    #[serde(default = "default_proxy_config_v4_cache_path")]
    pub proxy_config_v4_cache_path: Option<String>,

+    /// Optional custom URL for getProxyConfig (https://core.telegram.org/getProxyConfig if absent).
+    #[serde(default)]
+    pub proxy_config_v4_url: Option<String>,
+
    /// Optional path to cache raw getProxyConfigV6 snapshot for startup fallback.
    #[serde(default = "default_proxy_config_v6_cache_path")]
    pub proxy_config_v6_cache_path: Option<String>,

+    /// Optional custom URL for getProxyConfigV6 (https://core.telegram.org/getProxyConfigV6 if absent).
+    #[serde(default)]
+    pub proxy_config_v6_url: Option<String>,
+
    /// Global ad_tag (32 hex chars from @MTProxybot). Fallback when user has no per-user tag in access.user_ad_tags.
    #[serde(default)]
    pub ad_tag: Option<String>,
@@ -518,10 +542,17 @@ pub struct GeneralConfig {
    pub me_d2c_frame_buf_shrink_threshold_bytes: usize,

    /// Copy buffer size for client->DC direction in direct relay.
+    ///
+    /// This is also the upper bound for one amortized upload rate-limit burst:
+    /// upload debt is settled before the next relay read instead of blocking
+    /// inside the completed read path.
    #[serde(default = "default_direct_relay_copy_buf_c2s_bytes")]
    pub direct_relay_copy_buf_c2s_bytes: usize,

    /// Copy buffer size for DC->client direction in direct relay.
+    ///
+    /// This bounds one direct download rate-limit grant because writes are
+    /// clipped to the currently available shaper budget.
    #[serde(default = "default_direct_relay_copy_buf_s2c_bytes")]
    pub direct_relay_copy_buf_s2c_bytes: usize,

@@ -717,6 +748,14 @@ pub struct GeneralConfig {
    #[serde(default)]
    pub me_socks_kdf_policy: MeSocksKdfPolicy,

+    /// Enable route-level ME backpressure controls in reader fairness path.
+    #[serde(default = "default_me_route_backpressure_enabled")]
+    pub me_route_backpressure_enabled: bool,
+
+    /// Enable worker-local fairshare scheduler for ME reader routing.
+    #[serde(default = "default_me_route_fairshare_enabled")]
+    pub me_route_fairshare_enabled: bool,
+
    /// Base backpressure timeout in milliseconds for ME route channel send.
    #[serde(default = "default_me_route_backpressure_base_timeout_ms")]
    pub me_route_backpressure_base_timeout_ms: u64,
@@ -758,7 +797,7 @@ pub struct GeneralConfig {
    pub me_route_hybrid_max_wait_ms: u64,

    /// Maximum wait in milliseconds for blocking ME writer channel send fallback.
-    /// `0` keeps legacy unbounded wait behavior.
+    /// Must be within [1, 5000].
    #[serde(default = "default_me_route_blocking_send_timeout_ms")]
    pub me_route_blocking_send_timeout_ms: u64,

@@ -954,14 +993,19 @@ impl Default for GeneralConfig {
    fn default() -> Self {
        Self {
            data_path: None,
+            quota_state_path: default_quota_state_path(),
+            config_strict: false,
            modes: ProxyModes::default(),
            prefer_ipv6: false,
            fast_mode: default_true(),
            use_middle_proxy: default_true(),
            ad_tag: None,
            proxy_secret_path: default_proxy_secret_path(),
+            proxy_secret_url: None,
            proxy_config_v4_cache_path: default_proxy_config_v4_cache_path(),
+            proxy_config_v4_url: None,
            proxy_config_v6_cache_path: default_proxy_config_v6_cache_path(),
+            proxy_config_v6_url: None,
            middle_proxy_nat_ip: None,
            middle_proxy_nat_probe: default_true(),
            middle_proxy_nat_stun: default_middle_proxy_nat_stun(),
@@ -1044,6 +1088,8 @@ impl Default for GeneralConfig {
            disable_colors: false,
            telemetry: TelemetryConfig::default(),
            me_socks_kdf_policy: MeSocksKdfPolicy::Strict,
+            me_route_backpressure_enabled: default_me_route_backpressure_enabled(),
+            me_route_fairshare_enabled: default_me_route_fairshare_enabled(),
            me_route_backpressure_base_timeout_ms: default_me_route_backpressure_base_timeout_ms(),
            me_route_backpressure_high_timeout_ms: default_me_route_backpressure_high_timeout_ms(),
            me_route_backpressure_high_watermark_pct:
@@ -1153,7 +1199,8 @@ pub struct LinksConfig {
    #[serde(default)]
    pub public_host: Option<String>,

-    /// Public port for tg:// link generation (overrides server.port).
+    /// Public port for tg:// link generation.
+    /// Overrides listener ports and legacy `server.port`.
    #[serde(default)]
    pub public_port: Option<u16>,
 }
@@ -1183,6 +1230,13 @@ pub struct ApiConfig {
    #[serde(default = "default_api_whitelist")]
    pub whitelist: Vec<IpNetwork>,

+    /// Behavior for requests from source IPs outside `whitelist`.
+    /// - `api`: return structured API forbidden response.
+    /// - `200`: return `200 OK` with an empty body.
+    /// - `drop`: close the connection without HTTP response.
+    #[serde(default)]
+    pub gray_action: ApiGrayAction,
+
    /// Optional static value for `Authorization` header validation.
    /// Empty string disables header auth.
    #[serde(default)]
@@ -1227,6 +1281,7 @@ impl Default for ApiConfig {
            enabled: default_true(),
            listen: default_api_listen(),
            whitelist: default_api_whitelist(),
+            gray_action: ApiGrayAction::default(),
            auth_header: String::new(),
            request_body_limit_bytes: default_api_request_body_limit_bytes(),
            minimal_runtime_enabled: default_api_minimal_runtime_enabled(),
@@ -1240,6 +1295,19 @@ impl Default for ApiConfig {
    }
 }

+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum ApiGrayAction {
+    /// Preserve current API behavior for denied source IPs.
+    Api,
+    /// Mimic a plain web endpoint by returning `200 OK` with an empty body.
+    #[serde(rename = "200")]
+    Ok200,
+    /// Drop connection without HTTP response for denied source IPs.
+    #[default]
+    Drop,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(rename_all = "lowercase")]
 pub enum ConntrackMode {
@@ -1307,6 +1375,10 @@ pub struct ConntrackControlConfig {
    #[serde(default = "default_conntrack_control_enabled")]
    pub inline_conntrack_control: bool,

+    /// Tracks whether inline_conntrack_control was explicitly set in config.
+    #[serde(skip)]
+    pub inline_conntrack_control_explicit: bool,
+
    /// Conntrack mode for listener ingress traffic.
    #[serde(default)]
    pub mode: ConntrackMode,
@@ -1341,6 +1413,7 @@ impl Default for ConntrackControlConfig {
    fn default() -> Self {
        Self {
            inline_conntrack_control: default_conntrack_control_enabled(),
+            inline_conntrack_control_explicit: false,
            mode: ConntrackMode::default(),
            backend: ConntrackBackend::default(),
            profile: ConntrackPressureProfile::default(),
@@ -1354,6 +1427,8 @@ impl Default for ConntrackControlConfig {

 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ServerConfig {
+    /// Legacy listener port used for backward compatibility.
+    /// For new configs prefer `[[server.listeners]].port`.
    #[serde(default = "default_port")]
    pub port: u16,

@@ -1527,6 +1602,13 @@ pub enum UnknownSniAction {
    Drop,
    Mask,
    Accept,
+    /// Reject the TLS handshake by sending a fatal `unrecognized_name` alert
+    /// (RFC 6066, AlertDescription = 112) before closing the connection.
+    /// Mimics nginx `ssl_reject_handshake on;` behavior on the default vhost —
+    /// the wire response indistinguishable from a stock modern web server
+    /// that simply does not host the requested name.
+    #[serde(rename = "reject_handshake")]
+    RejectHandshake,
 }

 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
@@ -1605,6 +1687,14 @@ impl Default for TlsFetchConfig {
    }
 }

+#[derive(Debug, Clone)]
+pub struct ExclusiveMaskTarget {
+    /// Target host after IDNA/IP normalization.
+    pub host: String,
+    /// TCP port for the selected target.
+    pub port: u16,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AntiCensorshipConfig {
    #[serde(default = "default_tls_domain")]
@@ -1636,6 +1726,14 @@ pub struct AntiCensorshipConfig {
    #[serde(default = "default_mask_port")]
    pub mask_port: u16,

+    /// Per-SNI TCP mask targets. Keys are SNI domains, values are `host:port`.
+    #[serde(default)]
+    pub exclusive_mask: HashMap<String, String>,
+
+    /// Parsed runtime cache for per-SNI TCP mask targets.
+    #[serde(skip)]
+    pub exclusive_mask_targets: HashMap<String, ExclusiveMaskTarget>,
+
    #[serde(default)]
    pub mask_unix_sock: Option<String>,

@@ -1662,9 +1760,16 @@ pub struct AntiCensorshipConfig {
    #[serde(default = "default_tls_new_session_tickets")]
    pub tls_new_session_tickets: u8,

+    /// Enable compact ServerHello payload mode.
+    /// When false, FakeTLS always uses full ServerHello payload behavior.
+    /// When true, compact certificate payload mode can be used by TTL policy.
+    #[serde(default = "default_serverhello_compact")]
+    pub serverhello_compact: bool,
+
    /// TTL in seconds for sending full certificate payload per client IP.
    /// First client connection per (SNI domain, client IP) gets full cert payload.
    /// Subsequent handshakes within TTL use compact cert metadata payload.
+    /// Applied only when `serverhello_compact` is enabled.
    #[serde(default = "default_tls_full_cert_ttl_secs")]
    pub tls_full_cert_ttl_secs: u64,

@@ -1707,9 +1812,23 @@ pub struct AntiCensorshipConfig {
    pub mask_shape_above_cap_blur_max_bytes: usize,

    /// Maximum bytes relayed per direction on unauthenticated masking fallback paths.
+    /// Set to 0 to disable byte cap (unlimited within relay/idle timeouts).
    #[serde(default = "default_mask_relay_max_bytes")]
    pub mask_relay_max_bytes: usize,

+    /// Wall-clock cap for the full masking relay on non-MTProto fallback paths.
+    /// Raise when the mask target is a long-lived service (e.g. WebSocket).
+    /// Default: 60 000 ms (60 s).
+    #[serde(default = "default_mask_relay_timeout_ms")]
+    pub mask_relay_timeout_ms: u64,
+
+    /// Per-read idle timeout on masking relay and drain paths.
+    /// Limits resource consumption by slow-loris attacks and port scanners.
+    /// A read call stalling beyond this is treated as an abandoned connection.
+    /// Default: 5 000 ms (5 s).
+    #[serde(default = "default_mask_relay_idle_timeout_ms")]
+    pub mask_relay_idle_timeout_ms: u64,
+
    /// Prefetch timeout (ms) for extending fragmented masking classifier window.
    #[serde(default = "default_mask_classifier_prefetch_timeout_ms")]
    pub mask_classifier_prefetch_timeout_ms: u64,
@@ -1738,6 +1857,8 @@ impl Default for AntiCensorshipConfig {
            mask: default_true(),
            mask_host: None,
            mask_port: default_mask_port(),
+            exclusive_mask: HashMap::new(),
+            exclusive_mask_targets: HashMap::new(),
            mask_unix_sock: None,
            fake_cert_len: default_fake_cert_len(),
            tls_emulation: true,
@@ -1745,6 +1866,7 @@ impl Default for AntiCensorshipConfig {
            server_hello_delay_min_ms: default_server_hello_delay_min_ms(),
            server_hello_delay_max_ms: default_server_hello_delay_max_ms(),
            tls_new_session_tickets: default_tls_new_session_tickets(),
+            serverhello_compact: default_serverhello_compact(),
            tls_full_cert_ttl_secs: default_tls_full_cert_ttl_secs(),
            alpn_enforce: default_alpn_enforce(),
            mask_proxy_protocol: 0,
@@ -1755,6 +1877,8 @@ impl Default for AntiCensorshipConfig {
            mask_shape_above_cap_blur: default_mask_shape_above_cap_blur(),
            mask_shape_above_cap_blur_max_bytes: default_mask_shape_above_cap_blur_max_bytes(),
            mask_relay_max_bytes: default_mask_relay_max_bytes(),
+            mask_relay_timeout_ms: default_mask_relay_timeout_ms(),
+            mask_relay_idle_timeout_ms: default_mask_relay_idle_timeout_ms(),
            mask_classifier_prefetch_timeout_ms: default_mask_classifier_prefetch_timeout_ms(),
            mask_timing_normalization_enabled: default_mask_timing_normalization_enabled(),
            mask_timing_normalization_floor_ms: default_mask_timing_normalization_floor_ms(),
@@ -1787,6 +1911,30 @@ pub struct AccessConfig {
    #[serde(default)]
    pub user_data_quota: HashMap<String, u64>,

+    /// Per-user transport rate limits in bits-per-second.
+    ///
+    /// Each entry supports independent upload (`up_bps`) and download
+    /// (`down_bps`) ceilings. A value of `0` in one direction means
+    /// "unlimited" for that direction. Limits are amortized: a relay quantum
+    /// may pass as a bounded burst, and the limiter applies the resulting wait
+    /// before later traffic in the same direction proceeds.
+    #[serde(default)]
+    pub user_rate_limits: HashMap<String, RateLimitBps>,
+
+    /// Per-CIDR aggregate transport rate limits in bits-per-second.
+    ///
+    /// Matching uses longest-prefix-wins semantics. A value of `0` in one
+    /// direction means "unlimited" for that direction. Limits are amortized
+    /// with the same bounded-burst contract as per-user rate limits.
+    #[serde(default)]
+    pub cidr_rate_limits: HashMap<IpNetwork, RateLimitBps>,
+
+    /// Per-username client source IP/CIDR deny list. Checked after successful
+    /// authentication; matching IPs get the same rejection path as invalid auth
+    /// (handshake fails closed for that connection).
+    #[serde(default)]
+    pub user_source_deny: HashMap<String, Vec<IpNetwork>>,
+
    #[serde(default)]
    pub user_max_unique_ips: HashMap<String, usize>,

@@ -1820,6 +1968,9 @@ impl Default for AccessConfig {
            user_max_tcp_conns_global_each: default_user_max_tcp_conns_global_each(),
            user_expirations: HashMap::new(),
            user_data_quota: HashMap::new(),
+            user_rate_limits: HashMap::new(),
+            cidr_rate_limits: HashMap::new(),
+            user_source_deny: HashMap::new(),
            user_max_unique_ips: HashMap::new(),
            user_max_unique_ips_global_each: default_user_max_unique_ips_global_each(),
            user_max_unique_ips_mode: UserMaxUniqueIpsMode::default(),
@@ -1831,6 +1982,23 @@ impl Default for AccessConfig {
    }
 }

+impl AccessConfig {
+    /// Returns true if `ip` is contained in any CIDR listed for `username` under `user_source_deny`.
+    pub fn is_user_source_ip_denied(&self, username: &str, ip: IpAddr) -> bool {
+        self.user_source_deny
+            .get(username)
+            .is_some_and(|nets| nets.iter().any(|n| n.contains(ip)))
+    }
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct RateLimitBps {
+    #[serde(default)]
+    pub up_bps: u64,
+    #[serde(default)]
+    pub down_bps: u64,
+}
+
 // ============= Aux Structures =============

 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
@@ -1841,6 +2009,10 @@ pub enum UpstreamType {
        interface: Option<String>,
        #[serde(default)]
        bind_addresses: Option<Vec<String>>,
+        /// Linux-only hard interface pinning via `SO_BINDTODEVICE`.
+        /// Optional alias: `force_bind`.
+        #[serde(default, alias = "force_bind")]
+        bindtodevice: Option<String>,
    },
    Socks4 {
        address: String,
@@ -1877,11 +2049,22 @@ pub struct UpstreamConfig {
    pub scopes: String,
    #[serde(skip)]
    pub selected_scope: String,
+    /// Allow IPv4 DC targets for this upstream.
+    /// `None` means auto-detect from runtime connectivity state.
+    #[serde(default)]
+    pub ipv4: Option<bool>,
+    /// Allow IPv6 DC targets for this upstream.
+    /// `None` means auto-detect from runtime connectivity state.
+    #[serde(default)]
+    pub ipv6: Option<bool>,
 }

 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ListenerConfig {
    pub ip: IpAddr,
+    /// Per-listener TCP port. If omitted, falls back to legacy `server.port`.
+    #[serde(default)]
+    pub port: Option<u16>,
    /// IP address or hostname to announce in proxy links.
    /// Takes precedence over `announce_ip` if both are set.
    #[serde(default)]
@@ -24,6 +24,13 @@ enum NetfilterBackend {
    Iptables,
 }

+#[derive(Clone, Copy)]
+struct ConntrackRuntimeSupport {
+    netfilter_backend: Option<NetfilterBackend>,
+    has_cap_net_admin: bool,
+    has_conntrack_binary: bool,
+}
+
 #[derive(Clone, Copy)]
 struct PressureSample {
    conn_pct: Option<u8>,
@@ -56,11 +63,8 @@ pub(crate) fn spawn_conntrack_controller(
    shared: Arc<ProxySharedState>,
 ) {
    if !cfg!(target_os = "linux") {
-        let enabled = config_rx
-            .borrow()
-            .server
-            .conntrack_control
-            .inline_conntrack_control;
+        let cfg = config_rx.borrow();
+        let enabled = cfg.server.conntrack_control.inline_conntrack_control;
        stats.set_conntrack_control_enabled(enabled);
        stats.set_conntrack_control_available(false);
        stats.set_conntrack_pressure_active(false);
@@ -68,9 +72,14 @@ pub(crate) fn spawn_conntrack_controller(
        stats.set_conntrack_rule_apply_ok(false);
        shared.disable_conntrack_close_sender();
        shared.set_conntrack_pressure_active(false);
-        if enabled {
+        if enabled
+            && cfg
+                .server
+                .conntrack_control
+                .inline_conntrack_control_explicit
+        {
            warn!(
-                "conntrack control is configured but unsupported on this OS; disabling runtime worker"
+                "conntrack control explicitly enabled but unsupported on this OS; disabling runtime worker"
            );
        }
        return;
@@ -92,16 +101,17 @@ async fn run_conntrack_controller(
    let mut cfg = config_rx.borrow().clone();
    let mut pressure_state = PressureState::new(stats.as_ref());
    let mut delete_budget_tokens = cfg.server.conntrack_control.delete_budget_per_sec;
-    let mut backend = pick_backend(cfg.server.conntrack_control.backend);
+    let mut runtime_support = probe_runtime_support(cfg.server.conntrack_control.backend);
+    let mut effective_enabled = effective_conntrack_enabled(&cfg, runtime_support);

    apply_runtime_state(
        stats.as_ref(),
        shared.as_ref(),
        &cfg,
-        backend.is_some(),
+        runtime_support,
        false,
    );
-    reconcile_rules(&cfg, backend, stats.as_ref()).await;
+    reconcile_rules(&cfg, runtime_support, stats.as_ref()).await;

    loop {
        tokio::select! {
@@ -110,17 +120,18 @@ async fn run_conntrack_controller(
                    break;
                }
                cfg = config_rx.borrow_and_update().clone();
-                backend = pick_backend(cfg.server.conntrack_control.backend);
+                runtime_support = probe_runtime_support(cfg.server.conntrack_control.backend);
+                effective_enabled = effective_conntrack_enabled(&cfg, runtime_support);
                delete_budget_tokens = cfg.server.conntrack_control.delete_budget_per_sec;
-                apply_runtime_state(stats.as_ref(), shared.as_ref(), &cfg, backend.is_some(), pressure_state.active);
-                reconcile_rules(&cfg, backend, stats.as_ref()).await;
+                apply_runtime_state(stats.as_ref(), shared.as_ref(), &cfg, runtime_support, pressure_state.active);
+                reconcile_rules(&cfg, runtime_support, stats.as_ref()).await;
            }
            event = close_rx.recv() => {
                let Some(event) = event else {
                    break;
                };
                stats.set_conntrack_event_queue_depth(close_rx.len() as u64);
-                if !cfg.server.conntrack_control.inline_conntrack_control {
+                if !effective_enabled {
                    continue;
                }
                if !pressure_state.active {
@@ -156,6 +167,7 @@ async fn run_conntrack_controller(
                    stats.as_ref(),
                    shared.as_ref(),
                    &cfg,
+                    effective_enabled,
                    &sample,
                    &mut pressure_state,
                );
@@ -175,20 +187,30 @@ fn apply_runtime_state(
    stats: &Stats,
    shared: &ProxySharedState,
    cfg: &ProxyConfig,
-    backend_available: bool,
+    runtime_support: ConntrackRuntimeSupport,
    pressure_active: bool,
 ) {
    let enabled = cfg.server.conntrack_control.inline_conntrack_control;
-    let available = enabled && backend_available && has_cap_net_admin();
-    if enabled && !available {
+    let available = effective_conntrack_enabled(cfg, runtime_support);
+    if enabled
+        && !available
+        && cfg
+            .server
+            .conntrack_control
+            .inline_conntrack_control_explicit
+    {
        warn!(
-            "conntrack control enabled but unavailable (missing CAP_NET_ADMIN or backend binaries)"
+            has_cap_net_admin = runtime_support.has_cap_net_admin,
+            backend_available = runtime_support.netfilter_backend.is_some(),
+            conntrack_binary_available = runtime_support.has_conntrack_binary,
+            configured_backend = ?cfg.server.conntrack_control.backend,
+            "conntrack control explicitly enabled but unavailable; disabling runtime features"
        );
    }
    stats.set_conntrack_control_enabled(enabled);
    stats.set_conntrack_control_available(available);
-    shared.set_conntrack_pressure_active(enabled && pressure_active);
-    stats.set_conntrack_pressure_active(enabled && pressure_active);
+    shared.set_conntrack_pressure_active(available && pressure_active);
+    stats.set_conntrack_pressure_active(available && pressure_active);
 }

 fn collect_pressure_sample(
@@ -228,10 +250,11 @@ fn update_pressure_state(
    stats: &Stats,
    shared: &ProxySharedState,
    cfg: &ProxyConfig,
+    effective_enabled: bool,
    sample: &PressureSample,
    state: &mut PressureState,
 ) {
-    if !cfg.server.conntrack_control.inline_conntrack_control {
+    if !effective_enabled {
        if state.active {
            state.active = false;
            state.low_streak = 0;
@@ -285,22 +308,26 @@ fn update_pressure_state(
    state.low_streak = 0;
 }

-async fn reconcile_rules(cfg: &ProxyConfig, backend: Option<NetfilterBackend>, stats: &Stats) {
+async fn reconcile_rules(
+    cfg: &ProxyConfig,
+    runtime_support: ConntrackRuntimeSupport,
+    stats: &Stats,
+) {
    if !cfg.server.conntrack_control.inline_conntrack_control {
        clear_notrack_rules_all_backends().await;
        stats.set_conntrack_rule_apply_ok(true);
        return;
    }

-    if !has_cap_net_admin() {
+    if !effective_conntrack_enabled(cfg, runtime_support) {
+        clear_notrack_rules_all_backends().await;
        stats.set_conntrack_rule_apply_ok(false);
        return;
    }

-    let Some(backend) = backend else {
-        stats.set_conntrack_rule_apply_ok(false);
-        return;
-    };
+    let backend = runtime_support
+        .netfilter_backend
+        .expect("netfilter backend must be available for effective conntrack control");

    let apply_result = match backend {
        NetfilterBackend::Nftables => apply_nft_rules(cfg).await,
@@ -315,6 +342,24 @@ async fn reconcile_rules(cfg: &ProxyConfig, backend: Option<NetfilterBackend>, s
    }
 }

+fn probe_runtime_support(configured_backend: ConntrackBackend) -> ConntrackRuntimeSupport {
+    ConntrackRuntimeSupport {
+        netfilter_backend: pick_backend(configured_backend),
+        has_cap_net_admin: has_cap_net_admin(),
+        has_conntrack_binary: command_exists("conntrack"),
+    }
+}
+
+fn effective_conntrack_enabled(
+    cfg: &ProxyConfig,
+    runtime_support: ConntrackRuntimeSupport,
+) -> bool {
+    cfg.server.conntrack_control.inline_conntrack_control
+        && runtime_support.has_cap_net_admin
+        && runtime_support.netfilter_backend.is_some()
+        && runtime_support.has_conntrack_binary
+}
+
 fn pick_backend(configured: ConntrackBackend) -> Option<NetfilterBackend> {
    match configured {
        ConntrackBackend::Auto => {
@@ -343,15 +388,28 @@ fn command_exists(binary: &str) -> bool {
    })
 }

-fn notrack_targets(cfg: &ProxyConfig) -> (Vec<Option<IpAddr>>, Vec<Option<IpAddr>>) {
+fn listener_port_set(cfg: &ProxyConfig) -> Vec<u16> {
+    let mut ports: BTreeSet<u16> = BTreeSet::new();
+    if cfg.server.listeners.is_empty() {
+        ports.insert(cfg.server.port);
+    } else {
+        for listener in &cfg.server.listeners {
+            ports.insert(listener.port.unwrap_or(cfg.server.port));
+        }
+    }
+    ports.into_iter().collect()
+}
+
+fn notrack_targets(cfg: &ProxyConfig) -> (Vec<(Option<IpAddr>, u16)>, Vec<(Option<IpAddr>, u16)>) {
    let mode = cfg.server.conntrack_control.mode;
-    let mut v4_targets: BTreeSet<Option<IpAddr>> = BTreeSet::new();
-    let mut v6_targets: BTreeSet<Option<IpAddr>> = BTreeSet::new();
+    let mut v4_targets: BTreeSet<(Option<IpAddr>, u16)> = BTreeSet::new();
+    let mut v6_targets: BTreeSet<(Option<IpAddr>, u16)> = BTreeSet::new();

    match mode {
        ConntrackMode::Tracked => {}
        ConntrackMode::Notrack => {
            if cfg.server.listeners.is_empty() {
+                let port = cfg.server.port;
                if let Some(ipv4) = cfg
                    .server
                    .listen_addr_ipv4
@@ -359,9 +417,9 @@ fn notrack_targets(cfg: &ProxyConfig) -> (Vec<Option<IpAddr>>, Vec<Option<IpAddr
                    .and_then(|s| s.parse::<IpAddr>().ok())
                {
                    if ipv4.is_unspecified() {
-                        v4_targets.insert(None);
+                        v4_targets.insert((None, port));
                    } else {
-                        v4_targets.insert(Some(ipv4));
+                        v4_targets.insert((Some(ipv4), port));
                    }
                }
                if let Some(ipv6) = cfg
@@ -371,33 +429,39 @@ fn notrack_targets(cfg: &ProxyConfig) -> (Vec<Option<IpAddr>>, Vec<Option<IpAddr
                    .and_then(|s| s.parse::<IpAddr>().ok())
                {
                    if ipv6.is_unspecified() {
-                        v6_targets.insert(None);
+                        v6_targets.insert((None, port));
                    } else {
-                        v6_targets.insert(Some(ipv6));
+                        v6_targets.insert((Some(ipv6), port));
                    }
                }
            } else {
                for listener in &cfg.server.listeners {
+                    let port = listener.port.unwrap_or(cfg.server.port);
                    if listener.ip.is_ipv4() {
                        if listener.ip.is_unspecified() {
-                            v4_targets.insert(None);
+                            v4_targets.insert((None, port));
                        } else {
-                            v4_targets.insert(Some(listener.ip));
+                            v4_targets.insert((Some(listener.ip), port));
                        }
                    } else if listener.ip.is_unspecified() {
-                        v6_targets.insert(None);
+                        v6_targets.insert((None, port));
                    } else {
-                        v6_targets.insert(Some(listener.ip));
+                        v6_targets.insert((Some(listener.ip), port));
                    }
                }
            }
        }
        ConntrackMode::Hybrid => {
+            let ports = listener_port_set(cfg);
            for ip in &cfg.server.conntrack_control.hybrid_listener_ips {
                if ip.is_ipv4() {
-                    v4_targets.insert(Some(*ip));
+                    for port in &ports {
+                        v4_targets.insert((Some(*ip), *port));
+                    }
                } else {
-                    v6_targets.insert(Some(*ip));
+                    for port in &ports {
+                        v6_targets.insert((Some(*ip), *port));
+                    }
                }
            }
        }
@@ -422,19 +486,19 @@ async fn apply_nft_rules(cfg: &ProxyConfig) -> Result<(), String> {

    let (v4_targets, v6_targets) = notrack_targets(cfg);
    let mut rules = Vec::new();
-    for ip in v4_targets {
+    for (ip, port) in v4_targets {
        let rule = if let Some(ip) = ip {
-            format!("tcp dport {} ip daddr {} notrack", cfg.server.port, ip)
+            format!("tcp dport {} ip daddr {} notrack", port, ip)
        } else {
-            format!("tcp dport {} notrack", cfg.server.port)
+            format!("tcp dport {} notrack", port)
        };
        rules.push(rule);
    }
-    for ip in v6_targets {
+    for (ip, port) in v6_targets {
        let rule = if let Some(ip) = ip {
-            format!("tcp dport {} ip6 daddr {} notrack", cfg.server.port, ip)
+            format!("tcp dport {} ip6 daddr {} notrack", port, ip)
        } else {
-            format!("tcp dport {} notrack", cfg.server.port)
+            format!("tcp dport {} notrack", port)
        };
        rules.push(rule);
    }
@@ -498,7 +562,7 @@ async fn apply_iptables_rules_for_binary(

    let (v4_targets, v6_targets) = notrack_targets(cfg);
    let selected = if ipv4 { v4_targets } else { v6_targets };
-    for ip in selected {
+    for (ip, port) in selected {
        let mut args = vec![
            "-t".to_string(),
            "raw".to_string(),
@@ -507,7 +571,7 @@ async fn apply_iptables_rules_for_binary(
            "-p".to_string(),
            "tcp".to_string(),
            "--dport".to_string(),
-            cfg.server.port.to_string(),
+            port.to_string(),
        ];
        if let Some(ip) = ip {
            args.push("-d".to_string());
@@ -691,7 +755,7 @@ mod tests {
            me_queue_pressure_delta: 0,
        };

-        update_pressure_state(&stats, shared.as_ref(), &cfg, &sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &sample, &mut state);

        assert!(state.active);
        assert!(shared.conntrack_pressure_active());
@@ -712,7 +776,14 @@ mod tests {
            accept_timeout_delta: 0,
            me_queue_pressure_delta: 0,
        };
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &high_sample, &mut state);
+        update_pressure_state(
+            &stats,
+            shared.as_ref(),
+            &cfg,
+            true,
+            &high_sample,
+            &mut state,
+        );
        assert!(state.active);

        let low_sample = PressureSample {
@@ -721,11 +792,11 @@ mod tests {
            accept_timeout_delta: 0,
            me_queue_pressure_delta: 0,
        };
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &low_sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &low_sample, &mut state);
        assert!(state.active);
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &low_sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &low_sample, &mut state);
        assert!(state.active);
-        update_pressure_state(&stats, shared.as_ref(), &cfg, &low_sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, true, &low_sample, &mut state);

        assert!(!state.active);
        assert!(!shared.conntrack_pressure_active());
@@ -746,7 +817,7 @@ mod tests {
            me_queue_pressure_delta: 10,
        };

-        update_pressure_state(&stats, shared.as_ref(), &cfg, &sample, &mut state);
+        update_pressure_state(&stats, shared.as_ref(), &cfg, false, &sample, &mut state);

        assert!(!state.active);
        assert!(!shared.conntrack_pressure_active());
@@ -8,6 +8,7 @@ use std::io::{self, Read, Write};
 use std::os::unix::fs::OpenOptionsExt;
 use std::path::{Path, PathBuf};

+use nix::errno::Errno;
 use nix::fcntl::{Flock, FlockArg};
 use nix::unistd::{self, ForkResult, Gid, Pid, Uid, chdir, close, fork, getpid, setsid};
 use tracing::{debug, info, warn};
@@ -157,15 +158,15 @@ fn redirect_stdio_to_devnull() -> Result<(), DaemonError> {
    unsafe {
        // Redirect stdin (fd 0)
        if libc::dup2(devnull_fd, 0) < 0 {
-            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+            return Err(DaemonError::RedirectFailed(Errno::last()));
        }
        // Redirect stdout (fd 1)
        if libc::dup2(devnull_fd, 1) < 0 {
-            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+            return Err(DaemonError::RedirectFailed(Errno::last()));
        }
        // Redirect stderr (fd 2)
        if libc::dup2(devnull_fd, 2) < 0 {
-            return Err(DaemonError::RedirectFailed(nix::errno::Errno::last()));
+            return Err(DaemonError::RedirectFailed(Errno::last()));
        }
    }

@@ -337,6 +338,27 @@ fn is_process_running(pid: i32) -> bool {
    nix::sys::signal::kill(Pid::from_raw(pid), None).is_ok()
 }

+// macOS gates nix::unistd::setgroups differently in the current dependency set,
+// so call libc directly there while preserving the original nix path elsewhere.
+fn set_supplementary_groups(gid: Gid) -> Result<(), nix::Error> {
+    #[cfg(target_os = "macos")]
+    {
+        let groups = [gid.as_raw()];
+        let rc = unsafe {
+            libc::setgroups(
+                i32::try_from(groups.len()).expect("single supplementary group must fit in c_int"),
+                groups.as_ptr(),
+            )
+        };
+        if rc == 0 { Ok(()) } else { Err(Errno::last()) }
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        unistd::setgroups(&[gid])
+    }
+}
+
 /// Drops privileges to the specified user and group.
 ///
 /// This should be called after binding privileged ports but before entering
@@ -368,7 +390,7 @@ pub fn drop_privileges(

    if let Some(gid) = target_gid {
        unistd::setgid(gid).map_err(DaemonError::PrivilegeDrop)?;
-        unistd::setgroups(&[gid]).map_err(DaemonError::PrivilegeDrop)?;
+        set_supplementary_groups(gid).map_err(DaemonError::PrivilegeDrop)?;
        info!(gid = gid.as_raw(), "Dropped group privileges");
    }

@@ -222,6 +222,21 @@ pub enum ProxyError {
    #[error("Proxy error: {0}")]
    Proxy(String),

+    #[error("ME connection lost")]
+    MiddleConnectionLost,
+
+    #[error("Session terminated")]
+    RouteSwitched,
+
+    #[error("Traffic budget wait cancelled")]
+    TrafficBudgetWaitCancelled,
+
+    #[error("Traffic budget wait deadline exceeded")]
+    TrafficBudgetWaitDeadlineExceeded,
+
+    #[error("ME client writer cancelled")]
+    MiddleClientWriterCancelled,
+
    // ============= Config Errors =============
    #[error("Config error: {0}")]
    Config(String),
@@ -0,0 +1,211 @@
+use std::io::{Read, Write};
+use std::net::{Ipv4Addr, Ipv6Addr, SocketAddr, TcpStream};
+use std::time::Duration;
+
+use serde_json::Value;
+
+use crate::config::ProxyConfig;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum HealthcheckMode {
+    Liveness,
+    Ready,
+}
+
+impl HealthcheckMode {
+    pub(crate) fn from_cli_arg(value: &str) -> Option<Self> {
+        match value {
+            "liveness" => Some(Self::Liveness),
+            "ready" => Some(Self::Ready),
+            _ => None,
+        }
+    }
+
+    fn request_path(self) -> &'static str {
+        match self {
+            Self::Liveness => "/v1/health",
+            Self::Ready => "/v1/health/ready",
+        }
+    }
+}
+
+pub(crate) fn run(config_path: &str, mode: HealthcheckMode) -> i32 {
+    match run_inner(config_path, mode) {
+        Ok(()) => 0,
+        Err(error) => {
+            eprintln!("[telemt] healthcheck failed: {error}");
+            1
+        }
+    }
+}
+
+fn run_inner(config_path: &str, mode: HealthcheckMode) -> Result<(), String> {
+    let config =
+        ProxyConfig::load(config_path).map_err(|error| format!("config load failed: {error}"))?;
+    let api_cfg = &config.server.api;
+    if !api_cfg.enabled {
+        return Ok(());
+    }
+
+    let listen: SocketAddr = api_cfg
+        .listen
+        .parse()
+        .map_err(|_| format!("invalid API listen address: {}", api_cfg.listen))?;
+    if listen.port() == 0 {
+        return Err("API listen port is 0".to_string());
+    }
+    let target = probe_target(listen);
+
+    let mut stream = TcpStream::connect_timeout(&target, Duration::from_secs(2))
+        .map_err(|error| format!("connect {target} failed: {error}"))?;
+    stream
+        .set_read_timeout(Some(Duration::from_secs(2)))
+        .map_err(|error| format!("set read timeout failed: {error}"))?;
+    stream
+        .set_write_timeout(Some(Duration::from_secs(2)))
+        .map_err(|error| format!("set write timeout failed: {error}"))?;
+
+    let request = build_request(target, mode.request_path(), &api_cfg.auth_header);
+    stream
+        .write_all(request.as_bytes())
+        .map_err(|error| format!("request write failed: {error}"))?;
+    stream
+        .flush()
+        .map_err(|error| format!("request flush failed: {error}"))?;
+
+    let mut raw_response = Vec::new();
+    stream
+        .read_to_end(&mut raw_response)
+        .map_err(|error| format!("response read failed: {error}"))?;
+    let response =
+        String::from_utf8(raw_response).map_err(|_| "response is not valid UTF-8".to_string())?;
+
+    let (status_code, body) = split_response(&response)?;
+    if status_code != 200 {
+        return Err(format!("HTTP status {status_code}"));
+    }
+
+    validate_payload(mode, body)?;
+    Ok(())
+}
+
+fn probe_target(listen: SocketAddr) -> SocketAddr {
+    match listen {
+        SocketAddr::V4(addr) => {
+            let ip = if addr.ip().is_unspecified() {
+                Ipv4Addr::LOCALHOST
+            } else {
+                *addr.ip()
+            };
+            SocketAddr::from((ip, addr.port()))
+        }
+        SocketAddr::V6(addr) => {
+            let ip = if addr.ip().is_unspecified() {
+                Ipv6Addr::LOCALHOST
+            } else {
+                *addr.ip()
+            };
+            SocketAddr::from((ip, addr.port()))
+        }
+    }
+}
+
+fn build_request(target: SocketAddr, path: &str, auth_header: &str) -> String {
+    let mut request = format!(
+        "GET {path} HTTP/1.1\r\nHost: {}\r\nConnection: close\r\n",
+        target
+    );
+    if !auth_header.is_empty() {
+        request.push_str("Authorization: ");
+        request.push_str(auth_header);
+        request.push_str("\r\n");
+    }
+    request.push_str("\r\n");
+    request
+}
+
+fn split_response(response: &str) -> Result<(u16, &str), String> {
+    let header_end = response
+        .find("\r\n\r\n")
+        .ok_or_else(|| "invalid HTTP response headers".to_string())?;
+    let header = &response[..header_end];
+    let body = &response[header_end + 4..];
+    let status_line = header
+        .lines()
+        .next()
+        .ok_or_else(|| "missing HTTP status line".to_string())?;
+    let status_code = parse_status_code(status_line)?;
+    Ok((status_code, body))
+}
+
+fn parse_status_code(status_line: &str) -> Result<u16, String> {
+    let mut parts = status_line.split_whitespace();
+    let version = parts
+        .next()
+        .ok_or_else(|| "missing HTTP version".to_string())?;
+    if !version.starts_with("HTTP/") {
+        return Err(format!("invalid HTTP status line: {status_line}"));
+    }
+    let code = parts
+        .next()
+        .ok_or_else(|| "missing HTTP status code".to_string())?;
+    code.parse::<u16>()
+        .map_err(|_| format!("invalid HTTP status code: {code}"))
+}
+
+fn validate_payload(mode: HealthcheckMode, body: &str) -> Result<(), String> {
+    let payload: Value =
+        serde_json::from_str(body).map_err(|_| "response body is not valid JSON".to_string())?;
+    if payload.get("ok").and_then(Value::as_bool) != Some(true) {
+        return Err("response JSON has ok=false".to_string());
+    }
+
+    let data = payload
+        .get("data")
+        .ok_or_else(|| "response JSON has no data field".to_string())?;
+    match mode {
+        HealthcheckMode::Liveness => {
+            if data.get("status").and_then(Value::as_str) != Some("ok") {
+                return Err("liveness status is not ok".to_string());
+            }
+        }
+        HealthcheckMode::Ready => {
+            if data.get("ready").and_then(Value::as_bool) != Some(true) {
+                return Err("readiness flag is false".to_string());
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{HealthcheckMode, parse_status_code, split_response, validate_payload};
+
+    #[test]
+    fn parse_status_code_reads_http_200() {
+        let status = parse_status_code("HTTP/1.1 200 OK").expect("must parse status");
+        assert_eq!(status, 200);
+    }
+
+    #[test]
+    fn split_response_extracts_status_and_body() {
+        let response = "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\r\n{\"ok\":true}";
+        let (status, body) = split_response(response).expect("must split response");
+        assert_eq!(status, 200);
+        assert_eq!(body, "{\"ok\":true}");
+    }
+
+    #[test]
+    fn validate_payload_accepts_liveness_contract() {
+        let body = "{\"ok\":true,\"data\":{\"status\":\"ok\"}}";
+        validate_payload(HealthcheckMode::Liveness, body).expect("liveness payload must pass");
+    }
+
+    #[test]
+    fn validate_payload_rejects_not_ready() {
+        let body = "{\"ok\":true,\"data\":{\"ready\":false}}";
+        let result = validate_payload(HealthcheckMode::Ready, body);
+        assert!(result.is_err());
+    }
+}
@@ -0,0 +1,173 @@
+use super::*;
+
+impl UserIpTracker {
+    pub async fn set_limit_policy(&self, mode: UserMaxUniqueIpsMode, window_secs: u64) {
+        self.limit_mode
+            .store(Self::mode_to_u8(mode), Ordering::Relaxed);
+        self.limit_window_secs
+            .store(window_secs.max(1), Ordering::Relaxed);
+    }
+
+    pub async fn set_user_limit(&self, username: &str, max_ips: usize) {
+        self.max_ips.insert(username.to_string(), max_ips);
+    }
+
+    pub async fn remove_user_limit(&self, username: &str) {
+        self.max_ips.remove(username);
+    }
+
+    pub async fn load_limits(&self, default_limit: usize, limits: &HashMap<String, usize>) {
+        self.default_max_ips.store(default_limit, Ordering::Relaxed);
+        self.max_ips.clear();
+        for (username, limit) in limits {
+            self.max_ips.insert(username.clone(), *limit);
+        }
+    }
+
+    pub(super) fn prune_recent(
+        user_recent: &mut HashMap<IpAddr, Instant>,
+        now: Instant,
+        window: Duration,
+    ) -> usize {
+        if user_recent.is_empty() {
+            return 0;
+        }
+        let before = user_recent.len();
+        user_recent.retain(|_, seen_at| now.duration_since(*seen_at) <= window);
+        before.saturating_sub(user_recent.len())
+    }
+
+    pub async fn check_and_add(&self, username: &str, ip: IpAddr) -> Result<(), String> {
+        self.drain_cleanup_for_user(username).await;
+        self.maybe_compact_empty_users().await;
+        let limit = self.user_limit(username);
+        let mode = Self::mode_from_u8(self.limit_mode.load(Ordering::Relaxed));
+        let window = self.limit_window();
+        let now = Instant::now();
+
+        let shard_idx = Self::shard_idx(username);
+        let mut shard = self.shards[shard_idx].write().await;
+        let user_active = shard.active_ips.entry(username.to_string()).or_default();
+        let active_contains_ip = user_active.contains_key(&ip);
+        let active_len = user_active.len();
+        let user_recent = shard.recent_ips.entry(username.to_string()).or_default();
+        let pruned_recent_entries = Self::prune_recent(user_recent, now, window);
+        Self::decrement_counter(&self.recent_entry_count, pruned_recent_entries);
+        let recent_contains_ip = user_recent.contains_key(&ip);
+        let recent_len = user_recent.len();
+
+        if active_contains_ip {
+            if !recent_contains_ip
+                && !Self::try_increment_counter(&self.recent_entry_count, MAX_RECENT_IP_ENTRIES)
+            {
+                self.recent_cap_rejects.fetch_add(1, Ordering::Relaxed);
+                return Err(format!(
+                    "IP tracker recent entry cap reached: entries={}/{}",
+                    self.recent_entry_count.load(Ordering::Relaxed),
+                    MAX_RECENT_IP_ENTRIES
+                ));
+            }
+            let Some(count) = shard
+                .active_ips
+                .get_mut(username)
+                .and_then(|user_active| user_active.get_mut(&ip))
+            else {
+                return Err(format!(
+                    "IP tracker active entry unavailable for user '{username}'"
+                ));
+            };
+            *count = count.saturating_add(1);
+            if let Some(user_recent) = shard.recent_ips.get_mut(username) {
+                user_recent.insert(ip, now);
+            }
+            return Ok(());
+        }
+
+        let is_new_ip = !recent_contains_ip;
+
+        if let Some(limit) = limit {
+            let active_limit_reached = active_len >= limit;
+            let recent_limit_reached = recent_len >= limit && is_new_ip;
+            let deny = match mode {
+                UserMaxUniqueIpsMode::ActiveWindow => active_limit_reached,
+                UserMaxUniqueIpsMode::TimeWindow => recent_limit_reached,
+                UserMaxUniqueIpsMode::Combined => active_limit_reached || recent_limit_reached,
+            };
+
+            if deny {
+                return Err(format!(
+                    "IP limit reached for user '{}': active={}/{} recent={}/{} mode={:?}",
+                    username, active_len, limit, recent_len, limit, mode
+                ));
+            }
+        }
+
+        if !Self::try_increment_counter(&self.active_entry_count, MAX_ACTIVE_IP_ENTRIES) {
+            self.active_cap_rejects.fetch_add(1, Ordering::Relaxed);
+            return Err(format!(
+                "IP tracker active entry cap reached: entries={}/{}",
+                self.active_entry_count.load(Ordering::Relaxed),
+                MAX_ACTIVE_IP_ENTRIES
+            ));
+        }
+        let mut reserved_recent = false;
+        if is_new_ip {
+            if !Self::try_increment_counter(&self.recent_entry_count, MAX_RECENT_IP_ENTRIES) {
+                Self::decrement_counter(&self.active_entry_count, 1);
+                self.recent_cap_rejects.fetch_add(1, Ordering::Relaxed);
+                return Err(format!(
+                    "IP tracker recent entry cap reached: entries={}/{}",
+                    self.recent_entry_count.load(Ordering::Relaxed),
+                    MAX_RECENT_IP_ENTRIES
+                ));
+            }
+            reserved_recent = true;
+        }
+
+        let Some(user_active) = shard.active_ips.get_mut(username) else {
+            Self::decrement_counter(&self.active_entry_count, 1);
+            if reserved_recent {
+                Self::decrement_counter(&self.recent_entry_count, 1);
+            }
+            return Err(format!(
+                "IP tracker active entry unavailable for user '{username}'"
+            ));
+        };
+        if user_active.insert(ip, 1).is_some() {
+            Self::decrement_counter(&self.active_entry_count, 1);
+        }
+        let Some(user_recent) = shard.recent_ips.get_mut(username) else {
+            Self::decrement_counter(&self.active_entry_count, 1);
+            if reserved_recent {
+                Self::decrement_counter(&self.recent_entry_count, 1);
+            }
+            return Err(format!(
+                "IP tracker recent entry unavailable for user '{username}'"
+            ));
+        };
+        if user_recent.insert(ip, now).is_some() && reserved_recent {
+            Self::decrement_counter(&self.recent_entry_count, 1);
+        }
+        Ok(())
+    }
+
+    pub async fn remove_ip(&self, username: &str, ip: IpAddr) {
+        self.maybe_compact_empty_users().await;
+        let shard_idx = Self::shard_idx(username);
+        let mut shard = self.shards[shard_idx].write().await;
+        let mut removed_active_entries = 0usize;
+        if let Some(user_ips) = shard.active_ips.get_mut(username) {
+            if let Some(count) = user_ips.get_mut(&ip) {
+                if *count > 1 {
+                    *count -= 1;
+                } else if user_ips.remove(&ip).is_some() {
+                    removed_active_entries = 1;
+                }
+            }
+            if user_ips.is_empty() {
+                shard.active_ips.remove(username);
+            }
+        }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+    }
+}
@@ -0,0 +1,148 @@
+use super::*;
+
+impl UserIpTracker {
+    /// Queues a deferred active IP cleanup for a later async drain.
+    pub fn enqueue_cleanup(&self, user: String, ip: IpAddr) {
+        self.observe_cleanup_poison_for_tests();
+        let shard_idx = Self::shard_idx(&user);
+        let cleanup_shard = &self.cleanup_shards[shard_idx];
+        match cleanup_shard.queue.lock() {
+            Ok(mut queue) => {
+                let user_queue = queue.entry(user).or_default();
+                let count = user_queue.entry(ip).or_insert(0);
+                if *count == 0 {
+                    self.cleanup_queue_len.fetch_add(1, Ordering::Relaxed);
+                }
+                *count = count.saturating_add(1);
+                self.cleanup_deferred_releases
+                    .fetch_add(1, Ordering::Relaxed);
+            }
+            Err(poisoned) => {
+                let mut queue = poisoned.into_inner();
+                let user_queue = queue.entry(user.clone()).or_default();
+                let count = user_queue.entry(ip).or_insert(0);
+                if *count == 0 {
+                    self.cleanup_queue_len.fetch_add(1, Ordering::Relaxed);
+                }
+                *count = count.saturating_add(1);
+                self.cleanup_deferred_releases
+                    .fetch_add(1, Ordering::Relaxed);
+                cleanup_shard.queue.clear_poison();
+                tracing::warn!(
+                    "UserIpTracker cleanup_queue lock poisoned; recovered and enqueued IP cleanup for {} ({})",
+                    user,
+                    ip
+                );
+            }
+        }
+    }
+
+    #[cfg(test)]
+    pub(crate) fn cleanup_queue_len_for_tests(&self) -> usize {
+        self.cleanup_queue_len.load(Ordering::Relaxed) as usize
+    }
+
+    #[cfg(test)]
+    pub(crate) fn cleanup_queue_mutex_for_tests(
+        &self,
+    ) -> Arc<Mutex<HashMap<(String, IpAddr), usize>>> {
+        Arc::clone(&self.cleanup_queue_poison_probe)
+    }
+
+    pub(crate) async fn drain_cleanup_queue(&self) {
+        if self.cleanup_queue_len.load(Ordering::Relaxed) == 0 {
+            return;
+        }
+        for shard_idx in 0..USER_IP_TRACKER_SHARDS {
+            self.drain_cleanup_shard(shard_idx).await;
+        }
+    }
+
+    pub(super) async fn drain_cleanup_for_user(&self, user: &str) {
+        if self.cleanup_queue_len.load(Ordering::Relaxed) == 0 {
+            return;
+        }
+        let shard_idx = Self::shard_idx(user);
+        let cleanup_shard = &self.cleanup_shards[shard_idx];
+        let to_remove = match cleanup_shard.queue.lock() {
+            Ok(mut queue) => queue.remove(user).unwrap_or_default(),
+            Err(poisoned) => {
+                let mut queue = poisoned.into_inner();
+                let drained = queue.remove(user).unwrap_or_default();
+                cleanup_shard.queue.clear_poison();
+                drained
+            }
+        };
+        if to_remove.is_empty() {
+            return;
+        }
+        self.cleanup_queue_len
+            .fetch_sub(to_remove.len() as u64, Ordering::Relaxed);
+        let mut shard = self.shards[shard_idx].write().await;
+        let mut removed_active_entries = 0usize;
+        for (ip, pending_count) in to_remove {
+            removed_active_entries = removed_active_entries.saturating_add(
+                Self::apply_active_cleanup(&mut shard.active_ips, user, ip, pending_count),
+            );
+        }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+    }
+
+    pub(super) async fn drain_cleanup_shard(&self, shard_idx: usize) {
+        let Ok(_drain_guard) = self.cleanup_drain_locks[shard_idx].try_lock() else {
+            return;
+        };
+
+        let cleanup_shard = &self.cleanup_shards[shard_idx];
+        let to_remove = {
+            match cleanup_shard.queue.lock() {
+                Ok(mut queue) => {
+                    if queue.is_empty() {
+                        return;
+                    }
+                    let mut drained =
+                        HashMap::with_capacity(queue.len().min(CLEANUP_DRAIN_BATCH_LIMIT));
+                    for _ in 0..CLEANUP_DRAIN_BATCH_LIMIT {
+                        let Some((user, ip, count)) = Self::pop_one_cleanup(&mut queue) else {
+                            break;
+                        };
+                        self.cleanup_queue_len.fetch_sub(1, Ordering::Relaxed);
+                        drained.insert((user, ip), count);
+                    }
+                    drained
+                }
+                Err(poisoned) => {
+                    let mut queue = poisoned.into_inner();
+                    if queue.is_empty() {
+                        cleanup_shard.queue.clear_poison();
+                        return;
+                    }
+                    let mut drained =
+                        HashMap::with_capacity(queue.len().min(CLEANUP_DRAIN_BATCH_LIMIT));
+                    for _ in 0..CLEANUP_DRAIN_BATCH_LIMIT {
+                        let Some((user, ip, count)) = Self::pop_one_cleanup(&mut queue) else {
+                            break;
+                        };
+                        self.cleanup_queue_len.fetch_sub(1, Ordering::Relaxed);
+                        drained.insert((user, ip), count);
+                    }
+                    cleanup_shard.queue.clear_poison();
+                    drained
+                }
+            }
+        };
+        drop(_drain_guard);
+        if to_remove.is_empty() {
+            return;
+        }
+
+        let mut shard = self.shards[shard_idx].write().await;
+        let mut removed_active_entries = 0usize;
+        for ((user, ip), pending_count) in to_remove {
+            removed_active_entries = removed_active_entries.saturating_add(
+                Self::apply_active_cleanup(&mut shard.active_ips, &user, ip, pending_count),
+            );
+        }
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+    }
+}
@@ -0,0 +1,309 @@
+use super::*;
+
+impl UserIpTracker {
+    pub(super) async fn maybe_compact_empty_users(&self) {
+        const COMPACT_INTERVAL_SECS: u64 = 60;
+        let now_epoch_secs = Self::now_epoch_secs();
+        let last_compact_epoch_secs = self.last_compact_epoch_secs.load(Ordering::Relaxed);
+        if now_epoch_secs.saturating_sub(last_compact_epoch_secs) < COMPACT_INTERVAL_SECS {
+            return;
+        }
+        if self
+            .last_compact_epoch_secs
+            .compare_exchange(
+                last_compact_epoch_secs,
+                now_epoch_secs,
+                Ordering::AcqRel,
+                Ordering::Relaxed,
+            )
+            .is_err()
+        {
+            return;
+        }
+
+        let window = self.limit_window();
+        let now = Instant::now();
+        for shard_lock in self.shards.iter() {
+            let mut shard = shard_lock.write().await;
+            let mut pruned_recent_entries = 0usize;
+            for user_recent in shard.recent_ips.values_mut() {
+                pruned_recent_entries = pruned_recent_entries.saturating_add(Self::prune_recent(
+                    user_recent,
+                    now,
+                    window,
+                ));
+            }
+            Self::decrement_counter(&self.recent_entry_count, pruned_recent_entries);
+
+            let mut users = Vec::<String>::with_capacity(
+                shard
+                    .active_ips
+                    .len()
+                    .saturating_add(shard.recent_ips.len()),
+            );
+            users.extend(shard.active_ips.keys().cloned());
+            for user in shard.recent_ips.keys() {
+                if !shard.active_ips.contains_key(user) {
+                    users.push(user.clone());
+                }
+            }
+
+            for user in users {
+                let active_empty = shard
+                    .active_ips
+                    .get(&user)
+                    .map(|ips| ips.is_empty())
+                    .unwrap_or(true);
+                let recent_empty = shard
+                    .recent_ips
+                    .get(&user)
+                    .map(|ips| ips.is_empty())
+                    .unwrap_or(true);
+                if active_empty && recent_empty {
+                    shard.active_ips.remove(&user);
+                    shard.recent_ips.remove(&user);
+                }
+            }
+        }
+    }
+
+    pub async fn run_periodic_maintenance(self: Arc<Self>) {
+        let mut interval = tokio::time::interval(Duration::from_secs(1));
+        loop {
+            interval.tick().await;
+            self.drain_cleanup_queue().await;
+            self.maybe_compact_empty_users().await;
+        }
+    }
+
+    pub async fn memory_stats(&self) -> UserIpTrackerMemoryStats {
+        let cleanup_queue_len = self.cleanup_queue_len.load(Ordering::Relaxed) as usize;
+        let mut active_users = 0usize;
+        let mut recent_users = 0usize;
+        let mut active_entries = 0usize;
+        let mut recent_entries = 0usize;
+        for shard_lock in self.shards.iter() {
+            let shard = shard_lock.read().await;
+            active_users = active_users.saturating_add(shard.active_ips.len());
+            recent_users = recent_users.saturating_add(shard.recent_ips.len());
+            active_entries =
+                active_entries.saturating_add(shard.active_ips.values().map(HashMap::len).sum());
+            recent_entries =
+                recent_entries.saturating_add(shard.recent_ips.values().map(HashMap::len).sum());
+        }
+
+        UserIpTrackerMemoryStats {
+            active_users,
+            recent_users,
+            active_entries,
+            recent_entries,
+            cleanup_queue_len,
+            active_cap_rejects: self.active_cap_rejects.load(Ordering::Relaxed),
+            recent_cap_rejects: self.recent_cap_rejects.load(Ordering::Relaxed),
+            cleanup_deferred_releases: self.cleanup_deferred_releases.load(Ordering::Relaxed),
+        }
+    }
+
+    pub async fn get_recent_counts_for_users(&self, users: &[String]) -> HashMap<String, usize> {
+        self.drain_cleanup_queue().await;
+        self.get_recent_counts_for_users_snapshot(users).await
+    }
+
+    pub(crate) async fn get_recent_counts_for_users_snapshot(
+        &self,
+        users: &[String],
+    ) -> HashMap<String, usize> {
+        let window = self.limit_window();
+        let now = Instant::now();
+
+        let mut counts = HashMap::with_capacity(users.len());
+        for user in users {
+            let shard_idx = Self::shard_idx(user);
+            let shard = self.shards[shard_idx].read().await;
+            let count = if let Some(user_recent) = shard.recent_ips.get(user) {
+                user_recent
+                    .values()
+                    .filter(|seen_at| now.duration_since(**seen_at) <= window)
+                    .count()
+            } else {
+                0
+            };
+            counts.insert(user.clone(), count);
+        }
+        counts
+    }
+
+    pub async fn get_active_ips_for_users(&self, users: &[String]) -> HashMap<String, Vec<IpAddr>> {
+        self.drain_cleanup_queue().await;
+        let mut out = HashMap::with_capacity(users.len());
+        for user in users {
+            let shard_idx = Self::shard_idx(user);
+            let shard = self.shards[shard_idx].read().await;
+            let mut ips = shard
+                .active_ips
+                .get(user)
+                .map(|per_ip| per_ip.keys().copied().collect::<Vec<_>>())
+                .unwrap_or_else(Vec::new);
+            ips.sort();
+            out.insert(user.clone(), ips);
+        }
+        out
+    }
+
+    pub async fn get_recent_ips_for_users(&self, users: &[String]) -> HashMap<String, Vec<IpAddr>> {
+        self.drain_cleanup_queue().await;
+        let window = self.limit_window();
+        let now = Instant::now();
+
+        let mut out = HashMap::with_capacity(users.len());
+        for user in users {
+            let shard_idx = Self::shard_idx(user);
+            let shard = self.shards[shard_idx].read().await;
+            let mut ips = if let Some(user_recent) = shard.recent_ips.get(user) {
+                user_recent
+                    .iter()
+                    .filter(|(_, seen_at)| now.duration_since(**seen_at) <= window)
+                    .map(|(ip, _)| *ip)
+                    .collect::<Vec<_>>()
+            } else {
+                Vec::new()
+            };
+            ips.sort();
+            out.insert(user.clone(), ips);
+        }
+        out
+    }
+
+    pub async fn get_active_ip_count(&self, username: &str) -> usize {
+        self.drain_cleanup_queue().await;
+        let shard_idx = Self::shard_idx(username);
+        let shard = self.shards[shard_idx].read().await;
+        shard
+            .active_ips
+            .get(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0)
+    }
+
+    pub async fn get_active_ips(&self, username: &str) -> Vec<IpAddr> {
+        self.drain_cleanup_queue().await;
+        let shard_idx = Self::shard_idx(username);
+        let shard = self.shards[shard_idx].read().await;
+        shard
+            .active_ips
+            .get(username)
+            .map(|ips| ips.keys().copied().collect())
+            .unwrap_or_else(Vec::new)
+    }
+
+    pub async fn get_stats(&self) -> Vec<(String, usize, usize)> {
+        self.drain_cleanup_queue().await;
+        self.get_stats_snapshot().await
+    }
+
+    pub(crate) async fn get_stats_snapshot(&self) -> Vec<(String, usize, usize)> {
+        let mut active_counts = Vec::new();
+        for shard_lock in self.shards.iter() {
+            let shard = shard_lock.read().await;
+            active_counts.extend(
+                shard
+                    .active_ips
+                    .iter()
+                    .map(|(username, user_ips)| (username.clone(), user_ips.len())),
+            );
+        }
+
+        let mut stats = Vec::with_capacity(active_counts.len());
+        for (username, active_count) in active_counts {
+            let limit = self.user_limit(&username).unwrap_or(0);
+            stats.push((username, active_count, limit));
+        }
+
+        stats.sort_by(|a, b| a.0.cmp(&b.0));
+        stats
+    }
+
+    pub async fn clear_user_ips(&self, username: &str) {
+        let shard_idx = Self::shard_idx(username);
+        let mut shard = self.shards[shard_idx].write().await;
+        let removed_active_entries = shard
+            .active_ips
+            .remove(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0);
+        Self::decrement_counter(&self.active_entry_count, removed_active_entries);
+
+        let removed_recent_entries = shard
+            .recent_ips
+            .remove(username)
+            .map(|ips| ips.len())
+            .unwrap_or(0);
+        Self::decrement_counter(&self.recent_entry_count, removed_recent_entries);
+    }
+
+    pub async fn clear_all(&self) {
+        for shard_lock in self.shards.iter() {
+            let mut shard = shard_lock.write().await;
+            shard.active_ips.clear();
+            shard.recent_ips.clear();
+        }
+        self.active_entry_count.store(0, Ordering::Relaxed);
+        self.recent_entry_count.store(0, Ordering::Relaxed);
+        for cleanup_shard in self.cleanup_shards.iter() {
+            match cleanup_shard.queue.lock() {
+                Ok(mut queue) => queue.clear(),
+                Err(poisoned) => {
+                    poisoned.into_inner().clear();
+                    cleanup_shard.queue.clear_poison();
+                }
+            }
+        }
+        self.cleanup_queue_len.store(0, Ordering::Relaxed);
+    }
+
+    pub async fn is_ip_active(&self, username: &str, ip: IpAddr) -> bool {
+        self.drain_cleanup_queue().await;
+        let shard_idx = Self::shard_idx(username);
+        let shard = self.shards[shard_idx].read().await;
+        shard
+            .active_ips
+            .get(username)
+            .map(|ips| ips.contains_key(&ip))
+            .unwrap_or(false)
+    }
+
+    pub async fn get_user_limit(&self, username: &str) -> Option<usize> {
+        self.user_limit(username)
+    }
+
+    pub async fn format_stats(&self) -> String {
+        let stats = self.get_stats().await;
+
+        if stats.is_empty() {
+            return String::from("No active users");
+        }
+
+        let mut output = String::from("User IP Statistics:\n");
+        output.push_str("==================\n");
+
+        for (username, active_count, limit) in stats {
+            output.push_str(&format!(
+                "User: {:<20} Active IPs: {}/{}\n",
+                username,
+                active_count,
+                if limit > 0 {
+                    limit.to_string()
+                } else {
+                    "unlimited".to_string()
+                }
+            ));
+
+            let ips = self.get_active_ips(&username).await;
+            for ip in ips {
+                output.push_str(&format!("  - {}\n", ip));
+            }
+        }
+
+        output
+    }
+}
@@ -0,0 +1,385 @@
+use super::*;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+use std::sync::atomic::Ordering;
+
+fn test_ipv4(oct1: u8, oct2: u8, oct3: u8, oct4: u8) -> IpAddr {
+    IpAddr::V4(Ipv4Addr::new(oct1, oct2, oct3, oct4))
+}
+
+fn test_ipv6() -> IpAddr {
+    IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1))
+}
+
+#[tokio::test]
+async fn test_basic_ip_limit() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+    let ip3 = test_ipv4(192, 168, 1, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+}
+
+#[tokio::test]
+async fn test_active_window_rejects_new_ip_and_keeps_existing_session() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::ActiveWindow, 30)
+        .await;
+
+    let ip1 = test_ipv4(10, 10, 10, 1);
+    let ip2 = test_ipv4(10, 10, 10, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.is_ip_active("test_user", ip1).await);
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+    // Existing session remains active; only new unique IP is denied.
+    assert!(tracker.is_ip_active("test_user", ip1).await);
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+}
+
+#[tokio::test]
+async fn test_reconnection_from_same_ip() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+}
+
+#[tokio::test]
+async fn test_same_ip_disconnect_keeps_active_while_other_session_alive() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+    tracker.remove_ip("test_user", ip1).await;
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+    tracker.remove_ip("test_user", ip1).await;
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 0);
+}
+
+#[tokio::test]
+async fn test_ip_removal() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+    let ip3 = test_ipv4(192, 168, 1, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+
+    tracker.remove_ip("test_user", ip1).await;
+
+    assert!(tracker.check_and_add("test_user", ip3).await.is_ok());
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+}
+
+#[tokio::test]
+async fn test_no_limit() {
+    let tracker = UserIpTracker::new();
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+    let ip3 = test_ipv4(192, 168, 1, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_ok());
+
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 3);
+}
+
+#[tokio::test]
+async fn test_multiple_users() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user1", 2).await;
+    tracker.set_user_limit("user2", 1).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    assert!(tracker.check_and_add("user1", ip1).await.is_ok());
+    assert!(tracker.check_and_add("user1", ip2).await.is_ok());
+
+    assert!(tracker.check_and_add("user2", ip1).await.is_ok());
+    assert!(tracker.check_and_add("user2", ip2).await.is_err());
+}
+
+#[tokio::test]
+async fn test_ipv6_support() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 2).await;
+
+    let ipv4 = test_ipv4(192, 168, 1, 1);
+    let ipv6 = test_ipv6();
+
+    assert!(tracker.check_and_add("test_user", ipv4).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ipv6).await.is_ok());
+
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+}
+
+#[tokio::test]
+async fn test_get_active_ips() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 3).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+    tracker.check_and_add("test_user", ip2).await.unwrap();
+
+    let active_ips = tracker.get_active_ips("test_user").await;
+    assert_eq!(active_ips.len(), 2);
+    assert!(active_ips.contains(&ip1));
+    assert!(active_ips.contains(&ip2));
+}
+
+#[tokio::test]
+async fn test_stats() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user1", 3).await;
+    tracker.set_user_limit("user2", 2).await;
+
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    tracker.check_and_add("user1", ip1).await.unwrap();
+    tracker.check_and_add("user2", ip2).await.unwrap();
+
+    let stats = tracker.get_stats().await;
+    assert_eq!(stats.len(), 2);
+
+    assert!(stats.iter().any(|(name, _, _)| name == "user1"));
+    assert!(stats.iter().any(|(name, _, _)| name == "user2"));
+}
+
+#[tokio::test]
+async fn test_clear_user_ips() {
+    let tracker = UserIpTracker::new();
+    let ip1 = test_ipv4(192, 168, 1, 1);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+    tracker.clear_user_ips("test_user").await;
+    assert_eq!(tracker.get_active_ip_count("test_user").await, 0);
+}
+
+#[tokio::test]
+async fn test_is_ip_active() {
+    let tracker = UserIpTracker::new();
+    let ip1 = test_ipv4(192, 168, 1, 1);
+    let ip2 = test_ipv4(192, 168, 1, 2);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+
+    assert!(tracker.is_ip_active("test_user", ip1).await);
+    assert!(!tracker.is_ip_active("test_user", ip2).await);
+}
+
+#[tokio::test]
+async fn test_load_limits_from_config() {
+    let tracker = UserIpTracker::new();
+
+    let mut config_limits = HashMap::new();
+    config_limits.insert("user1".to_string(), 5);
+    config_limits.insert("user2".to_string(), 3);
+
+    tracker.load_limits(0, &config_limits).await;
+
+    assert_eq!(tracker.get_user_limit("user1").await, Some(5));
+    assert_eq!(tracker.get_user_limit("user2").await, Some(3));
+    assert_eq!(tracker.get_user_limit("user3").await, None);
+}
+
+#[tokio::test]
+async fn test_load_limits_replaces_previous_map() {
+    let tracker = UserIpTracker::new();
+
+    let mut first = HashMap::new();
+    first.insert("user1".to_string(), 2);
+    first.insert("user2".to_string(), 3);
+    tracker.load_limits(0, &first).await;
+
+    let mut second = HashMap::new();
+    second.insert("user2".to_string(), 5);
+    tracker.load_limits(0, &second).await;
+
+    assert_eq!(tracker.get_user_limit("user1").await, None);
+    assert_eq!(tracker.get_user_limit("user2").await, Some(5));
+}
+
+#[tokio::test]
+async fn test_global_each_limit_applies_without_user_override() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(2, &HashMap::new()).await;
+
+    let ip1 = test_ipv4(172, 16, 0, 1);
+    let ip2 = test_ipv4(172, 16, 0, 2);
+    let ip3 = test_ipv4(172, 16, 0, 3);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+    assert_eq!(tracker.get_user_limit("test_user").await, Some(2));
+}
+
+#[tokio::test]
+async fn test_user_override_wins_over_global_each_limit() {
+    let tracker = UserIpTracker::new();
+    let mut limits = HashMap::new();
+    limits.insert("test_user".to_string(), 1);
+    tracker.load_limits(3, &limits).await;
+
+    let ip1 = test_ipv4(172, 17, 0, 1);
+    let ip2 = test_ipv4(172, 17, 0, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+    assert_eq!(tracker.get_user_limit("test_user").await, Some(1));
+}
+
+#[tokio::test]
+async fn test_time_window_mode_blocks_recent_ip_churn() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 30)
+        .await;
+
+    let ip1 = test_ipv4(10, 0, 0, 1);
+    let ip2 = test_ipv4(10, 0, 0, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+}
+
+#[tokio::test]
+async fn test_combined_mode_enforces_active_and_recent_limits() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::Combined, 30)
+        .await;
+
+    let ip1 = test_ipv4(10, 0, 1, 1);
+    let ip2 = test_ipv4(10, 0, 1, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+}
+
+#[tokio::test]
+async fn test_time_window_expires() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    let ip1 = test_ipv4(10, 1, 0, 1);
+    let ip2 = test_ipv4(10, 1, 0, 2);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+    tokio::time::sleep(Duration::from_millis(1100)).await;
+    assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+}
+
+#[tokio::test]
+async fn test_memory_stats_reports_queue_and_entry_counts() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 4).await;
+    let ip1 = test_ipv4(10, 2, 0, 1);
+    let ip2 = test_ipv4(10, 2, 0, 2);
+
+    tracker.check_and_add("test_user", ip1).await.unwrap();
+    tracker.check_and_add("test_user", ip2).await.unwrap();
+    tracker.enqueue_cleanup("test_user".to_string(), ip1);
+
+    let snapshot = tracker.memory_stats().await;
+    assert_eq!(snapshot.active_users, 1);
+    assert_eq!(snapshot.recent_users, 1);
+    assert_eq!(snapshot.active_entries, 2);
+    assert_eq!(snapshot.recent_entries, 2);
+    assert_eq!(snapshot.cleanup_queue_len, 1);
+}
+
+#[tokio::test]
+async fn test_compact_prunes_stale_recent_entries() {
+    let tracker = UserIpTracker::new();
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    let stale_user = "stale-user".to_string();
+    let stale_ip = test_ipv4(10, 3, 0, 1);
+    {
+        let shard_idx = UserIpTracker::shard_idx(&stale_user);
+        let mut shard = tracker.shards[shard_idx].write().await;
+        shard
+            .recent_ips
+            .entry(stale_user.clone())
+            .or_insert_with(HashMap::new)
+            .insert(stale_ip, Instant::now() - Duration::from_secs(5));
+    }
+
+    tracker.last_compact_epoch_secs.store(0, Ordering::Relaxed);
+    tracker
+        .check_and_add("trigger-user", test_ipv4(10, 3, 0, 2))
+        .await
+        .unwrap();
+
+    let shard_idx = UserIpTracker::shard_idx(&stale_user);
+    let shard = tracker.shards[shard_idx].read().await;
+    let stale_exists = shard
+        .recent_ips
+        .get(&stale_user)
+        .map(|ips| ips.contains_key(&stale_ip))
+        .unwrap_or(false);
+    assert!(!stale_exists);
+}
+
+#[tokio::test]
+async fn test_time_window_allows_same_ip_reconnect() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("test_user", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    let ip1 = test_ipv4(10, 4, 0, 1);
+
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+    tracker.remove_ip("test_user", ip1).await;
+    assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+}
@@ -1,7 +1,7 @@
 use std::sync::Arc;
 use std::time::{Duration, Instant};

-use tokio::sync::watch;
+use tokio::sync::{RwLock, watch};
 use tracing::{info, warn};

 use crate::config::ProxyConfig;
@@ -14,23 +14,32 @@ const RUNTIME_FALLBACK_AFTER: Duration = Duration::from_secs(6);
 pub(crate) async fn configure_admission_gate(
    config: &Arc<ProxyConfig>,
    me_pool: Option<Arc<MePool>>,
+    me_pool_runtime: Arc<RwLock<Option<Arc<MePool>>>>,
    route_runtime: Arc<RouteRuntimeController>,
    admission_tx: &watch::Sender<bool>,
    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    me_ready_rx: watch::Receiver<u64>,
 ) {
    if config.general.use_middle_proxy {
-        if let Some(pool) = me_pool.as_ref() {
-            let initial_ready = pool.admission_ready_conditional_cast().await;
+        if me_pool.is_some() || config.general.me2dc_fallback {
+            let initial_pool = match me_pool.as_ref() {
+                Some(pool) => Some(pool.clone()),
+                None => me_pool_runtime.read().await.clone(),
+            };
+            let initial_ready = match initial_pool.as_ref() {
+                Some(pool) => pool.admission_ready_conditional_cast().await,
+                None => false,
+            };
            let mut fallback_enabled = config.general.me2dc_fallback;
            let mut fast_fallback_enabled = fallback_enabled && config.general.me2dc_fast;
            let (initial_gate_open, initial_route_mode, initial_fallback_reason) = if initial_ready
            {
                (true, RelayRouteMode::Middle, None)
-            } else if fast_fallback_enabled {
+            } else if fallback_enabled {
                (
                    true,
                    RelayRouteMode::Direct,
-                    Some("fast_not_ready_fallback"),
+                    Some("startup_direct_fallback"),
                )
            } else {
                (false, RelayRouteMode::Middle, None)
@@ -48,10 +57,12 @@ pub(crate) async fn configure_admission_gate(
                warn!("Conditional-admission gate: closed / ME pool is NOT ready)");
            }

-            let pool_for_gate = pool.clone();
+            let mut pool_for_gate = initial_pool;
+            let pool_runtime_for_gate = me_pool_runtime.clone();
            let admission_tx_gate = admission_tx.clone();
            let route_runtime_gate = route_runtime.clone();
            let mut config_rx_gate = config_rx.clone();
+            let mut me_ready_rx_gate = me_ready_rx;
            let mut admission_poll_ms = config.general.me_admission_poll_ms.max(1);
            tokio::spawn(async move {
                let mut gate_open = initial_gate_open;
@@ -74,14 +85,34 @@ pub(crate) async fn configure_admission_gate(
                            fast_fallback_enabled = cfg.general.me2dc_fallback && cfg.general.me2dc_fast;
                            continue;
                        }
+                        changed = me_ready_rx_gate.changed() => {
+                            if changed.is_err() {
+                                break;
+                            }
+                        }
                        _ = tokio::time::sleep(Duration::from_millis(admission_poll_ms)) => {}
                    }
-                    let ready = pool_for_gate.admission_ready_conditional_cast().await;
+                    if pool_for_gate.is_none() {
+                        pool_for_gate = pool_runtime_for_gate.read().await.clone();
+                    }
+                    let ready = match pool_for_gate.as_ref() {
+                        Some(pool) => pool.admission_ready_conditional_cast().await,
+                        None => false,
+                    };
                    let now = Instant::now();
                    let (next_gate_open, next_route_mode, next_fallback_reason) = if ready {
                        ready_observed = true;
                        not_ready_since = None;
+                        if let Some(pool) = pool_for_gate.as_ref() {
+                            pool.set_runtime_ready(true);
+                        }
                        (true, RelayRouteMode::Middle, None)
+                    } else if fallback_enabled && !ready_observed {
+                        (
+                            true,
+                            RelayRouteMode::Direct,
+                            Some("startup_direct_fallback"),
+                        )
                    } else if fast_fallback_enabled {
                        (
                            true,
@@ -115,7 +146,14 @@ pub(crate) async fn configure_admission_gate(
                                );
                            } else {
                                let fallback_reason = next_fallback_reason.unwrap_or("unknown");
-                                if fallback_reason == "strict_grace_fallback" {
+                                if fallback_reason == "startup_direct_fallback" {
+                                    warn!(
+                                        target_mode = route_mode.as_str(),
+                                        cutover_generation = snapshot.generation,
+                                        fallback_reason,
+                                        "ME pool not-ready during startup; routing new sessions via Direct-DC"
+                                    );
+                                } else if fallback_reason == "strict_grace_fallback" {
                                    let fallback_after = if ready_observed {
                                        RUNTIME_FALLBACK_AFTER
                                    } else {
@@ -1,6 +1,6 @@
 #![allow(clippy::items_after_test_module)]

-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::time::Duration;

 use tokio::sync::watch;
@@ -15,9 +15,16 @@ use crate::transport::middle_proxy::{
    save_proxy_config_cache,
 };

+const MAESTRO_COLOR: &str = "\x1b[92m";
+const COLOR_RESET: &str = "\x1b[0m";
+
+pub(crate) fn print_maestro_line(message: impl AsRef<str>) {
+    eprintln!("{MAESTRO_COLOR}MAESTRO{COLOR_RESET}: {}", message.as_ref());
+}
+
 pub(crate) fn resolve_runtime_config_path(
    config_path_cli: &str,
-    startup_cwd: &std::path::Path,
+    startup_cwd: &Path,
    config_path_explicit: bool,
 ) -> PathBuf {
    if config_path_explicit {
@@ -46,6 +53,39 @@ pub(crate) fn resolve_runtime_config_path(
    startup_cwd.join("config.toml")
 }

+pub(crate) fn resolve_runtime_base_dir(
+    config_path: &Path,
+    startup_cwd: &Path,
+    config_path_explicit: bool,
+    data_path: Option<&Path>,
+) -> PathBuf {
+    if let Some(path) = data_path {
+        return normalize_runtime_dir(path, startup_cwd);
+    }
+
+    if startup_cwd != Path::new("/") {
+        return normalize_runtime_dir(startup_cwd, startup_cwd);
+    }
+
+    if config_path_explicit
+        && let Some(parent) = config_path.parent()
+        && !parent.as_os_str().is_empty()
+    {
+        return normalize_runtime_dir(parent, startup_cwd);
+    }
+
+    PathBuf::from("/etc/telemt")
+}
+
+fn normalize_runtime_dir(path: &Path, startup_cwd: &Path) -> PathBuf {
+    let absolute = if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        startup_cwd.join(path)
+    };
+    absolute.canonicalize().unwrap_or(absolute)
+}
+
 /// Parsed CLI arguments.
 pub(crate) struct CliArgs {
    pub config_path: String,
@@ -231,7 +271,13 @@ fn print_help() {

 #[cfg(test)]
 mod tests {
-    use super::resolve_runtime_config_path;
+    use std::path::{Path, PathBuf};
+
+    use super::{
+        expected_handshake_close_description, is_expected_handshake_eof, peer_close_description,
+        resolve_runtime_base_dir, resolve_runtime_config_path,
+    };
+    use crate::error::{ProxyError, StreamError};

    #[test]
    fn resolve_runtime_config_path_anchors_relative_to_startup_cwd() {
@@ -299,10 +345,170 @@ mod tests {

        let _ = std::fs::remove_dir(&startup_cwd);
    }
+
+    #[test]
+    fn resolve_runtime_base_dir_prefers_cli_data_path() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd = std::env::temp_dir().join(format!("telemt_runtime_base_cwd_{nonce}"));
+        let data_path = std::env::temp_dir().join(format!("telemt_runtime_base_data_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+        std::fs::create_dir_all(&data_path).unwrap();
+
+        let resolved = resolve_runtime_base_dir(
+            &startup_cwd.join("config.toml"),
+            &startup_cwd,
+            true,
+            Some(&data_path),
+        );
+        assert_eq!(resolved, data_path.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&data_path);
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_uses_working_directory_before_explicit_config_parent() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd = std::env::temp_dir().join(format!("telemt_runtime_base_start_{nonce}"));
+        let config_dir = std::env::temp_dir().join(format!("telemt_runtime_base_cfg_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+        std::fs::create_dir_all(&config_dir).unwrap();
+
+        let resolved =
+            resolve_runtime_base_dir(&config_dir.join("telemt.toml"), &startup_cwd, true, None);
+        assert_eq!(resolved, startup_cwd.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&config_dir);
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_uses_explicit_config_parent_from_root() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let config_dir = std::env::temp_dir().join(format!("telemt_runtime_base_root_cfg_{nonce}"));
+        std::fs::create_dir_all(&config_dir).unwrap();
+
+        let resolved =
+            resolve_runtime_base_dir(&config_dir.join("telemt.toml"), Path::new("/"), true, None);
+        assert_eq!(resolved, config_dir.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&config_dir);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_uses_systemd_working_directory_before_etc() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let startup_cwd = std::env::temp_dir().join(format!("telemt_runtime_base_systemd_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+
+        let resolved =
+            resolve_runtime_base_dir(&startup_cwd.join("config.toml"), &startup_cwd, false, None);
+        assert_eq!(resolved, startup_cwd.canonicalize().unwrap());
+
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_base_dir_falls_back_to_etc_from_root() {
+        let resolved = resolve_runtime_base_dir(
+            Path::new("/etc/telemt/config.toml"),
+            Path::new("/"),
+            false,
+            None,
+        );
+        assert_eq!(resolved, PathBuf::from("/etc/telemt"));
+    }
+
+    #[test]
+    fn expected_handshake_eof_matches_connection_reset() {
+        let err = ProxyError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionReset));
+        assert!(is_expected_handshake_eof(&err));
+    }
+
+    #[test]
+    fn expected_handshake_eof_matches_stream_io_unexpected_eof() {
+        let err = ProxyError::Stream(StreamError::Io(std::io::Error::from(
+            std::io::ErrorKind::UnexpectedEof,
+        )));
+        assert!(is_expected_handshake_eof(&err));
+    }
+
+    #[test]
+    fn peer_close_description_is_human_readable_for_all_peer_close_kinds() {
+        let cases = [
+            (
+                std::io::ErrorKind::ConnectionReset,
+                "Peer reset TCP connection (RST)",
+            ),
+            (
+                std::io::ErrorKind::ConnectionAborted,
+                "Peer aborted TCP connection during transport",
+            ),
+            (
+                std::io::ErrorKind::BrokenPipe,
+                "Peer closed write side (broken pipe)",
+            ),
+            (
+                std::io::ErrorKind::NotConnected,
+                "Socket was already closed by peer",
+            ),
+        ];
+
+        for (kind, expected) in cases {
+            let err = ProxyError::Io(std::io::Error::from(kind));
+            assert_eq!(peer_close_description(&err), Some(expected));
+        }
+    }
+
+    #[test]
+    fn handshake_close_description_is_human_readable_for_all_expected_kinds() {
+        let cases = [
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::UnexpectedEof)),
+                "Peer closed before sending full 64-byte MTProto handshake",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionReset)),
+                "Peer reset TCP connection during initial MTProto handshake",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionAborted)),
+                "Peer aborted TCP connection during initial MTProto handshake",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::BrokenPipe)),
+                "Peer closed write side before MTProto handshake completed",
+            ),
+            (
+                ProxyError::Io(std::io::Error::from(std::io::ErrorKind::NotConnected)),
+                "Handshake socket was already closed by peer",
+            ),
+            (
+                ProxyError::Stream(StreamError::UnexpectedEof),
+                "Peer closed before sending full 64-byte MTProto handshake",
+            ),
+        ];
+
+        for (err, expected) in cases {
+            assert_eq!(expected_handshake_close_description(&err), Some(expected));
+        }
+    }
 }

 pub(crate) fn print_proxy_links(host: &str, port: u16, config: &ProxyConfig) {
-    info!(target: "telemt::links", "--- Proxy Links ({}) ---", host);
+    print_maestro_line(format!("Proxy links ({host})"));
    for user_name in config
        .general
        .links
@@ -310,20 +516,16 @@ pub(crate) fn print_proxy_links(host: &str, port: u16, config: &ProxyConfig) {
        .resolve_users(&config.access.users)
    {
        if let Some(secret) = config.access.users.get(user_name) {
-            info!(target: "telemt::links", "User: {}", user_name);
+            print_maestro_line(format!("User: {user_name}"));
            if config.general.modes.classic {
-                info!(
-                    target: "telemt::links",
-                    "  Classic: tg://proxy?server={}&port={}&secret={}",
-                    host, port, secret
-                );
+                print_maestro_line(format!(
+                    "Classic: tg://proxy?server={host}&port={port}&secret={secret}"
+                ));
            }
            if config.general.modes.secure {
-                info!(
-                    target: "telemt::links",
-                    "  DD:      tg://proxy?server={}&port={}&secret=dd{}",
-                    host, port, secret
-                );
+                print_maestro_line(format!(
+                    "DD: tg://proxy?server={host}&port={port}&secret=dd{secret}"
+                ));
            }
            if config.general.modes.tls {
                let mut domains = Vec::with_capacity(1 + config.censorship.tls_domains.len());
@@ -336,18 +538,15 @@ pub(crate) fn print_proxy_links(host: &str, port: u16, config: &ProxyConfig) {

                for domain in domains {
                    let domain_hex = hex::encode(&domain);
-                    info!(
-                        target: "telemt::links",
-                        "  EE-TLS:  tg://proxy?server={}&port={}&secret=ee{}{}",
-                        host, port, secret, domain_hex
-                    );
+                    print_maestro_line(format!(
+                        "EE-TLS: tg://proxy?server={host}&port={port}&secret=ee{secret}{domain_hex}"
+                    ));
                }
            }
        } else {
            warn!(target: "telemt::links", "User '{}' in show_link not found", user_name);
        }
    }
-    info!(target: "telemt::links", "------------------------");
 }

 pub(crate) async fn write_beobachten_snapshot(path: &str, payload: &str) -> std::io::Result<()> {
@@ -428,7 +627,63 @@ pub(crate) async fn wait_until_admission_open(admission_rx: &mut watch::Receiver
 }

 pub(crate) fn is_expected_handshake_eof(err: &crate::error::ProxyError) -> bool {
-    err.to_string().contains("expected 64 bytes, got 0")
+    expected_handshake_close_description(err).is_some()
+}
+
+pub(crate) fn peer_close_description(err: &crate::error::ProxyError) -> Option<&'static str> {
+    fn from_kind(kind: std::io::ErrorKind) -> Option<&'static str> {
+        match kind {
+            std::io::ErrorKind::ConnectionReset => Some("Peer reset TCP connection (RST)"),
+            std::io::ErrorKind::ConnectionAborted => {
+                Some("Peer aborted TCP connection during transport")
+            }
+            std::io::ErrorKind::BrokenPipe => Some("Peer closed write side (broken pipe)"),
+            std::io::ErrorKind::NotConnected => Some("Socket was already closed by peer"),
+            _ => None,
+        }
+    }
+
+    match err {
+        crate::error::ProxyError::Io(ioe) => from_kind(ioe.kind()),
+        crate::error::ProxyError::Stream(crate::error::StreamError::Io(ioe)) => {
+            from_kind(ioe.kind())
+        }
+        _ => None,
+    }
+}
+
+pub(crate) fn expected_handshake_close_description(
+    err: &crate::error::ProxyError,
+) -> Option<&'static str> {
+    fn from_kind(kind: std::io::ErrorKind) -> Option<&'static str> {
+        match kind {
+            std::io::ErrorKind::UnexpectedEof => {
+                Some("Peer closed before sending full 64-byte MTProto handshake")
+            }
+            std::io::ErrorKind::ConnectionReset => {
+                Some("Peer reset TCP connection during initial MTProto handshake")
+            }
+            std::io::ErrorKind::ConnectionAborted => {
+                Some("Peer aborted TCP connection during initial MTProto handshake")
+            }
+            std::io::ErrorKind::BrokenPipe => {
+                Some("Peer closed write side before MTProto handshake completed")
+            }
+            std::io::ErrorKind::NotConnected => Some("Handshake socket was already closed by peer"),
+            _ => None,
+        }
+    }
+
+    match err {
+        crate::error::ProxyError::Io(ioe) => from_kind(ioe.kind()),
+        crate::error::ProxyError::Stream(crate::error::StreamError::UnexpectedEof) => {
+            Some("Peer closed before sending full 64-byte MTProto handshake")
+        }
+        crate::error::ProxyError::Stream(crate::error::StreamError::Io(ioe)) => {
+            from_kind(ioe.kind())
+        }
+        _ => None,
+    }
 }

 pub(crate) async fn load_startup_proxy_config_snapshot(
@@ -6,14 +6,14 @@ use std::time::Duration;
 use tokio::net::TcpListener;
 #[cfg(unix)]
 use tokio::net::UnixListener;
-use tokio::sync::{Semaphore, watch};
+use tokio::sync::{RwLock, Semaphore, watch};
 use tracing::{debug, error, info, warn};

 use crate::config::{ProxyConfig, RstOnCloseMode};
 use crate::crypto::SecureRandom;
 use crate::ip_tracker::UserIpTracker;
 use crate::proxy::ClientHandler;
-use crate::proxy::route_mode::{ROUTE_SWITCH_ERROR_MSG, RouteRuntimeController};
+use crate::proxy::route_mode::RouteRuntimeController;
 use crate::proxy::shared_state::ProxySharedState;
 use crate::startup::{COMPONENT_LISTENERS_BIND, StartupTracker};
 use crate::stats::beobachten::BeobachtenStore;
@@ -24,13 +24,29 @@ use crate::transport::middle_proxy::MePool;
 use crate::transport::socket::set_linger_zero;
 use crate::transport::{ListenOptions, UpstreamManager, create_listener, find_listener_processes};

-use super::helpers::{is_expected_handshake_eof, print_proxy_links};
+use super::helpers::{
+    expected_handshake_close_description, is_expected_handshake_eof, peer_close_description,
+    print_proxy_links,
+};

 pub(crate) struct BoundListeners {
    pub(crate) listeners: Vec<(TcpListener, bool)>,
    pub(crate) has_unix_listener: bool,
 }

+fn listener_port_or_legacy(listener: &crate::config::ListenerConfig, config: &ProxyConfig) -> u16 {
+    listener.port.unwrap_or(config.server.port)
+}
+
+fn default_link_port(config: &ProxyConfig) -> u16 {
+    config
+        .server
+        .listeners
+        .first()
+        .and_then(|listener| listener.port)
+        .unwrap_or(config.server.port)
+}
+
 #[allow(clippy::too_many_arguments)]
 pub(crate) async fn bind_listeners(
    config: &Arc<ProxyConfig>,
@@ -47,6 +63,7 @@ pub(crate) async fn bind_listeners(
    buffer_pool: Arc<BufferPool>,
    rng: Arc<SecureRandom>,
    me_pool: Option<Arc<MePool>>,
+    me_pool_runtime: Arc<RwLock<Option<Arc<MePool>>>>,
    route_runtime: Arc<RouteRuntimeController>,
    tls_cache: Option<Arc<TlsFrontCache>>,
    ip_tracker: Arc<UserIpTracker>,
@@ -63,7 +80,8 @@ pub(crate) async fn bind_listeners(
    let mut listeners = Vec::new();

    for listener_conf in &config.server.listeners {
-        let addr = SocketAddr::new(listener_conf.ip, config.server.port);
+        let listener_port = listener_port_or_legacy(listener_conf, config);
+        let addr = SocketAddr::new(listener_conf.ip, listener_port);
        if addr.is_ipv4() && !decision_ipv4_dc {
            warn!(%addr, "Skipping IPv4 listener: IPv4 disabled by [network]");
            continue;
@@ -106,11 +124,7 @@ pub(crate) async fn bind_listeners(
                if config.general.links.public_host.is_none()
                    && !config.general.links.show.is_empty()
                {
-                    let link_port = config
-                        .general
-                        .links
-                        .public_port
-                        .unwrap_or(config.server.port);
+                    let link_port = config.general.links.public_port.unwrap_or(listener_port);
                    print_proxy_links(&public_host, link_port, config);
                }

@@ -158,7 +172,7 @@ pub(crate) async fn bind_listeners(
                    .general
                    .links
                    .public_port
-                    .unwrap_or(config.server.port),
+                    .unwrap_or(default_link_port(config)),
            )
        } else {
            let ip = detected_ip_v4.or(detected_ip_v6).map(|ip| ip.to_string());
@@ -173,7 +187,7 @@ pub(crate) async fn bind_listeners(
                    .general
                    .links
                    .public_port
-                    .unwrap_or(config.server.port),
+                    .unwrap_or(default_link_port(config)),
            )
        };

@@ -223,6 +237,7 @@ pub(crate) async fn bind_listeners(
        let buffer_pool = buffer_pool.clone();
        let rng = rng.clone();
        let me_pool = me_pool.clone();
+        let me_pool_runtime = me_pool_runtime.clone();
        let route_runtime = route_runtime.clone();
        let tls_cache = tls_cache.clone();
        let ip_tracker = ip_tracker.clone();
@@ -285,6 +300,7 @@ pub(crate) async fn bind_listeners(
                        let buffer_pool = buffer_pool.clone();
                        let rng = rng.clone();
                        let me_pool = me_pool.clone();
+                        let me_pool_runtime = me_pool_runtime.clone();
                        let route_runtime = route_runtime.clone();
                        let tls_cache = tls_cache.clone();
                        let ip_tracker = ip_tracker.clone();
@@ -294,7 +310,8 @@ pub(crate) async fn bind_listeners(

                        tokio::spawn(async move {
                            let _permit = permit;
-                            if let Err(e) = crate::proxy::client::handle_client_stream_with_shared(
+                            if let Err(e) =
+                                crate::proxy::client::handle_client_stream_with_shared_and_pool_runtime(
                                stream,
                                fake_peer,
                                config,
@@ -304,6 +321,7 @@ pub(crate) async fn bind_listeners(
                                buffer_pool,
                                rng,
                                me_pool,
+                                Some(me_pool_runtime),
                                route_runtime,
                                tls_cache,
                                ip_tracker,
@@ -354,6 +372,7 @@ pub(crate) fn spawn_tcp_accept_loops(
    buffer_pool: Arc<BufferPool>,
    rng: Arc<SecureRandom>,
    me_pool: Option<Arc<MePool>>,
+    me_pool_runtime: Arc<RwLock<Option<Arc<MePool>>>>,
    route_runtime: Arc<RouteRuntimeController>,
    tls_cache: Option<Arc<TlsFrontCache>>,
    ip_tracker: Arc<UserIpTracker>,
@@ -370,6 +389,7 @@ pub(crate) fn spawn_tcp_accept_loops(
        let buffer_pool = buffer_pool.clone();
        let rng = rng.clone();
        let me_pool = me_pool.clone();
+        let me_pool_runtime = me_pool_runtime.clone();
        let route_runtime = route_runtime.clone();
        let tls_cache = tls_cache.clone();
        let ip_tracker = ip_tracker.clone();
@@ -436,6 +456,7 @@ pub(crate) fn spawn_tcp_accept_loops(
                        let buffer_pool = buffer_pool.clone();
                        let rng = rng.clone();
                        let me_pool = me_pool.clone();
+                        let me_pool_runtime = me_pool_runtime.clone();
                        let route_runtime = route_runtime.clone();
                        let tls_cache = tls_cache.clone();
                        let ip_tracker = ip_tracker.clone();
@@ -457,6 +478,7 @@ pub(crate) fn spawn_tcp_accept_loops(
                                buffer_pool,
                                rng,
                                me_pool,
+                                Some(me_pool_runtime),
                                route_runtime,
                                tls_cache,
                                ip_tracker,
@@ -475,45 +497,32 @@ pub(crate) fn spawn_tcp_accept_loops(
                                    Ok(guard) => *guard,
                                    Err(_) => None,
                                };
-                                let peer_closed = matches!(
-                                    &e,
-                                    crate::error::ProxyError::Io(ioe)
-                                        if matches!(
-                                            ioe.kind(),
-                                            std::io::ErrorKind::ConnectionReset
-                                                | std::io::ErrorKind::ConnectionAborted
-                                                | std::io::ErrorKind::BrokenPipe
-                                                | std::io::ErrorKind::NotConnected
-                                        )
-                                ) || matches!(
-                                    &e,
-                                    crate::error::ProxyError::Stream(
-                                        crate::error::StreamError::Io(ioe)
-                                    )
-                                        if matches!(
-                                            ioe.kind(),
-                                            std::io::ErrorKind::ConnectionReset
-                                                | std::io::ErrorKind::ConnectionAborted
-                                                | std::io::ErrorKind::BrokenPipe
-                                                | std::io::ErrorKind::NotConnected
-                                        )
-                                );
+                                let peer_close_reason = peer_close_description(&e);
+                                let handshake_close_reason =
+                                    expected_handshake_close_description(&e);

-                                let me_closed = matches!(
-                                    &e,
-                                    crate::error::ProxyError::Proxy(msg) if msg == "ME connection lost"
-                                );
-                                let route_switched = matches!(
-                                    &e,
-                                    crate::error::ProxyError::Proxy(msg) if msg == ROUTE_SWITCH_ERROR_MSG
-                                );
+                                let me_closed =
+                                    matches!(&e, crate::error::ProxyError::MiddleConnectionLost);
+                                let route_switched =
+                                    matches!(&e, crate::error::ProxyError::RouteSwitched);

-                                match (peer_closed, me_closed) {
-                                    (true, _) => {
+                                match (peer_close_reason, me_closed) {
+                                    (Some(reason), _) => {
                                        if let Some(real_peer) = real_peer {
-                                            debug!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed by client");
+                                            debug!(
+                                                peer = %peer_addr,
+                                                real_peer = %real_peer,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed by peer"
+                                            );
                                        } else {
-                                            debug!(peer = %peer_addr, error = %e, "Connection closed by client");
+                                            debug!(
+                                                peer = %peer_addr,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed by peer"
+                                            );
                                        }
                                    }
                                    (_, true) => {
@@ -531,10 +540,23 @@ pub(crate) fn spawn_tcp_accept_loops(
                                        }
                                    }
                                    _ if is_expected_handshake_eof(&e) => {
+                                        let reason = handshake_close_reason
+                                            .unwrap_or("Peer closed during initial handshake");
                                        if let Some(real_peer) = real_peer {
-                                            info!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed during initial handshake");
+                                            info!(
+                                                peer = %peer_addr,
+                                                real_peer = %real_peer,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed during initial handshake"
+                                            );
                                        } else {
-                                            info!(peer = %peer_addr, error = %e, "Connection closed during initial handshake");
+                                            info!(
+                                                peer = %peer_addr,
+                                                error = %e,
+                                                close_reason = reason,
+                                                "Connection closed during initial handshake"
+                                            );
                                        }
                                    }
                                    _ => {
@@ -3,7 +3,7 @@
 use std::sync::Arc;
 use std::time::Duration;

-use tokio::sync::RwLock;
+use tokio::sync::{RwLock, watch};
 use tracing::{error, info, warn};

 use crate::config::ProxyConfig;
@@ -29,6 +29,7 @@ pub(crate) async fn initialize_me_pool(
    rng: Arc<SecureRandom>,
    stats: Arc<Stats>,
    api_me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+    me_ready_tx: watch::Sender<u64>,
 ) -> Option<Arc<MePool>> {
    if !use_middle_proxy {
        return None;
@@ -66,6 +67,7 @@ pub(crate) async fn initialize_me_pool(
        match crate::transport::middle_proxy::fetch_proxy_secret_with_upstream(
            proxy_secret_path,
            config.general.proxy_secret_len_max,
+            config.general.proxy_secret_url.as_deref(),
            Some(upstream_manager.clone()),
        )
        .await
@@ -126,7 +128,11 @@ pub(crate) async fn initialize_me_pool(
                .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_PROXY_CONFIG_V4)
                .await;
            let cfg_v4 = load_startup_proxy_config_snapshot(
-                "https://core.telegram.org/getProxyConfig",
+                config
+                    .general
+                    .proxy_config_v4_url
+                    .as_deref()
+                    .unwrap_or("https://core.telegram.org/getProxyConfig"),
                config.general.proxy_config_v4_cache_path.as_deref(),
                me2dc_fallback,
                "getProxyConfig",
@@ -158,7 +164,11 @@ pub(crate) async fn initialize_me_pool(
                .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_PROXY_CONFIG_V6)
                .await;
            let cfg_v6 = load_startup_proxy_config_snapshot(
-                "https://core.telegram.org/getProxyConfigV6",
+                config
+                    .general
+                    .proxy_config_v6_url
+                    .as_deref()
+                    .unwrap_or("https://core.telegram.org/getProxyConfigV6"),
                config.general.proxy_config_v6_cache_path.as_deref(),
                me2dc_fallback,
                "getProxyConfigV6",
@@ -268,6 +278,8 @@ pub(crate) async fn initialize_me_pool(
                    config.general.me_socks_kdf_policy,
                    config.general.me_writer_cmd_channel_capacity,
                    config.general.me_route_channel_capacity,
+                    config.general.me_route_backpressure_enabled,
+                    config.general.me_route_fairshare_enabled,
                    config.general.me_route_backpressure_base_timeout_ms,
                    config.general.me_route_backpressure_high_timeout_ms,
                    config.general.me_route_backpressure_high_watermark_pct,
@@ -303,6 +315,7 @@ pub(crate) async fn initialize_me_pool(
                    let pool_bg = pool.clone();
                    let rng_bg = rng.clone();
                    let startup_tracker_bg = startup_tracker.clone();
+                    let me_ready_tx_bg = me_ready_tx.clone();
                    let retry_limit = if me_init_retry_attempts == 0 {
                        String::from("unlimited")
                    } else {
@@ -336,6 +349,9 @@ pub(crate) async fn initialize_me_pool(
                                        startup_tracker_bg
                                            .set_me_status(StartupMeStatus::Ready, "ready")
                                            .await;
+                                        me_ready_tx_bg.send_modify(|version| {
+                                            *version = version.saturating_add(1);
+                                        });
                                        info!(
                                            attempt = init_attempt,
                                            "Middle-End pool initialized successfully"
@@ -463,6 +479,9 @@ pub(crate) async fn initialize_me_pool(
                                startup_tracker
                                    .set_me_status(StartupMeStatus::Ready, "ready")
                                    .await;
+                                me_ready_tx.send_modify(|version| {
+                                    *version = version.saturating_add(1);
+                                });
                                info!(
                                    attempt = init_attempt,
                                    "Middle-End pool initialized successfully"
@@ -36,10 +36,10 @@ use crate::network::probe::{decide_network_capabilities, log_probe_result, run_p
 use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
 use crate::proxy::shared_state::ProxySharedState;
 use crate::startup::{
-    COMPONENT_API_BOOTSTRAP, COMPONENT_CONFIG_LOAD, COMPONENT_ME_POOL_CONSTRUCT,
-    COMPONENT_ME_POOL_INIT_STAGE1, COMPONENT_ME_PROXY_CONFIG_V4, COMPONENT_ME_PROXY_CONFIG_V6,
-    COMPONENT_ME_SECRET_FETCH, COMPONENT_NETWORK_PROBE, COMPONENT_TRACING_INIT, StartupMeStatus,
-    StartupTracker,
+    COMPONENT_API_BOOTSTRAP, COMPONENT_CONFIG_LOAD, COMPONENT_DC_CONNECTIVITY_PING,
+    COMPONENT_ME_CONNECTIVITY_PING, COMPONENT_ME_POOL_CONSTRUCT, COMPONENT_ME_POOL_INIT_STAGE1,
+    COMPONENT_ME_PROXY_CONFIG_V4, COMPONENT_ME_PROXY_CONFIG_V6, COMPONENT_ME_SECRET_FETCH,
+    COMPONENT_NETWORK_PROBE, COMPONENT_TRACING_INIT, StartupMeStatus, StartupTracker,
 };
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::telemetry::TelemetryPolicy;
@@ -47,7 +47,9 @@ use crate::stats::{ReplayChecker, Stats};
 use crate::stream::BufferPool;
 use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::MePool;
-use helpers::{parse_cli, resolve_runtime_config_path};
+use helpers::{
+    parse_cli, print_maestro_line, resolve_runtime_base_dir, resolve_runtime_config_path,
+};

 #[cfg(unix)]
 use crate::daemon::{DaemonOptions, PidFile, drop_privileges};
@@ -81,23 +83,11 @@ pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
    }
 }

-#[cfg(unix)]
-async fn run_inner(
-    daemon_opts: DaemonOptions,
+// Shared maestro startup and main loop. `drop_after_bind` runs on Unix after listeners are bound
+// (for privilege drop); it is a no-op on other platforms.
+async fn run_telemt_core(
+    drop_after_bind: impl FnOnce(),
 ) -> std::result::Result<(), Box<dyn std::error::Error>> {
-    // Acquire PID file if daemonizing or if explicitly requested
-    // Keep it alive until shutdown (underscore prefix = intentionally kept for RAII cleanup)
-    let _pid_file = if daemon_opts.daemonize || daemon_opts.pid_file.is_some() {
-        let mut pf = PidFile::new(daemon_opts.pid_file_path());
-        if let Err(e) = pf.acquire() {
-            eprintln!("[telemt] {}", e);
-            std::process::exit(1);
-        }
-        Some(pf)
-    } else {
-        None
-    };
-
    let process_started_at = Instant::now();
    let process_started_at_epoch_secs = SystemTime::now()
        .duration_since(UNIX_EPOCH)
@@ -124,8 +114,51 @@ async fn run_inner(
            std::process::exit(1);
        }
    };
+    if let Some(ref data_path) = data_path
+        && !data_path.is_absolute()
+    {
+        eprintln!(
+            "[telemt] data_path must be absolute: {}",
+            data_path.display()
+        );
+        std::process::exit(1);
+    }
    let mut config_path =
        resolve_runtime_config_path(&config_path_cli, &startup_cwd, config_path_explicit);
+    let runtime_base_dir = resolve_runtime_base_dir(
+        &config_path,
+        &startup_cwd,
+        config_path_explicit,
+        data_path.as_deref(),
+    );
+
+    if !runtime_base_dir.exists()
+        && let Err(e) = std::fs::create_dir_all(&runtime_base_dir)
+    {
+        eprintln!(
+            "[telemt] Can't create runtime directory {}: {}",
+            runtime_base_dir.display(),
+            e
+        );
+        std::process::exit(1);
+    }
+
+    if !runtime_base_dir.is_dir() {
+        eprintln!(
+            "[telemt] Runtime path exists but is not a directory: {}",
+            runtime_base_dir.display()
+        );
+        std::process::exit(1);
+    }
+
+    if let Err(e) = std::env::set_current_dir(&runtime_base_dir) {
+        eprintln!(
+            "[telemt] Can't use runtime directory {}: {}",
+            runtime_base_dir.display(),
+            e
+        );
+        std::process::exit(1);
+    }

    let mut config = match ProxyConfig::load(&config_path) {
        Ok(c) => c,
@@ -168,16 +201,15 @@ async fn run_inner(
                        );
                    }
                } else {
-                    let system_dir = std::path::Path::new("/etc/telemt");
-                    let system_config_path = system_dir.join("telemt.toml");
-                    let startup_config_path = startup_cwd.join("config.toml");
+                    let runtime_config_path = runtime_base_dir.join("telemt.toml");
+                    let fallback_config_path = runtime_base_dir.join("config.toml");
                    let mut persisted = false;

                    if let Some(serialized) = serialized.as_ref() {
-                        match std::fs::create_dir_all(system_dir) {
-                            Ok(()) => match std::fs::write(&system_config_path, serialized) {
+                        match std::fs::create_dir_all(&runtime_base_dir) {
+                            Ok(()) => match std::fs::write(&runtime_config_path, serialized) {
                                Ok(()) => {
-                                    config_path = system_config_path;
+                                    config_path = runtime_config_path;
                                    eprintln!(
                                        "[telemt] Created default config at {}",
                                        config_path.display()
@@ -187,7 +219,7 @@ async fn run_inner(
                                Err(write_error) => {
                                    eprintln!(
                                        "[telemt] Warning: failed to write default config at {}: {}",
-                                        system_config_path.display(),
+                                        runtime_config_path.display(),
                                        write_error
                                    );
                                }
@@ -195,16 +227,16 @@ async fn run_inner(
                            Err(create_error) => {
                                eprintln!(
                                    "[telemt] Warning: failed to create {}: {}",
-                                    system_dir.display(),
+                                    runtime_base_dir.display(),
                                    create_error
                                );
                            }
                        }

                        if !persisted {
-                            match std::fs::write(&startup_config_path, serialized) {
+                            match std::fs::write(&fallback_config_path, serialized) {
                                Ok(()) => {
-                                    config_path = startup_config_path;
+                                    config_path = fallback_config_path;
                                    eprintln!(
                                        "[telemt] Created default config at {}",
                                        config_path.display()
@@ -214,7 +246,7 @@ async fn run_inner(
                                Err(write_error) => {
                                    eprintln!(
                                        "[telemt] Warning: failed to write default config at {}: {}",
-                                        startup_config_path.display(),
+                                        fallback_config_path.display(),
                                        write_error
                                    );
                                }
@@ -295,7 +327,9 @@ async fn run_inner(
        config.general.log_level.clone()
    };

-    let (filter_layer, filter_handle) = reload::Layer::new(EnvFilter::new("info"));
+    let initial_filter_spec = runtime_tasks::log_filter_spec(has_rust_log, &effective_log_level);
+    let (filter_layer, filter_handle) =
+        reload::Layer::new(EnvFilter::new(initial_filter_spec.clone()));
    startup_tracker
        .start_component(
            COMPONENT_TRACING_INIT,
@@ -326,7 +360,7 @@ async fn run_inner(
                destination: log_destination,
                disable_colors: true,
            };
-            let (_, guard) = crate::logging::init_logging(&logging_opts, "info");
+            let (_, guard) = crate::logging::init_logging(&logging_opts, &initial_filter_spec);
            _logging_guard = Some(guard);
        }
        crate::logging::LogDestination::File { .. } => {
@@ -335,7 +369,7 @@ async fn run_inner(
                destination: log_destination,
                disable_colors: true,
            };
-            let (_, guard) = crate::logging::init_logging(&logging_opts, "info");
+            let (_, guard) = crate::logging::init_logging(&logging_opts, &initial_filter_spec);
            _logging_guard = Some(guard);
        }
    }
@@ -347,7 +381,7 @@ async fn run_inner(
        )
        .await;

-    info!("Telemt MTProxy v{}", env!("CARGO_PKG_VERSION"));
+    print_maestro_line(format!("Telemt MTProxy v{}", env!("CARGO_PKG_VERSION")));
    info!("Log level: {}", effective_log_level);
    if config.general.disable_colors {
        info!("Colors: disabled");
@@ -387,6 +421,8 @@ async fn run_inner(

    let stats = Arc::new(Stats::new());
    stats.apply_telemetry_policy(TelemetryPolicy::from_config(&config.general.telemetry));
+    let quota_state_path = config.general.quota_state_path.clone();
+    crate::quota_state::load_quota_state(&quota_state_path, stats.as_ref()).await;

    let upstream_manager = Arc::new(UpstreamManager::new(
        config.upstreams.clone(),
@@ -429,12 +465,13 @@ async fn run_inner(

    let (api_config_tx, api_config_rx) = watch::channel(Arc::new(config.clone()));
    let (detected_ips_tx, detected_ips_rx) = watch::channel((None::<IpAddr>, None::<IpAddr>));
-    let initial_admission_open = !config.general.use_middle_proxy;
+    let initial_direct_first = config.general.use_middle_proxy && config.general.me2dc_fallback;
+    let initial_admission_open = !config.general.use_middle_proxy || initial_direct_first;
    let (admission_tx, admission_rx) = watch::channel(initial_admission_open);
-    let initial_route_mode = if config.general.use_middle_proxy {
-        RelayRouteMode::Middle
-    } else {
+    let initial_route_mode = if !config.general.use_middle_proxy || initial_direct_first {
        RelayRouteMode::Direct
+    } else {
+        RelayRouteMode::Middle
    };
    let route_runtime = Arc::new(RouteRuntimeController::new(initial_route_mode));
    let api_me_pool = Arc::new(RwLock::new(None::<Arc<MePool>>));
@@ -466,6 +503,7 @@ async fn run_inner(
            let config_rx_api = api_config_rx.clone();
            let admission_rx_api = admission_rx.clone();
            let config_path_api = config_path.clone();
+            let quota_state_path_api = quota_state_path.clone();
            let startup_tracker_api = startup_tracker.clone();
            let detected_ips_rx_api = detected_ips_rx.clone();
            tokio::spawn(async move {
@@ -479,6 +517,7 @@ async fn run_inner(
                    config_rx_api,
                    admission_rx_api,
                    config_path_api,
+                    quota_state_path_api,
                    detected_ips_rx_api,
                    process_started_at_epoch_secs,
                    startup_tracker_api,
@@ -568,8 +607,9 @@ async fn run_inner(
    let me_init_retry_attempts = config.general.me_init_retry_attempts;
    if use_middle_proxy && !decision.ipv4_me && !decision.ipv6_me {
        if me2dc_fallback {
-            warn!("No usable IP family for Middle Proxy detected; falling back to direct DC");
-            use_middle_proxy = false;
+            warn!(
+                "No usable IP family for Middle Proxy detected; Direct-DC startup fallback is active while ME init retries continue"
+            );
        } else {
            warn!(
                "No usable IP family for Middle Proxy detected; me2dc_fallback=false, ME init retries stay active"
@@ -630,21 +670,35 @@ async fn run_inner(
            .await;
    }

-    let me_pool: Option<Arc<MePool>> = me_startup::initialize_me_pool(
-        use_middle_proxy,
-        &config,
-        &decision,
-        &probe,
-        &startup_tracker,
-        upstream_manager.clone(),
-        rng.clone(),
-        stats.clone(),
-        api_me_pool.clone(),
-    )
-    .await;
+    let (me_ready_tx, me_ready_rx) = watch::channel(0_u64);
+    let direct_first_startup = use_middle_proxy && me2dc_fallback;
+
+    let me_pool: Option<Arc<MePool>> = if direct_first_startup {
+        None
+    } else {
+        me_startup::initialize_me_pool(
+            use_middle_proxy,
+            &config,
+            &decision,
+            &probe,
+            &startup_tracker,
+            upstream_manager.clone(),
+            rng.clone(),
+            stats.clone(),
+            api_me_pool.clone(),
+            me_ready_tx.clone(),
+        )
+        .await
+    };

    // If ME failed to initialize, force direct-only mode.
-    if me_pool.is_some() {
+    if direct_first_startup {
+        startup_tracker.set_transport_mode("direct").await;
+        startup_tracker.set_degraded(true).await;
+        info!(
+            "Transport: Direct DC startup fallback active; Middle-End bootstrap continues in background"
+        );
+    } else if me_pool.is_some() {
        startup_tracker.set_transport_mode("middle_proxy").await;
        startup_tracker.set_degraded(false).await;
        info!("Transport: Middle-End Proxy - all DC-over-RPC");
@@ -676,19 +730,39 @@ async fn run_inner(
    ));

    let buffer_pool = Arc::new(BufferPool::with_config(64 * 1024, 4096));
+    let shared_state = ProxySharedState::new();
+    shared_state.traffic_limiter.apply_policy(
+        config.access.user_rate_limits.clone(),
+        config.access.cidr_rate_limits.clone(),
+    );

-    connectivity::run_startup_connectivity(
-        &config,
-        &me_pool,
-        rng.clone(),
-        &startup_tracker,
-        upstream_manager.clone(),
-        prefer_ipv6,
-        &decision,
-        process_started_at,
-        api_me_pool.clone(),
-    )
-    .await;
+    if direct_first_startup {
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_CONNECTIVITY_PING,
+                Some("deferred by direct-first startup".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_DC_CONNECTIVITY_PING,
+                Some("background health checks active".to_string()),
+            )
+            .await;
+    } else {
+        connectivity::run_startup_connectivity(
+            &config,
+            &me_pool,
+            rng.clone(),
+            &startup_tracker,
+            upstream_manager.clone(),
+            prefer_ipv6,
+            &decision,
+            process_started_at,
+            api_me_pool.clone(),
+        )
+        .await;
+    }

    let runtime_watches = runtime_tasks::spawn_runtime_tasks(
        &config,
@@ -707,6 +781,8 @@ async fn run_inner(
        beobachten.clone(),
        api_config_tx.clone(),
        me_pool.clone(),
+        shared_state.clone(),
+        me_ready_tx.clone(),
    )
    .await;
    let config_rx = runtime_watches.config_rx;
@@ -714,16 +790,79 @@ async fn run_inner(
    let detected_ip_v4 = runtime_watches.detected_ip_v4;
    let detected_ip_v6 = runtime_watches.detected_ip_v6;

+    if direct_first_startup {
+        let config_bg = config.clone();
+        let decision_bg = decision.clone();
+        let probe_bg = probe.clone();
+        let startup_tracker_bg = startup_tracker.clone();
+        let upstream_manager_bg = upstream_manager.clone();
+        let rng_bg = rng.clone();
+        let stats_bg = stats.clone();
+        let api_me_pool_bg = api_me_pool.clone();
+        let me_ready_tx_bg = me_ready_tx.clone();
+        let config_rx_bg = config_rx.clone();
+        tokio::spawn(async move {
+            let mut bootstrap_attempt: u32 = 0;
+            loop {
+                bootstrap_attempt = bootstrap_attempt.saturating_add(1);
+                let pool = me_startup::initialize_me_pool(
+                    true,
+                    config_bg.as_ref(),
+                    &decision_bg,
+                    &probe_bg,
+                    &startup_tracker_bg,
+                    upstream_manager_bg.clone(),
+                    rng_bg.clone(),
+                    stats_bg.clone(),
+                    api_me_pool_bg.clone(),
+                    me_ready_tx_bg.clone(),
+                )
+                .await;
+                if let Some(pool) = pool {
+                    runtime_tasks::spawn_middle_proxy_runtime_tasks(
+                        config_bg.as_ref(),
+                        config_rx_bg,
+                        pool,
+                        rng_bg,
+                        me_ready_tx_bg,
+                    );
+                    break;
+                }
+                if me_init_retry_attempts > 0 && bootstrap_attempt >= me_init_retry_attempts {
+                    break;
+                }
+                tokio::time::sleep(Duration::from_secs(2)).await;
+            }
+        });
+
+        let startup_tracker_ready = startup_tracker.clone();
+        let api_me_pool_ready = api_me_pool.clone();
+        let mut me_ready_rx_transport = me_ready_tx.subscribe();
+        tokio::spawn(async move {
+            if me_ready_rx_transport.changed().await.is_ok() {
+                if let Some(pool) = api_me_pool_ready.read().await.as_ref() {
+                    pool.set_runtime_ready(true);
+                }
+                startup_tracker_ready
+                    .set_transport_mode("middle_proxy")
+                    .await;
+                startup_tracker_ready.set_degraded(false).await;
+                info!("Transport: Middle-End Proxy restored for new sessions");
+            }
+        });
+    }
+
    admission::configure_admission_gate(
        &config,
        me_pool.clone(),
+        api_me_pool.clone(),
        route_runtime.clone(),
        &admission_tx,
        config_rx.clone(),
+        me_ready_rx,
    )
    .await;
    let _admission_tx_hold = admission_tx;
-    let shared_state = ProxySharedState::new();
    conntrack_control::spawn_conntrack_controller(
        config_rx.clone(),
        stats.clone(),
@@ -745,6 +884,7 @@ async fn run_inner(
        buffer_pool.clone(),
        rng.clone(),
        me_pool.clone(),
+        api_me_pool.clone(),
        route_runtime.clone(),
        tls_cache.clone(),
        ip_tracker.clone(),
@@ -761,17 +901,8 @@ async fn run_inner(
        std::process::exit(1);
    }

-    // Drop privileges after binding sockets (which may require root for port < 1024)
-    if daemon_opts.user.is_some() || daemon_opts.group.is_some() {
-        if let Err(e) = drop_privileges(
-            daemon_opts.user.as_deref(),
-            daemon_opts.group.as_deref(),
-            _pid_file.as_ref(),
-        ) {
-            error!(error = %e, "Failed to drop privileges");
-            std::process::exit(1);
-        }
-    }
+    // On Unix, caller supplies privilege drop after bind (may require root for port < 1024).
+    drop_after_bind();

    runtime_tasks::apply_runtime_log_filter(
        has_rust_log,
@@ -788,6 +919,7 @@ async fn run_inner(
        beobachten.clone(),
        shared_state.clone(),
        ip_tracker.clone(),
+        tls_cache.clone(),
        config_rx.clone(),
    )
    .await;
@@ -807,6 +939,7 @@ async fn run_inner(
        buffer_pool.clone(),
        rng.clone(),
        me_pool.clone(),
+        api_me_pool.clone(),
        route_runtime.clone(),
        tls_cache.clone(),
        ip_tracker.clone(),
@@ -815,7 +948,43 @@ async fn run_inner(
        max_connections.clone(),
    );

-    shutdown::wait_for_shutdown(process_started_at, me_pool, stats).await;
+    shutdown::wait_for_shutdown(process_started_at, me_pool, stats, quota_state_path).await;

    Ok(())
 }
+
+#[cfg(unix)]
+async fn run_inner(
+    daemon_opts: DaemonOptions,
+) -> std::result::Result<(), Box<dyn std::error::Error>> {
+    // Acquire PID file if daemonizing or if explicitly requested
+    // Keep it alive until shutdown (underscore prefix = intentionally kept for RAII cleanup)
+    let _pid_file = if daemon_opts.daemonize || daemon_opts.pid_file.is_some() {
+        let mut pf = PidFile::new(daemon_opts.pid_file_path());
+        if let Err(e) = pf.acquire() {
+            eprintln!("[telemt] {}", e);
+            std::process::exit(1);
+        }
+        Some(pf)
+    } else {
+        None
+    };
+
+    let user = daemon_opts.user.clone();
+    let group = daemon_opts.group.clone();
+
+    run_telemt_core(|| {
+        if user.is_some() || group.is_some() {
+            if let Err(e) = drop_privileges(user.as_deref(), group.as_deref(), _pid_file.as_ref()) {
+                error!(error = %e, "Failed to drop privileges");
+                std::process::exit(1);
+            }
+        }
+    })
+    .await
+}
+
+#[cfg(not(unix))]
+async fn run_inner() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    run_telemt_core(|| {}).await
+}
@@ -21,6 +21,7 @@ use crate::startup::{
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::telemetry::TelemetryPolicy;
 use crate::stats::{ReplayChecker, Stats};
+use crate::tls_front::TlsFrontCache;
 use crate::transport::UpstreamManager;
 use crate::transport::middle_proxy::{MePool, MeReinitTrigger};

@@ -51,6 +52,8 @@ pub(crate) async fn spawn_runtime_tasks(
    beobachten: Arc<BeobachtenStore>,
    api_config_tx: watch::Sender<Arc<ProxyConfig>>,
    me_pool_for_policy: Option<Arc<MePool>>,
+    shared_state: Arc<ProxySharedState>,
+    me_ready_tx: watch::Sender<u64>,
 ) -> RuntimeWatches {
    let um_clone = upstream_manager.clone();
    let dc_overrides_for_health = config.dc_overrides.clone();
@@ -70,6 +73,18 @@ pub(crate) async fn spawn_runtime_tasks(
        rc_clone.run_periodic_cleanup().await;
    });

+    let stats_maintenance = stats.clone();
+    tokio::spawn(async move {
+        stats_maintenance
+            .run_periodic_user_stats_maintenance()
+            .await;
+    });
+
+    let ip_tracker_maintenance = ip_tracker.clone();
+    tokio::spawn(async move {
+        ip_tracker_maintenance.run_periodic_maintenance().await;
+    });
+
    let detected_ip_v4: Option<IpAddr> = probe.detected_ipv4.map(IpAddr::V4);
    let detected_ip_v6: Option<IpAddr> = probe.detected_ipv6.map(IpAddr::V6);
    debug!(
@@ -121,6 +136,8 @@ pub(crate) async fn spawn_runtime_tasks(
            if let Some(pool) = &me_pool_for_policy {
                pool.update_runtime_transport_policy(
                    cfg.general.me_socks_kdf_policy,
+                    cfg.general.me_route_backpressure_enabled,
+                    cfg.general.me_route_fairshare_enabled,
                    cfg.general.me_route_backpressure_base_timeout_ms,
                    cfg.general.me_route_backpressure_high_timeout_ms,
                    cfg.general.me_route_backpressure_high_watermark_pct,
@@ -182,6 +199,41 @@ pub(crate) async fn spawn_runtime_tasks(
        }
    });

+    let limiter = shared_state.traffic_limiter.clone();
+    limiter.apply_policy(
+        config.access.user_rate_limits.clone(),
+        config.access.cidr_rate_limits.clone(),
+    );
+    let mut config_rx_rate_limits = config_rx.clone();
+    tokio::spawn(async move {
+        let mut prev_user_limits = config_rx_rate_limits
+            .borrow()
+            .access
+            .user_rate_limits
+            .clone();
+        let mut prev_cidr_limits = config_rx_rate_limits
+            .borrow()
+            .access
+            .cidr_rate_limits
+            .clone();
+        loop {
+            if config_rx_rate_limits.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_rate_limits.borrow_and_update().clone();
+            if prev_user_limits != cfg.access.user_rate_limits
+                || prev_cidr_limits != cfg.access.cidr_rate_limits
+            {
+                limiter.apply_policy(
+                    cfg.access.user_rate_limits.clone(),
+                    cfg.access.cidr_rate_limits.clone(),
+                );
+                prev_user_limits = cfg.access.user_rate_limits.clone();
+                prev_cidr_limits = cfg.access.cidr_rate_limits.clone();
+            }
+        }
+    });
+
    let beobachten_writer = beobachten.clone();
    let config_rx_beobachten = config_rx.clone();
    tokio::spawn(async move {
@@ -205,43 +257,7 @@ pub(crate) async fn spawn_runtime_tasks(
    });

    if let Some(pool) = me_pool {
-        let reinit_trigger_capacity = config.general.me_reinit_trigger_channel.max(1);
-        let (reinit_tx, reinit_rx) = mpsc::channel::<MeReinitTrigger>(reinit_trigger_capacity);
-
-        let pool_clone_sched = pool.clone();
-        let rng_clone_sched = rng.clone();
-        let config_rx_clone_sched = config_rx.clone();
-        tokio::spawn(async move {
-            crate::transport::middle_proxy::me_reinit_scheduler(
-                pool_clone_sched,
-                rng_clone_sched,
-                config_rx_clone_sched,
-                reinit_rx,
-            )
-            .await;
-        });
-
-        let pool_clone = pool.clone();
-        let config_rx_clone = config_rx.clone();
-        let reinit_tx_updater = reinit_tx.clone();
-        tokio::spawn(async move {
-            crate::transport::middle_proxy::me_config_updater(
-                pool_clone,
-                config_rx_clone,
-                reinit_tx_updater,
-            )
-            .await;
-        });
-
-        let config_rx_clone_rot = config_rx.clone();
-        let reinit_tx_rotation = reinit_tx.clone();
-        tokio::spawn(async move {
-            crate::transport::middle_proxy::me_rotation_task(
-                config_rx_clone_rot,
-                reinit_tx_rotation,
-            )
-            .await;
-        });
+        spawn_middle_proxy_runtime_tasks(config, config_rx.clone(), pool, rng, me_ready_tx);
    }

    RuntimeWatches {
@@ -252,19 +268,58 @@ pub(crate) async fn spawn_runtime_tasks(
    }
 }

+pub(crate) fn spawn_middle_proxy_runtime_tasks(
+    config: &ProxyConfig,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    pool: Arc<MePool>,
+    rng: Arc<SecureRandom>,
+    me_ready_tx: watch::Sender<u64>,
+) {
+    let reinit_trigger_capacity = config.general.me_reinit_trigger_channel.max(1);
+    let (reinit_tx, reinit_rx) = mpsc::channel::<MeReinitTrigger>(reinit_trigger_capacity);
+
+    let pool_clone_sched = pool.clone();
+    let rng_clone_sched = rng.clone();
+    let config_rx_clone_sched = config_rx.clone();
+    let me_ready_tx_sched = me_ready_tx.clone();
+    tokio::spawn(async move {
+        crate::transport::middle_proxy::me_reinit_scheduler(
+            pool_clone_sched,
+            rng_clone_sched,
+            config_rx_clone_sched,
+            reinit_rx,
+            me_ready_tx_sched,
+        )
+        .await;
+    });
+
+    let pool_clone = pool.clone();
+    let config_rx_clone = config_rx.clone();
+    let reinit_tx_updater = reinit_tx.clone();
+    tokio::spawn(async move {
+        crate::transport::middle_proxy::me_config_updater(
+            pool_clone,
+            config_rx_clone,
+            reinit_tx_updater,
+        )
+        .await;
+    });
+
+    let config_rx_clone_rot = config_rx.clone();
+    let reinit_tx_rotation = reinit_tx.clone();
+    tokio::spawn(async move {
+        crate::transport::middle_proxy::me_rotation_task(config_rx_clone_rot, reinit_tx_rotation)
+            .await;
+    });
+}
+
 pub(crate) async fn apply_runtime_log_filter(
    has_rust_log: bool,
    effective_log_level: &LogLevel,
    filter_handle: reload::Handle<EnvFilter, tracing_subscriber::Registry>,
    mut log_level_rx: watch::Receiver<LogLevel>,
 ) {
-    let runtime_filter = if has_rust_log {
-        EnvFilter::from_default_env()
-    } else if matches!(effective_log_level, LogLevel::Silent) {
-        EnvFilter::new("warn,telemt::links=info")
-    } else {
-        EnvFilter::new(effective_log_level.to_filter_str())
-    };
+    let runtime_filter = EnvFilter::new(log_filter_spec(has_rust_log, effective_log_level));
    filter_handle
        .reload(runtime_filter)
        .expect("Failed to switch log filter");
@@ -275,7 +330,7 @@ pub(crate) async fn apply_runtime_log_filter(
                break;
            }
            let level = log_level_rx.borrow_and_update().clone();
-            let new_filter = tracing_subscriber::EnvFilter::new(level.to_filter_str());
+            let new_filter = tracing_subscriber::EnvFilter::new(log_filter_spec(false, &level));
            if let Err(e) = filter_handle.reload(new_filter) {
                tracing::error!("config reload: failed to update log filter: {}", e);
            }
@@ -283,6 +338,17 @@ pub(crate) async fn apply_runtime_log_filter(
    });
 }

+pub(crate) fn log_filter_spec(has_rust_log: bool, effective_log_level: &LogLevel) -> String {
+    if has_rust_log {
+        std::env::var("RUST_LOG")
+            .unwrap_or_else(|_| effective_log_level.to_filter_str().to_string())
+    } else if matches!(effective_log_level, LogLevel::Silent) {
+        "warn,telemt::links=info".to_string()
+    } else {
+        effective_log_level.to_filter_str().to_string()
+    }
+}
+
 pub(crate) async fn spawn_metrics_if_configured(
    config: &Arc<ProxyConfig>,
    startup_tracker: &Arc<StartupTracker>,
@@ -290,6 +356,7 @@ pub(crate) async fn spawn_metrics_if_configured(
    beobachten: Arc<BeobachtenStore>,
    shared_state: Arc<ProxySharedState>,
    ip_tracker: Arc<UserIpTracker>,
+    tls_cache: Option<Arc<TlsFrontCache>>,
    config_rx: watch::Receiver<Arc<ProxyConfig>>,
 ) {
    // metrics_listen takes precedence; fall back to metrics_port for backward compat.
@@ -325,6 +392,7 @@ pub(crate) async fn spawn_metrics_if_configured(
        let shared_state = shared_state.clone();
        let config_rx_metrics = config_rx.clone();
        let ip_tracker_metrics = ip_tracker.clone();
+        let tls_cache_metrics = tls_cache.clone();
        let whitelist = config.server.metrics_whitelist.clone();
        let listen_backlog = config.server.listen_backlog;
        tokio::spawn(async move {
@@ -336,6 +404,7 @@ pub(crate) async fn spawn_metrics_if_configured(
                beobachten,
                shared_state,
                ip_tracker_metrics,
+                tls_cache_metrics,
                config_rx_metrics,
                whitelist,
            )
@@ -8,6 +8,7 @@
 //!
 //! SIGHUP is handled separately in config/hot_reload.rs for config reload.

+use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::{Duration, Instant};

@@ -48,9 +49,17 @@ pub(crate) async fn wait_for_shutdown(
    process_started_at: Instant,
    me_pool: Option<Arc<MePool>>,
    stats: Arc<Stats>,
+    quota_state_path: PathBuf,
 ) {
    let signal = wait_for_shutdown_signal().await;
-    perform_shutdown(signal, process_started_at, me_pool, &stats).await;
+    perform_shutdown(
+        signal,
+        process_started_at,
+        me_pool,
+        &stats,
+        quota_state_path,
+    )
+    .await;
 }

 /// Waits for any shutdown signal (SIGINT, SIGTERM, SIGQUIT).
@@ -79,6 +88,7 @@ async fn perform_shutdown(
    process_started_at: Instant,
    me_pool: Option<Arc<MePool>>,
    stats: &Stats,
+    quota_state_path: PathBuf,
 ) {
    let shutdown_started_at = Instant::now();
    info!(signal = %signal, "Received shutdown signal");
@@ -109,6 +119,22 @@ async fn perform_shutdown(
        }
    }

+    match crate::quota_state::save_quota_state(&quota_state_path, stats).await {
+        Ok(()) => {
+            info!(
+                path = %quota_state_path.display(),
+                "Persisted per-user quota state"
+            );
+        }
+        Err(error) => {
+            warn!(
+                error = %error,
+                path = %quota_state_path.display(),
+                "Failed to persist per-user quota state"
+            );
+        }
+    }
+
    let shutdown_secs = shutdown_started_at.elapsed().as_secs();
    info!(
        "Shutdown completed successfully in {} {}.",
@@ -10,6 +10,14 @@ use crate::tls_front::TlsFrontCache;
 use crate::tls_front::fetcher::TlsFetchStrategy;
 use crate::transport::UpstreamManager;

+fn tls_fetch_host_for_domain(mask_host: &str, primary_tls_domain: &str, domain: &str) -> String {
+    if mask_host.eq_ignore_ascii_case(primary_tls_domain) {
+        domain.to_string()
+    } else {
+        mask_host.to_string()
+    }
+}
+
 pub(crate) async fn bootstrap_tls_front(
    config: &ProxyConfig,
    tls_domains: &[String],
@@ -56,6 +64,7 @@ pub(crate) async fn bootstrap_tls_front(
        let cache_initial = cache.clone();
        let domains_initial = tls_domains.to_vec();
        let host_initial = mask_host.clone();
+        let primary_initial = config.censorship.tls_domain.clone();
        let unix_sock_initial = mask_unix_sock.clone();
        let scope_initial = tls_fetch_scope.clone();
        let upstream_initial = upstream_manager.clone();
@@ -64,7 +73,8 @@ pub(crate) async fn bootstrap_tls_front(
            let mut join = tokio::task::JoinSet::new();
            for domain in domains_initial {
                let cache_domain = cache_initial.clone();
-                let host_domain = host_initial.clone();
+                let host_domain =
+                    tls_fetch_host_for_domain(&host_initial, &primary_initial, &domain);
                let unix_sock_domain = unix_sock_initial.clone();
                let scope_domain = scope_initial.clone();
                let upstream_domain = upstream_initial.clone();
@@ -117,6 +127,7 @@ pub(crate) async fn bootstrap_tls_front(
        let cache_refresh = cache.clone();
        let domains_refresh = tls_domains.to_vec();
        let host_refresh = mask_host.clone();
+        let primary_refresh = config.censorship.tls_domain.clone();
        let unix_sock_refresh = mask_unix_sock.clone();
        let scope_refresh = tls_fetch_scope.clone();
        let upstream_refresh = upstream_manager.clone();
@@ -130,7 +141,8 @@ pub(crate) async fn bootstrap_tls_front(
                let mut join = tokio::task::JoinSet::new();
                for domain in domains_refresh.clone() {
                    let cache_domain = cache_refresh.clone();
-                    let host_domain = host_refresh.clone();
+                    let host_domain =
+                        tls_fetch_host_for_domain(&host_refresh, &primary_refresh, &domain);
                    let unix_sock_domain = unix_sock_refresh.clone();
                    let scope_domain = scope_refresh.clone();
                    let upstream_domain = upstream_refresh.clone();
@@ -186,3 +198,24 @@ pub(crate) async fn bootstrap_tls_front(

    tls_cache
 }
+
+#[cfg(test)]
+mod tests {
+    use super::tls_fetch_host_for_domain;
+
+    #[test]
+    fn tls_fetch_host_uses_each_domain_when_mask_host_is_primary_default() {
+        assert_eq!(
+            tls_fetch_host_for_domain("a.com", "a.com", "b.com"),
+            "b.com"
+        );
+    }
+
+    #[test]
+    fn tls_fetch_host_preserves_explicit_non_primary_mask_host() {
+        assert_eq!(
+            tls_fetch_host_for_domain("origin.example", "a.com", "b.com"),
+            "origin.example"
+        );
+    }
+}
@@ -8,6 +8,7 @@ mod crypto;
 #[cfg(unix)]
 mod daemon;
 mod error;
+mod healthcheck;
 mod ip_tracker;
 #[cfg(test)]
 #[path = "tests/ip_tracker_encapsulation_adversarial_tests.rs"]
@@ -24,6 +25,7 @@ mod metrics;
 mod network;
 mod protocol;
 mod proxy;
+mod quota_state;
 mod service;
 mod startup;
 mod stats;
@@ -97,6 +97,7 @@ pub async fn run_probe(
        let UpstreamType::Direct {
            interface,
            bind_addresses,
+            ..
        } = &upstream.upstream_type
        else {
            continue;
@@ -1383,6 +1383,8 @@ fn emulated_server_hello_never_places_alpn_in_server_hello_extensions() {
        &session_id,
        &cached,
        false,
+        true,
+        ClientHelloTlsVersion::Tls13,
        &rng,
        Some(b"h2".to_vec()),
        0,
@@ -1624,6 +1626,34 @@ fn test_extract_alpn_multiple() {
    assert_eq!(alpn_str, vec!["h2", "spdy", "h3"]);
 }

+#[test]
+fn detect_client_hello_tls_version_prefers_supported_versions_tls13() {
+    let supported_versions = vec![4, 0x03, 0x04, 0x03, 0x03];
+    let ch = build_client_hello_with_exts(vec![(0x002b, supported_versions)], "example.com");
+    assert_eq!(
+        detect_client_hello_tls_version(&ch),
+        Some(ClientHelloTlsVersion::Tls13)
+    );
+}
+
+#[test]
+fn detect_client_hello_tls_version_falls_back_to_legacy_tls12() {
+    let ch = build_client_hello_with_exts(Vec::new(), "example.com");
+    assert_eq!(
+        detect_client_hello_tls_version(&ch),
+        Some(ClientHelloTlsVersion::Tls12)
+    );
+}
+
+#[test]
+fn detect_client_hello_tls_version_rejects_malformed_supported_versions() {
+    // list_len=3 is invalid because version vector must contain u16 pairs.
+    let malformed_supported_versions = vec![3, 0x03, 0x04, 0x03];
+    let ch =
+        build_client_hello_with_exts(vec![(0x002b, malformed_supported_versions)], "example.com");
+    assert!(detect_client_hello_tls_version(&ch).is_none());
+}
+
 #[test]
 fn extract_sni_rejects_zero_length_host_name() {
    let mut sni_ext = Vec::new();
@@ -811,6 +811,122 @@ pub fn extract_alpn_from_client_hello(handshake: &[u8]) -> Vec<Vec<u8>> {
    out
 }

+/// ClientHello TLS generation inferred from handshake fields.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ClientHelloTlsVersion {
+    Tls12,
+    Tls13,
+}
+
+/// Detect TLS generation from a ClientHello.
+///
+/// The parser prefers `supported_versions` (0x002b) when present and falls back
+/// to `legacy_version` for compatibility with TLS 1.2 style hellos.
+pub fn detect_client_hello_tls_version(handshake: &[u8]) -> Option<ClientHelloTlsVersion> {
+    if handshake.len() < 5 || handshake[0] != TLS_RECORD_HANDSHAKE {
+        return None;
+    }
+
+    let record_len = u16::from_be_bytes([handshake[3], handshake[4]]) as usize;
+    if handshake.len() < 5 + record_len {
+        return None;
+    }
+
+    let mut pos = 5; // after record header
+    if handshake.get(pos) != Some(&0x01) {
+        return None; // not ClientHello
+    }
+    pos += 1; // message type
+
+    if pos + 3 > handshake.len() {
+        return None;
+    }
+    let handshake_len = ((handshake[pos] as usize) << 16)
+        | ((handshake[pos + 1] as usize) << 8)
+        | handshake[pos + 2] as usize;
+    pos += 3; // handshake length bytes
+    if pos + handshake_len > 5 + record_len {
+        return None;
+    }
+
+    if pos + 2 + 32 > handshake.len() {
+        return None;
+    }
+    let legacy_version = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
+    pos += 2 + 32; // version + random
+
+    let session_id_len = *handshake.get(pos)? as usize;
+    pos += 1 + session_id_len;
+    if pos + 2 > handshake.len() {
+        return None;
+    }
+
+    let cipher_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    pos += 2 + cipher_len;
+    if pos >= handshake.len() {
+        return None;
+    }
+
+    let comp_len = *handshake.get(pos)? as usize;
+    pos += 1 + comp_len;
+    if pos + 2 > handshake.len() {
+        return None;
+    }
+
+    let ext_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    pos += 2;
+    let ext_end = pos + ext_len;
+    if ext_end > handshake.len() {
+        return None;
+    }
+
+    while pos + 4 <= ext_end {
+        let etype = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
+        let elen = u16::from_be_bytes([handshake[pos + 2], handshake[pos + 3]]) as usize;
+        pos += 4;
+        if pos + elen > ext_end {
+            return None;
+        }
+
+        if etype == extension_type::SUPPORTED_VERSIONS {
+            if elen < 1 {
+                return None;
+            }
+            let list_len = handshake[pos] as usize;
+            if list_len == 0 || list_len % 2 != 0 || 1 + list_len > elen {
+                return None;
+            }
+
+            let mut has_tls12 = false;
+            let mut ver_pos = pos + 1;
+            let ver_end = ver_pos + list_len;
+            while ver_pos + 1 < ver_end {
+                let version = u16::from_be_bytes([handshake[ver_pos], handshake[ver_pos + 1]]);
+                if version == 0x0304 {
+                    return Some(ClientHelloTlsVersion::Tls13);
+                }
+                if version == 0x0303 || version == 0x0302 || version == 0x0301 {
+                    has_tls12 = true;
+                }
+                ver_pos += 2;
+            }
+
+            if has_tls12 {
+                return Some(ClientHelloTlsVersion::Tls12);
+            }
+            return None;
+        }
+
+        pos += elen;
+    }
+
+    if legacy_version >= 0x0303 {
+        Some(ClientHelloTlsVersion::Tls12)
+    } else {
+        None
+    }
+}
+
 /// Check if bytes look like a TLS ClientHello
 pub fn is_tls_handshake(first_bytes: &[u8]) -> bool {
    if first_bytes.len() < 3 {
@@ -11,6 +11,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite};
 use tokio::net::TcpStream;
+use tokio::sync::RwLock;
 use tokio::time::timeout;
 use tracing::{debug, warn};

@@ -31,38 +32,63 @@ struct UserConnectionReservation {
    ip_tracker: Arc<UserIpTracker>,
    user: String,
    ip: IpAddr,
-    active: bool,
+    tracks_ip: bool,
+    state: SessionReservationState,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum SessionReservationState {
+    Active,
+    Released,
 }

 impl UserConnectionReservation {
-    fn new(stats: Arc<Stats>, ip_tracker: Arc<UserIpTracker>, user: String, ip: IpAddr) -> Self {
+    fn new(
+        stats: Arc<Stats>,
+        ip_tracker: Arc<UserIpTracker>,
+        user: String,
+        ip: IpAddr,
+        tracks_ip: bool,
+    ) -> Self {
        Self {
            stats,
            ip_tracker,
            user,
            ip,
-            active: true,
+            tracks_ip,
+            state: SessionReservationState::Active,
        }
    }

+    fn mark_released(&mut self) -> bool {
+        if self.state != SessionReservationState::Active {
+            return false;
+        }
+        self.state = SessionReservationState::Released;
+        true
+    }
+
    async fn release(mut self) {
-        if !self.active {
+        if !self.mark_released() {
            return;
        }
-        self.ip_tracker.remove_ip(&self.user, self.ip).await;
-        self.active = false;
+        if self.tracks_ip {
+            self.ip_tracker.remove_ip(&self.user, self.ip).await;
+        }
        self.stats.decrement_user_curr_connects(&self.user);
    }
 }

 impl Drop for UserConnectionReservation {
    fn drop(&mut self) {
-        if !self.active {
+        if !self.mark_released() {
            return;
        }
-        self.active = false;
+        self.stats.increment_session_drop_fallback_total();
        self.stats.decrement_user_curr_connects(&self.user);
-        self.ip_tracker.enqueue_cleanup(self.user.clone(), self.ip);
+        if self.tracks_ip {
+            self.ip_tracker.enqueue_cleanup(self.user.clone(), self.ip);
+        }
    }
 }

@@ -324,17 +350,38 @@ fn record_beobachten_class(
    beobachten.record(class, peer_ip, beobachten_ttl(config));
 }

+fn classify_expected_64_got_0(kind: std::io::ErrorKind) -> Option<&'static str> {
+    match kind {
+        std::io::ErrorKind::UnexpectedEof => Some("expected_64_got_0_unexpected_eof"),
+        std::io::ErrorKind::ConnectionReset => Some("expected_64_got_0_connection_reset"),
+        std::io::ErrorKind::ConnectionAborted => Some("expected_64_got_0_connection_aborted"),
+        std::io::ErrorKind::BrokenPipe => Some("expected_64_got_0_broken_pipe"),
+        std::io::ErrorKind::NotConnected => Some("expected_64_got_0_not_connected"),
+        _ => None,
+    }
+}
+
+fn classify_handshake_failure_class(error: &ProxyError) -> &'static str {
+    match error {
+        ProxyError::Io(err) => classify_expected_64_got_0(err.kind()).unwrap_or("other"),
+        ProxyError::Stream(StreamError::UnexpectedEof) => "expected_64_got_0_unexpected_eof",
+        ProxyError::Stream(StreamError::Io(err)) => {
+            classify_expected_64_got_0(err.kind()).unwrap_or("other")
+        }
+        _ => "other",
+    }
+}
+
 fn record_handshake_failure_class(
    beobachten: &BeobachtenStore,
    config: &ProxyConfig,
    peer_ip: IpAddr,
    error: &ProxyError,
 ) {
-    let class = match error {
-        ProxyError::Io(err) if err.kind() == std::io::ErrorKind::UnexpectedEof => {
-            "expected_64_got_0"
-        }
-        ProxyError::Stream(StreamError::UnexpectedEof) => "expected_64_got_0",
+    // Keep beobachten buckets stable while detailed per-kind classification
+    // is tracked in API counters.
+    let class = match classify_handshake_failure_class(error) {
+        value if value.starts_with("expected_64_got_0_") => "expected_64_got_0",
        _ => "other",
    };
    record_beobachten_class(beobachten, config, peer_ip, class);
@@ -343,7 +390,7 @@ fn record_handshake_failure_class(
 #[inline]
 fn increment_bad_on_unknown_tls_sni(stats: &Stats, error: &ProxyError) {
    if matches!(error, ProxyError::UnknownTlsSni) {
-        stats.increment_connects_bad();
+        stats.increment_connects_bad_with_class("unknown_tls_sni");
    }
 }

@@ -406,8 +453,9 @@ where
 }

 #[allow(clippy::too_many_arguments)]
+#[allow(dead_code)]
 pub async fn handle_client_stream_with_shared<S>(
-    mut stream: S,
+    stream: S,
    peer: SocketAddr,
    config: Arc<ProxyConfig>,
    stats: Arc<Stats>,
@@ -423,6 +471,49 @@ pub async fn handle_client_stream_with_shared<S>(
    shared: Arc<ProxySharedState>,
    proxy_protocol_enabled: bool,
 ) -> Result<()>
+where
+    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
+{
+    handle_client_stream_with_shared_and_pool_runtime(
+        stream,
+        peer,
+        config,
+        stats,
+        upstream_manager,
+        replay_checker,
+        buffer_pool,
+        rng,
+        me_pool,
+        None,
+        route_runtime,
+        tls_cache,
+        ip_tracker,
+        beobachten,
+        shared,
+        proxy_protocol_enabled,
+    )
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+pub async fn handle_client_stream_with_shared_and_pool_runtime<S>(
+    mut stream: S,
+    peer: SocketAddr,
+    config: Arc<ProxyConfig>,
+    stats: Arc<Stats>,
+    upstream_manager: Arc<UpstreamManager>,
+    replay_checker: Arc<ReplayChecker>,
+    buffer_pool: Arc<BufferPool>,
+    rng: Arc<SecureRandom>,
+    me_pool: Option<Arc<MePool>>,
+    me_pool_runtime: Option<Arc<RwLock<Option<Arc<MePool>>>>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    tls_cache: Option<Arc<TlsFrontCache>>,
+    ip_tracker: Arc<UserIpTracker>,
+    beobachten: Arc<BeobachtenStore>,
+    shared: Arc<ProxySharedState>,
+    proxy_protocol_enabled: bool,
+) -> Result<()>
 where
    S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
 {
@@ -433,6 +524,17 @@ where
    let mut local_addr = synthetic_local_addr(config.server.port);

    if proxy_protocol_enabled {
+        if !is_trusted_proxy_source(peer.ip(), &config.server.proxy_protocol_trusted_cidrs) {
+            stats.increment_connects_bad_with_class("proxy_protocol_untrusted");
+            warn!(
+                peer = %peer,
+                trusted = ?config.server.proxy_protocol_trusted_cidrs,
+                "Rejecting PROXY protocol header from untrusted source"
+            );
+            record_beobachten_class(&beobachten, &config, peer.ip(), "other");
+            return Err(ProxyError::InvalidProxyProtocol);
+        }
+
        let proxy_header_timeout =
            Duration::from_millis(config.server.proxy_protocol_header_timeout_ms.max(1));
        match timeout(
@@ -442,17 +544,6 @@ where
        .await
        {
            Ok(Ok(info)) => {
-                if !is_trusted_proxy_source(peer.ip(), &config.server.proxy_protocol_trusted_cidrs)
-                {
-                    stats.increment_connects_bad();
-                    warn!(
-                        peer = %peer,
-                        trusted = ?config.server.proxy_protocol_trusted_cidrs,
-                        "Rejecting PROXY protocol header from untrusted source"
-                    );
-                    record_beobachten_class(&beobachten, &config, peer.ip(), "other");
-                    return Err(ProxyError::InvalidProxyProtocol);
-                }
                debug!(
                    peer = %peer,
                    client = %info.src_addr,
@@ -465,13 +556,13 @@ where
                }
            }
            Ok(Err(e)) => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("proxy_protocol_invalid_header");
                warn!(peer = %peer, error = %e, "Invalid PROXY protocol header");
                record_beobachten_class(&beobachten, &config, peer.ip(), "other");
                return Err(e);
            }
            Err(_) => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("proxy_protocol_header_timeout");
                warn!(peer = %peer, timeout_ms = proxy_header_timeout.as_millis(), "PROXY protocol header timeout");
                record_beobachten_class(&beobachten, &config, peer.ip(), "other");
                return Err(ProxyError::InvalidProxyProtocol);
@@ -561,7 +652,7 @@ where
            // third-party clients or future Telegram versions.
            if !tls_clienthello_len_in_bounds(tls_len) {
                debug!(peer = %real_peer, tls_len = tls_len, max_tls_len = MAX_TLS_PLAINTEXT_SIZE, "TLS handshake length out of bounds");
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_clienthello_len_out_of_bounds");
                maybe_apply_mask_reject_delay(&config).await;
                let (reader, writer) = tokio::io::split(stream);
                return Ok(masking_outcome(
@@ -581,7 +672,7 @@ where
                Ok(n) => n,
                Err(e) => {
                    debug!(peer = %real_peer, error = %e, tls_len = tls_len, "TLS ClientHello body read failed; engaging masking fallback");
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("tls_clienthello_read_error");
                    maybe_apply_mask_reject_delay(&config).await;
                    let initial_len = 5;
                    let (reader, writer) = tokio::io::split(stream);
@@ -599,7 +690,7 @@ where

            if body_read < tls_len {
                debug!(peer = %real_peer, got = body_read, expected = tls_len, "Truncated in-range TLS ClientHello; engaging masking fallback");
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_clienthello_truncated");
                maybe_apply_mask_reject_delay(&config).await;
                let initial_len = 5 + body_read;
                let (reader, writer) = tokio::io::split(stream);
@@ -623,7 +714,7 @@ where
            ).await {
                HandshakeResult::Success(result) => result,
                HandshakeResult::BadClient { reader, writer } => {
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("tls_handshake_bad_client");
                    return Ok(masking_outcome(
                        reader,
                        writer,
@@ -663,7 +754,7 @@ where
                        wrap_tls_application_record(&pending_plaintext)
                    };
                    let reader = tokio::io::AsyncReadExt::chain(std::io::Cursor::new(pending_record), reader);
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("tls_mtproto_bad_client");
                    debug!(
                        peer = %peer,
                        "Authenticated TLS session failed MTProto validation; engaging masking fallback"
@@ -685,6 +776,7 @@ where
                RunningClientHandler::handle_authenticated_static_with_shared(
                    crypto_reader, crypto_writer, success,
                    upstream_manager, stats, config, buffer_pool, rng, me_pool,
+                    me_pool_runtime,
                    route_runtime.clone(),
                    local_addr, real_peer, ip_tracker.clone(),
                    shared.clone(),
@@ -693,7 +785,7 @@ where
        } else {
            if !config.general.modes.classic && !config.general.modes.secure {
                debug!(peer = %real_peer, "Non-TLS modes disabled");
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("direct_modes_disabled");
                maybe_apply_mask_reject_delay(&config).await;
                let (reader, writer) = tokio::io::split(stream);
                return Ok(masking_outcome(
@@ -720,7 +812,7 @@ where
            ).await {
                HandshakeResult::Success(result) => result,
                HandshakeResult::BadClient { reader, writer } => {
-                    stats.increment_connects_bad();
+                    stats.increment_connects_bad_with_class("direct_mtproto_bad_client");
                    return Ok(masking_outcome(
                        reader,
                        writer,
@@ -745,6 +837,7 @@ where
                    buffer_pool,
                    rng,
                    me_pool,
+                    me_pool_runtime,
                    route_runtime.clone(),
                    local_addr,
                    real_peer,
@@ -757,6 +850,7 @@ where
        Ok(Ok(outcome)) => outcome,
        Ok(Err(e)) => {
            debug!(peer = %peer, error = %e, "Handshake failed");
+            stats_for_timeout.increment_handshake_failure_class(classify_handshake_failure_class(&e));
            record_handshake_failure_class(
                &beobachten_for_timeout,
                &config_for_timeout,
@@ -767,6 +861,7 @@ where
        }
        Err(_) => {
            stats_for_timeout.increment_handshake_timeouts();
+            stats_for_timeout.increment_handshake_failure_class("timeout");
            debug!(peer = %peer, "Handshake timeout");
            record_beobachten_class(
                &beobachten_for_timeout,
@@ -798,6 +893,7 @@ pub struct RunningClientHandler {
    buffer_pool: Arc<BufferPool>,
    rng: Arc<SecureRandom>,
    me_pool: Option<Arc<MePool>>,
+    me_pool_runtime: Option<Arc<RwLock<Option<Arc<MePool>>>>>,
    route_runtime: Arc<RouteRuntimeController>,
    tls_cache: Option<Arc<TlsFrontCache>>,
    ip_tracker: Arc<UserIpTracker>,
@@ -843,6 +939,7 @@ impl ClientHandler {
            buffer_pool,
            rng,
            me_pool,
+            None,
            route_runtime,
            tls_cache,
            ip_tracker,
@@ -867,6 +964,7 @@ impl ClientHandler {
        buffer_pool: Arc<BufferPool>,
        rng: Arc<SecureRandom>,
        me_pool: Option<Arc<MePool>>,
+        me_pool_runtime: Option<Arc<RwLock<Option<Arc<MePool>>>>>,
        route_runtime: Arc<RouteRuntimeController>,
        tls_cache: Option<Arc<TlsFrontCache>>,
        ip_tracker: Arc<UserIpTracker>,
@@ -890,6 +988,7 @@ impl ClientHandler {
            buffer_pool,
            rng,
            me_pool,
+            me_pool_runtime,
            route_runtime,
            tls_cache,
            ip_tracker,
@@ -943,6 +1042,21 @@ impl RunningClientHandler {
        let mut local_addr = self.stream.local_addr().map_err(ProxyError::Io)?;

        if self.proxy_protocol_enabled {
+            if !is_trusted_proxy_source(
+                self.peer.ip(),
+                &self.config.server.proxy_protocol_trusted_cidrs,
+            ) {
+                self.stats
+                    .increment_connects_bad_with_class("proxy_protocol_untrusted");
+                warn!(
+                    peer = %self.peer,
+                    trusted = ?self.config.server.proxy_protocol_trusted_cidrs,
+                    "Rejecting PROXY protocol header from untrusted source"
+                );
+                record_beobachten_class(&self.beobachten, &self.config, self.peer.ip(), "other");
+                return Err(ProxyError::InvalidProxyProtocol);
+            }
+
            let proxy_header_timeout =
                Duration::from_millis(self.config.server.proxy_protocol_header_timeout_ms.max(1));
            match timeout(
@@ -952,24 +1066,6 @@ impl RunningClientHandler {
            .await
            {
                Ok(Ok(info)) => {
-                    if !is_trusted_proxy_source(
-                        self.peer.ip(),
-                        &self.config.server.proxy_protocol_trusted_cidrs,
-                    ) {
-                        self.stats.increment_connects_bad();
-                        warn!(
-                            peer = %self.peer,
-                            trusted = ?self.config.server.proxy_protocol_trusted_cidrs,
-                            "Rejecting PROXY protocol header from untrusted source"
-                        );
-                        record_beobachten_class(
-                            &self.beobachten,
-                            &self.config,
-                            self.peer.ip(),
-                            "other",
-                        );
-                        return Err(ProxyError::InvalidProxyProtocol);
-                    }
                    debug!(
                        peer = %self.peer,
                        client = %info.src_addr,
@@ -986,7 +1082,8 @@ impl RunningClientHandler {
                    }
                }
                Ok(Err(e)) => {
-                    self.stats.increment_connects_bad();
+                    self.stats
+                        .increment_connects_bad_with_class("proxy_protocol_invalid_header");
                    warn!(peer = %self.peer, error = %e, "Invalid PROXY protocol header");
                    record_beobachten_class(
                        &self.beobachten,
@@ -997,7 +1094,8 @@ impl RunningClientHandler {
                    return Err(e);
                }
                Err(_) => {
-                    self.stats.increment_connects_bad();
+                    self.stats
+                        .increment_connects_bad_with_class("proxy_protocol_header_timeout");
                    warn!(
                        peer = %self.peer,
                        timeout_ms = proxy_header_timeout.as_millis(),
@@ -1095,6 +1193,7 @@ impl RunningClientHandler {
            Ok(Ok(outcome)) => outcome,
            Ok(Err(e)) => {
                debug!(peer = %peer_for_log, error = %e, "Handshake failed");
+                stats.increment_handshake_failure_class(classify_handshake_failure_class(&e));
                record_handshake_failure_class(
                    &beobachten_for_timeout,
                    &config_for_timeout,
@@ -1105,6 +1204,7 @@ impl RunningClientHandler {
            }
            Err(_) => {
                stats.increment_handshake_timeouts();
+                stats.increment_handshake_failure_class("timeout");
                debug!(peer = %peer_for_log, "Handshake timeout");
                record_beobachten_class(
                    &beobachten_for_timeout,
@@ -1140,7 +1240,8 @@ impl RunningClientHandler {
        // third-party clients or future Telegram versions.
        if !tls_clienthello_len_in_bounds(tls_len) {
            debug!(peer = %peer, tls_len = tls_len, max_tls_len = MAX_TLS_PLAINTEXT_SIZE, "TLS handshake length out of bounds");
-            self.stats.increment_connects_bad();
+            self.stats
+                .increment_connects_bad_with_class("tls_clienthello_len_out_of_bounds");
            maybe_apply_mask_reject_delay(&self.config).await;
            let (reader, writer) = self.stream.into_split();
            return Ok(masking_outcome(
@@ -1160,7 +1261,8 @@ impl RunningClientHandler {
            Ok(n) => n,
            Err(e) => {
                debug!(peer = %peer, error = %e, tls_len = tls_len, "TLS ClientHello body read failed; engaging masking fallback");
-                self.stats.increment_connects_bad();
+                self.stats
+                    .increment_connects_bad_with_class("tls_clienthello_read_error");
                maybe_apply_mask_reject_delay(&self.config).await;
                let (reader, writer) = self.stream.into_split();
                return Ok(masking_outcome(
@@ -1177,7 +1279,8 @@ impl RunningClientHandler {

        if body_read < tls_len {
            debug!(peer = %peer, got = body_read, expected = tls_len, "Truncated in-range TLS ClientHello; engaging masking fallback");
-            self.stats.increment_connects_bad();
+            self.stats
+                .increment_connects_bad_with_class("tls_clienthello_truncated");
            maybe_apply_mask_reject_delay(&self.config).await;
            let initial_len = 5 + body_read;
            let (reader, writer) = self.stream.into_split();
@@ -1214,7 +1317,7 @@ impl RunningClientHandler {
        {
            HandshakeResult::Success(result) => result,
            HandshakeResult::BadClient { reader, writer } => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_handshake_bad_client");
                return Ok(masking_outcome(
                    reader,
                    writer,
@@ -1264,7 +1367,7 @@ impl RunningClientHandler {
                };
                let reader =
                    tokio::io::AsyncReadExt::chain(std::io::Cursor::new(pending_record), reader);
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("tls_mtproto_bad_client");
                debug!(
                    peer = %peer,
                    "Authenticated TLS session failed MTProto validation; engaging masking fallback"
@@ -1293,6 +1396,7 @@ impl RunningClientHandler {
                buffer_pool,
                self.rng,
                self.me_pool,
+                self.me_pool_runtime,
                self.route_runtime.clone(),
                local_addr,
                peer,
@@ -1311,7 +1415,8 @@ impl RunningClientHandler {

        if !self.config.general.modes.classic && !self.config.general.modes.secure {
            debug!(peer = %peer, "Non-TLS modes disabled");
-            self.stats.increment_connects_bad();
+            self.stats
+                .increment_connects_bad_with_class("direct_modes_disabled");
            maybe_apply_mask_reject_delay(&self.config).await;
            let (reader, writer) = self.stream.into_split();
            return Ok(masking_outcome(
@@ -1351,7 +1456,7 @@ impl RunningClientHandler {
        {
            HandshakeResult::Success(result) => result,
            HandshakeResult::BadClient { reader, writer } => {
-                stats.increment_connects_bad();
+                stats.increment_connects_bad_with_class("direct_mtproto_bad_client");
                return Ok(masking_outcome(
                    reader,
                    writer,
@@ -1376,6 +1481,7 @@ impl RunningClientHandler {
                buffer_pool,
                self.rng,
                self.me_pool,
+                self.me_pool_runtime,
                self.route_runtime.clone(),
                local_addr,
                peer,
@@ -1387,8 +1493,8 @@ impl RunningClientHandler {

    /// Main dispatch after successful handshake.
    /// Two modes:
-    ///   - Direct: TCP relay to TG DC (existing behavior)  
-    ///   - Middle Proxy: RPC multiplex through ME pool (new — supports CDN DCs)
+    ///   - Direct: TCP relay to TG DC (existing behavior)
+    ///   - Middle Proxy: RPC multiplex through ME pool (supports CDN DCs)
    #[cfg(test)]
    async fn handle_authenticated_static<R, W>(
        client_reader: CryptoReader<R>,
@@ -1419,6 +1525,7 @@ impl RunningClientHandler {
            buffer_pool,
            rng,
            me_pool,
+            None,
            route_runtime,
            local_addr,
            peer_addr,
@@ -1438,6 +1545,7 @@ impl RunningClientHandler {
        buffer_pool: Arc<BufferPool>,
        rng: Arc<SecureRandom>,
        me_pool: Option<Arc<MePool>>,
+        me_pool_runtime: Option<Arc<RwLock<Option<Arc<MePool>>>>>,
        route_runtime: Arc<RouteRuntimeController>,
        local_addr: SocketAddr,
        peer_addr: SocketAddr,
@@ -1468,15 +1576,29 @@ impl RunningClientHandler {

        let route_snapshot = route_runtime.snapshot();
        let session_id = rng.u64();
-        let relay_result = if config.general.use_middle_proxy
+        let selected_me_pool = if config.general.use_middle_proxy
            && matches!(route_snapshot.mode, RelayRouteMode::Middle)
        {
            if let Some(ref pool) = me_pool {
+                Some(pool.clone())
+            } else if let Some(pool_runtime) = me_pool_runtime.as_ref() {
+                pool_runtime.read().await.clone()
+            } else {
+                None
+            }
+        } else {
+            None
+        };
+
+        let relay_result = if config.general.use_middle_proxy
+            && matches!(route_snapshot.mode, RelayRouteMode::Middle)
+        {
+            if let Some(pool) = selected_me_pool {
                handle_via_middle_proxy(
                    client_reader,
                    client_writer,
                    success,
-                    pool.clone(),
+                    pool,
                    stats.clone(),
                    config,
                    buffer_pool,
@@ -1589,6 +1711,7 @@ impl RunningClientHandler {
            ip_tracker,
            user.to_string(),
            peer_addr.ip(),
+            true,
        ))
    }

@@ -1634,7 +1757,6 @@ impl RunningClientHandler {
        match ip_tracker.check_and_add(user, peer_addr.ip()).await {
            Ok(()) => {
                ip_tracker.remove_ip(user, peer_addr.ip()).await;
-                stats.decrement_user_curr_connects(user);
            }
            Err(reason) => {
                stats.decrement_user_curr_connects(user);
@@ -1650,6 +1772,7 @@ impl RunningClientHandler {
            }
        }

+        stats.decrement_user_curr_connects(user);
        Ok(())
    }
 }
@@ -18,8 +18,7 @@ use crate::error::{ProxyError, Result};
 use crate::protocol::constants::*;
 use crate::proxy::handshake::{HandshakeSuccess, encrypt_tg_nonce_with_ciphers, generate_tg_nonce};
 use crate::proxy::route_mode::{
-    ROUTE_SWITCH_ERROR_MSG, RelayRouteMode, RouteCutoverState, affected_cutover_state,
-    cutover_stagger_delay,
+    RelayRouteMode, RouteCutoverState, affected_cutover_state, cutover_stagger_delay,
 };
 use crate::proxy::shared_state::{
    ConntrackCloseEvent, ConntrackClosePublishResult, ConntrackCloseReason, ProxySharedState,
@@ -316,6 +315,9 @@ where

    stats.increment_user_connects(user);
    let _direct_connection_lease = stats.acquire_direct_connection_lease();
+    let traffic_lease = shared
+        .traffic_limiter
+        .acquire_lease(user, success.peer.ip());

    let buffer_pool_trim = Arc::clone(&buffer_pool);
    let relay_activity_timeout = if shared.conntrack_pressure_active() {
@@ -329,7 +331,7 @@ where
    } else {
        Duration::from_secs(1800)
    };
-    let relay_result = crate::proxy::relay::relay_bidirectional_with_activity_timeout(
+    let relay_result = crate::proxy::relay::relay_bidirectional_with_activity_timeout_and_lease(
        client_reader,
        client_writer,
        tg_reader,
@@ -340,6 +342,7 @@ where
        Arc::clone(&stats),
        config.access.user_data_quota.get(user).copied(),
        buffer_pool,
+        traffic_lease,
        relay_activity_timeout,
    );
    tokio::pin!(relay_result);
@@ -355,8 +358,9 @@ where
                delay_ms = delay.as_millis() as u64,
                "Cutover affected direct session, closing client connection"
            );
+            let _cutover_park_lease = stats.acquire_direct_cutover_park_lease();
            tokio::time::sleep(delay).await;
-            break Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+            break Err(ProxyError::RouteSwitched);
        }
        tokio::select! {
            result = &mut relay_result => {
@@ -55,6 +55,7 @@ const STICKY_HINT_MAX_ENTRIES: usize = 65_536;
 const CANDIDATE_HINT_TRACK_CAP: usize = 64;
 const OVERLOAD_CANDIDATE_BUDGET_HINTED: usize = 16;
 const OVERLOAD_CANDIDATE_BUDGET_UNHINTED: usize = 8;
+const EXPENSIVE_INVALID_SCAN_SATURATION_THRESHOLD: usize = 64;
 const RECENT_USER_RING_SCAN_LIMIT: usize = 32;

 type HmacSha256 = Hmac<Sha256>;
@@ -551,6 +552,19 @@ fn auth_probe_note_saturation_in(shared: &ProxySharedState, now: Instant) {
    }
 }

+fn auth_probe_note_expensive_invalid_scan_in(
+    shared: &ProxySharedState,
+    now: Instant,
+    validation_checks: usize,
+    overload: bool,
+) {
+    if overload || validation_checks < EXPENSIVE_INVALID_SCAN_SATURATION_THRESHOLD {
+        return;
+    }
+
+    auth_probe_note_saturation_in(shared, now);
+}
+
 fn auth_probe_record_failure_in(shared: &ProxySharedState, peer_ip: IpAddr, now: Instant) {
    let peer_ip = normalize_auth_probe_ip(peer_ip);
    let state = &shared.handshake.auth_probe;
@@ -1119,6 +1133,10 @@ where
    } else {
        None
    };
+    // Fail-closed to TLS 1.3 semantics when ClientHello version is ambiguous:
+    // this avoids leaking certificate payload on malformed probes.
+    let client_tls_version = tls::detect_client_hello_tls_version(handshake)
+        .unwrap_or(tls::ClientHelloTlsVersion::Tls13);

    if client_sni.is_some() && matched_tls_domain.is_none() && preferred_user_hint.is_none() {
        let sni = client_sni.as_deref().unwrap_or_default();
@@ -1132,9 +1150,20 @@ where
                    "TLS handshake accepted by unknown SNI policy"
                );
            }
-            action @ (UnknownSniAction::Drop | UnknownSniAction::Mask) => {
+            action @ (UnknownSniAction::Drop
+            | UnknownSniAction::Mask
+            | UnknownSniAction::RejectHandshake) => {
                auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
-                maybe_apply_server_hello_delay(config).await;
+                // For Drop/Mask we apply the synthetic ServerHello delay so
+                // the fail-closed path is timing-indistinguishable from the
+                // success path. For RejectHandshake we deliberately skip the
+                // delay: a stock modern nginx with `ssl_reject_handshake on;`
+                // responds with the alert essentially immediately, so
+                // injecting 8-24ms here would itself become a distinguisher
+                // against the public baseline we are trying to blend into.
+                if !matches!(action, UnknownSniAction::RejectHandshake) {
+                    maybe_apply_server_hello_delay(config).await;
+                }
                let log_now = Instant::now();
                if should_emit_unknown_sni_warn_in(shared, log_now) {
                    warn!(
@@ -1153,8 +1182,33 @@ where
                        "TLS handshake rejected by unknown SNI policy"
                    );
                }
+                if matches!(action, UnknownSniAction::RejectHandshake) {
+                    // TLS alert record layer:
+                    //   0x15            ContentType.alert
+                    //   0x03 0x03       legacy_record_version = TLS 1.2
+                    //                   (matches what modern nginx emits in
+                    //                   the first server -> client record,
+                    //                   per RFC 8446 5.1 guidance)
+                    //   0x00 0x02       length = 2
+                    // Alert payload:
+                    //   0x02            AlertLevel.fatal
+                    //   0x70            AlertDescription.unrecognized_name (112, RFC 6066)
+                    const TLS_ALERT_UNRECOGNIZED_NAME: [u8; 7] =
+                        [0x15, 0x03, 0x03, 0x00, 0x02, 0x02, 0x70];
+                    if let Err(e) = writer.write_all(&TLS_ALERT_UNRECOGNIZED_NAME).await {
+                        debug!(
+                            peer = %peer,
+                            error = %e,
+                            "Failed to write unrecognized_name TLS alert"
+                        );
+                    } else {
+                        let _ = writer.flush().await;
+                    }
+                }
                return match action {
-                    UnknownSniAction::Drop => HandshakeResult::Error(ProxyError::UnknownTlsSni),
+                    UnknownSniAction::Drop | UnknownSniAction::RejectHandshake => {
+                        HandshakeResult::Error(ProxyError::UnknownTlsSni)
+                    }
                    UnknownSniAction::Mask => HandshakeResult::BadClient { reader, writer },
                    UnknownSniAction::Accept => unreachable!(),
                };
@@ -1338,7 +1392,14 @@ where
        }

        if !matched {
-            auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+            let failure_now = Instant::now();
+            auth_probe_note_expensive_invalid_scan_in(
+                shared,
+                failure_now,
+                validation_checks,
+                overload,
+            );
+            auth_probe_record_failure_in(shared, peer.ip(), failure_now);
            maybe_apply_server_hello_delay(config).await;
            debug!(
                peer = %peer,
@@ -1389,6 +1450,20 @@ where
        validated_secret.copy_from_slice(secret);
    }

+    if config
+        .access
+        .is_user_source_ip_denied(validated_user.as_str(), peer.ip())
+    {
+        auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+        maybe_apply_server_hello_delay(config).await;
+        warn!(
+            peer = %peer,
+            user = %validated_user,
+            "TLS handshake rejected: client source IP on per-user deny list (access.user_source_deny)"
+        );
+        return HandshakeResult::BadClient { reader, writer };
+    }
+
    // Reject known replay digests before expensive cache/domain/ALPN policy work.
    let digest_half = &validation_digest[..tls::TLS_DIGEST_HALF_LEN];
    if replay_checker.check_tls_digest(digest_half) {
@@ -1403,12 +1478,18 @@ where
            let selected_domain =
                matched_tls_domain.unwrap_or(config.censorship.tls_domain.as_str());
            let cached_entry = cache.get(selected_domain).await;
-            let use_full_cert_payload = cache
-                .take_full_cert_budget_for_ip(
-                    peer.ip(),
-                    Duration::from_secs(config.censorship.tls_full_cert_ttl_secs),
-                )
-                .await;
+            let use_full_cert_payload = if config.censorship.serverhello_compact
+                && matches!(client_tls_version, tls::ClientHelloTlsVersion::Tls12)
+            {
+                cache
+                    .take_full_cert_budget_for_ip(
+                        peer.ip(),
+                        Duration::from_secs(config.censorship.tls_full_cert_ttl_secs),
+                    )
+                    .await
+            } else {
+                true
+            };
            Some((cached_entry, use_full_cert_payload))
        } else {
            None
@@ -1429,6 +1510,8 @@ where
            validation_session_id_slice,
            &cached_entry,
            use_full_cert_payload,
+            config.censorship.serverhello_compact,
+            client_tls_version,
            rng,
            selected_alpn.clone(),
            config.censorship.tls_new_session_tickets,
@@ -1705,7 +1788,14 @@ where
        }

        if !matched {
-            auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+            let failure_now = Instant::now();
+            auth_probe_note_expensive_invalid_scan_in(
+                shared,
+                failure_now,
+                validation_checks,
+                overload,
+            );
+            auth_probe_record_failure_in(shared, peer.ip(), failure_now);
            maybe_apply_server_hello_delay(config).await;
            debug!(
                peer = %peer,
@@ -1719,6 +1809,20 @@ where

        let validation = matched_validation.expect("validation must exist when matched");

+        if config
+            .access
+            .is_user_source_ip_denied(matched_user.as_str(), peer.ip())
+        {
+            auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+            maybe_apply_server_hello_delay(config).await;
+            warn!(
+                peer = %peer,
+                user = %matched_user,
+                "MTProto handshake rejected: client source IP on per-user deny list (access.user_source_deny)"
+            );
+            return HandshakeResult::BadClient { reader, writer };
+        }
+
        // Apply replay tracking only after successful authentication.
        //
        // This ordering prevents an attacker from producing invalid handshakes that
@@ -1797,6 +1901,20 @@ where
                .auth_expensive_checks_total
                .fetch_add(validation_checks as u64, Ordering::Relaxed);

+            if config
+                .access
+                .is_user_source_ip_denied(user.as_str(), peer.ip())
+            {
+                auth_probe_record_failure_in(shared, peer.ip(), Instant::now());
+                maybe_apply_server_hello_delay(config).await;
+                warn!(
+                    peer = %peer,
+                    user = %user,
+                    "MTProto handshake rejected: client source IP on per-user deny list (access.user_source_deny)"
+                );
+                return HandshakeResult::BadClient { reader, writer };
+            }
+
            // Apply replay tracking only after successful authentication.
            //
            // This ordering prevents an attacker from producing invalid handshakes that
@@ -2,6 +2,7 @@

 use crate::config::ProxyConfig;
 use crate::network::dns_overrides::resolve_socket_addr;
+use crate::protocol::tls;
 use crate::stats::beobachten::BeobachtenStore;
 use crate::transport::proxy_protocol::{ProxyProtocolV1Builder, ProxyProtocolV2Builder};
 #[cfg(unix)]
@@ -28,14 +29,10 @@ use tracing::debug;
 const MASK_TIMEOUT: Duration = Duration::from_secs(5);
 #[cfg(test)]
 const MASK_TIMEOUT: Duration = Duration::from_millis(50);
-/// Maximum duration for the entire masking relay.
-/// Limits resource consumption from slow-loris attacks and port scanners.
-#[cfg(not(test))]
-const MASK_RELAY_TIMEOUT: Duration = Duration::from_secs(60);
+/// Maximum duration for the entire masking relay under test (replaced by config at runtime).
 #[cfg(test)]
 const MASK_RELAY_TIMEOUT: Duration = Duration::from_millis(200);
-#[cfg(not(test))]
-const MASK_RELAY_IDLE_TIMEOUT: Duration = Duration::from_secs(5);
+/// Per-read idle timeout for masking relay and drain paths under test (replaced by config at runtime).
 #[cfg(test)]
 const MASK_RELAY_IDLE_TIMEOUT: Duration = Duration::from_millis(100);
 const MASK_BUFFER_SIZE: usize = 8192;
@@ -50,11 +47,18 @@ struct CopyOutcome {
    ended_by_eof: bool,
 }

+#[derive(Clone, Copy)]
+struct MaskTcpTarget<'a> {
+    host: &'a str,
+    port: u16,
+}
+
 async fn copy_with_idle_timeout<R, W>(
    reader: &mut R,
    writer: &mut W,
    byte_cap: usize,
    shutdown_on_eof: bool,
+    idle_timeout: Duration,
 ) -> CopyOutcome
 where
    R: AsyncRead + Unpin,
@@ -63,22 +67,19 @@ where
    let mut buf = Box::new([0u8; MASK_BUFFER_SIZE]);
    let mut total = 0usize;
    let mut ended_by_eof = false;
-
-    if byte_cap == 0 {
-        return CopyOutcome {
-            total,
-            ended_by_eof,
-        };
-    }
+    let unlimited = byte_cap == 0;

    loop {
-        let remaining_budget = byte_cap.saturating_sub(total);
-        if remaining_budget == 0 {
-            break;
-        }
-
-        let read_len = remaining_budget.min(MASK_BUFFER_SIZE);
-        let read_res = timeout(MASK_RELAY_IDLE_TIMEOUT, reader.read(&mut buf[..read_len])).await;
+        let read_len = if unlimited {
+            MASK_BUFFER_SIZE
+        } else {
+            let remaining_budget = byte_cap.saturating_sub(total);
+            if remaining_budget == 0 {
+                break;
+            }
+            remaining_budget.min(MASK_BUFFER_SIZE)
+        };
+        let read_res = timeout(idle_timeout, reader.read(&mut buf[..read_len])).await;
        let n = match read_res {
            Ok(Ok(n)) => n,
            Ok(Err(_)) | Err(_) => break,
@@ -86,13 +87,13 @@ where
        if n == 0 {
            ended_by_eof = true;
            if shutdown_on_eof {
-                let _ = timeout(MASK_RELAY_IDLE_TIMEOUT, writer.shutdown()).await;
+                let _ = timeout(idle_timeout, writer.shutdown()).await;
            }
            break;
        }
        total = total.saturating_add(n);

-        let write_res = timeout(MASK_RELAY_IDLE_TIMEOUT, writer.write_all(&buf[..n])).await;
+        let write_res = timeout(idle_timeout, writer.write_all(&buf[..n])).await;
        match write_res {
            Ok(Ok(())) => {}
            Ok(Err(_)) | Err(_) => break,
@@ -230,13 +231,20 @@ where
    }
 }

-async fn consume_client_data_with_timeout_and_cap<R>(reader: R, byte_cap: usize)
-where
+async fn consume_client_data_with_timeout_and_cap<R>(
+    reader: R,
+    byte_cap: usize,
+    relay_timeout: Duration,
+    idle_timeout: Duration,
+) where
    R: AsyncRead + Unpin,
 {
-    if timeout(MASK_RELAY_TIMEOUT, consume_client_data(reader, byte_cap))
-        .await
-        .is_err()
+    if timeout(
+        relay_timeout,
+        consume_client_data(reader, byte_cap, idle_timeout),
+    )
+    .await
+    .is_err()
    {
        debug!("Timed out while consuming client data on masking fallback path");
    }
@@ -327,6 +335,110 @@ async fn wait_mask_outcome_budget(started: Instant, config: &ProxyConfig) {
    }
 }

+#[cfg(test)]
+mod tls_domain_mask_host_tests {
+    use super::{
+        mask_host_for_initial_data, mask_tcp_target_for_initial_data, matching_tls_domain_for_sni,
+    };
+    use crate::config::ProxyConfig;
+
+    fn client_hello_with_sni(sni_host: &str) -> Vec<u8> {
+        let mut body = Vec::new();
+        body.extend_from_slice(&[0x03, 0x03]);
+        body.extend_from_slice(&[0u8; 32]);
+        body.push(32);
+        body.extend_from_slice(&[0x42u8; 32]);
+        body.extend_from_slice(&2u16.to_be_bytes());
+        body.extend_from_slice(&[0x13, 0x01]);
+        body.push(1);
+        body.push(0);
+
+        let host_bytes = sni_host.as_bytes();
+        let mut sni_payload = Vec::new();
+        sni_payload.extend_from_slice(&((host_bytes.len() + 3) as u16).to_be_bytes());
+        sni_payload.push(0);
+        sni_payload.extend_from_slice(&(host_bytes.len() as u16).to_be_bytes());
+        sni_payload.extend_from_slice(host_bytes);
+
+        let mut extensions = Vec::new();
+        extensions.extend_from_slice(&0x0000u16.to_be_bytes());
+        extensions.extend_from_slice(&(sni_payload.len() as u16).to_be_bytes());
+        extensions.extend_from_slice(&sni_payload);
+        body.extend_from_slice(&(extensions.len() as u16).to_be_bytes());
+        body.extend_from_slice(&extensions);
+
+        let mut handshake = Vec::new();
+        handshake.push(0x01);
+        let body_len = (body.len() as u32).to_be_bytes();
+        handshake.extend_from_slice(&body_len[1..4]);
+        handshake.extend_from_slice(&body);
+
+        let mut record = Vec::new();
+        record.push(0x16);
+        record.extend_from_slice(&[0x03, 0x01]);
+        record.extend_from_slice(&(handshake.len() as u16).to_be_bytes());
+        record.extend_from_slice(&handshake);
+        record
+    }
+
+    fn config_with_tls_domains() -> ProxyConfig {
+        let mut config = ProxyConfig::default();
+        config.censorship.tls_domain = "a.com".to_string();
+        config.censorship.tls_domains = vec!["b.com".to_string(), "c.com".to_string()];
+        config.censorship.mask_host = Some("a.com".to_string());
+        config
+    }
+
+    #[test]
+    fn matching_tls_domain_accepts_primary_and_extra_domains_case_insensitively() {
+        let config = config_with_tls_domains();
+
+        assert_eq!(matching_tls_domain_for_sni(&config, "A.COM"), Some("a.com"));
+        assert_eq!(matching_tls_domain_for_sni(&config, "B.COM"), Some("b.com"));
+        assert_eq!(matching_tls_domain_for_sni(&config, "unknown.com"), None);
+    }
+
+    #[test]
+    fn mask_host_preserves_explicit_non_primary_origin() {
+        let mut config = config_with_tls_domains();
+        config.censorship.mask_host = Some("origin.example".to_string());
+
+        let initial_data = client_hello_with_sni("b.com");
+
+        assert_eq!(
+            mask_host_for_initial_data(&config, &initial_data),
+            "origin.example"
+        );
+    }
+
+    #[test]
+    fn mask_host_uses_matching_tls_domain_when_mask_host_is_primary_default() {
+        let config = config_with_tls_domains();
+        let initial_data = client_hello_with_sni("b.com");
+
+        assert_eq!(mask_host_for_initial_data(&config, &initial_data), "b.com");
+    }
+
+    #[test]
+    fn exclusive_mask_target_overrides_only_matching_sni() {
+        let mut config = config_with_tls_domains();
+        config
+            .censorship
+            .exclusive_mask
+            .insert("b.com".to_string(), "origin-b.example:8443".to_string());
+        let b_initial_data = client_hello_with_sni("B.COM");
+        let c_initial_data = client_hello_with_sni("c.com");
+
+        let b_target = mask_tcp_target_for_initial_data(&config, &b_initial_data);
+        let c_target = mask_tcp_target_for_initial_data(&config, &c_initial_data);
+
+        assert_eq!(b_target.host, "origin-b.example");
+        assert_eq!(b_target.port, 8443);
+        assert_eq!(c_target.host, "c.com");
+        assert_eq!(c_target.port, config.censorship.mask_port);
+    }
+}
+
 /// Detect client type based on initial data
 fn detect_client_type(data: &[u8]) -> &'static str {
    // Check for HTTP request
@@ -359,6 +471,134 @@ fn parse_mask_host_ip_literal(host: &str) -> Option<IpAddr> {
    host.parse::<IpAddr>().ok()
 }

+fn matching_tls_domain_for_sni<'a>(config: &'a ProxyConfig, sni: &str) -> Option<&'a str> {
+    if config.censorship.tls_domain.eq_ignore_ascii_case(sni) {
+        return Some(config.censorship.tls_domain.as_str());
+    }
+
+    for domain in &config.censorship.tls_domains {
+        if domain.eq_ignore_ascii_case(sni) {
+            return Some(domain.as_str());
+        }
+    }
+
+    None
+}
+
+fn parse_exclusive_mask_target(target: &str) -> Option<MaskTcpTarget<'_>> {
+    let target = target.trim();
+    if target.is_empty() {
+        return None;
+    }
+
+    if target.starts_with('[') {
+        let end = target.find(']')?;
+        if target.get(end + 1..end + 2)? != ":" {
+            return None;
+        }
+        let port = target[end + 2..].parse::<u16>().ok()?;
+        return (port > 0).then_some(MaskTcpTarget {
+            host: &target[..=end],
+            port,
+        });
+    }
+
+    let (host, port) = target.rsplit_once(':')?;
+    if host.is_empty() || host.contains(':') {
+        return None;
+    }
+    let port = port.parse::<u16>().ok()?;
+    (port > 0).then_some(MaskTcpTarget { host, port })
+}
+
+fn exclusive_mask_target_for_sni<'a>(
+    config: &'a ProxyConfig,
+    sni: &str,
+) -> Option<MaskTcpTarget<'a>> {
+    if let Some(target) = config.censorship.exclusive_mask_targets.get(sni) {
+        return Some(MaskTcpTarget {
+            host: target.host.as_str(),
+            port: target.port,
+        });
+    }
+    if let Some(target) = config.censorship.exclusive_mask.get(sni) {
+        return parse_exclusive_mask_target(target);
+    }
+
+    if sni.bytes().any(|byte| byte.is_ascii_uppercase()) {
+        let normalized_sni = sni.to_ascii_lowercase();
+        if let Some(target) = config
+            .censorship
+            .exclusive_mask_targets
+            .get(&normalized_sni)
+        {
+            return Some(MaskTcpTarget {
+                host: target.host.as_str(),
+                port: target.port,
+            });
+        }
+        if let Some(target) = config.censorship.exclusive_mask.get(&normalized_sni) {
+            return parse_exclusive_mask_target(target);
+        }
+    }
+
+    None
+}
+
+#[cfg(test)]
+fn mask_host_for_initial_data<'a>(config: &'a ProxyConfig, initial_data: &[u8]) -> &'a str {
+    mask_tcp_target_for_initial_data(config, initial_data).host
+}
+
+#[cfg(test)]
+fn mask_tcp_target_for_initial_data<'a>(
+    config: &'a ProxyConfig,
+    initial_data: &[u8],
+) -> MaskTcpTarget<'a> {
+    let sni = tls::extract_sni_from_client_hello(initial_data);
+    if let Some(target) = sni
+        .as_deref()
+        .and_then(|sni| exclusive_mask_target_for_sni(config, sni))
+    {
+        return target;
+    }
+
+    default_mask_tcp_target_for_initial_data(config, initial_data, sni.as_deref())
+}
+
+fn default_mask_tcp_target_for_initial_data<'a>(
+    config: &'a ProxyConfig,
+    initial_data: &[u8],
+    sni: Option<&str>,
+) -> MaskTcpTarget<'a> {
+    let configured_mask_host = config
+        .censorship
+        .mask_host
+        .as_deref()
+        .unwrap_or(&config.censorship.tls_domain);
+
+    if !configured_mask_host.eq_ignore_ascii_case(&config.censorship.tls_domain) {
+        return MaskTcpTarget {
+            host: configured_mask_host,
+            port: config.censorship.mask_port,
+        };
+    }
+
+    let extracted_sni = if sni.is_none() {
+        tls::extract_sni_from_client_hello(initial_data)
+    } else {
+        None
+    };
+    let host = sni
+        .or(extracted_sni.as_deref())
+        .and_then(|sni| matching_tls_domain_for_sni(config, sni))
+        .unwrap_or(configured_mask_host);
+    MaskTcpTarget {
+        host,
+        port: config.censorship.mask_port,
+    }
+}
+
 fn canonical_ip(ip: IpAddr) -> IpAddr {
    match ip {
        IpAddr::V6(v6) => v6
@@ -639,16 +879,31 @@ pub async fn handle_bad_client<R, W>(
        beobachten.record(client_type, peer.ip(), ttl);
    }

+    let relay_timeout = Duration::from_millis(config.censorship.mask_relay_timeout_ms);
+    let idle_timeout = Duration::from_millis(config.censorship.mask_relay_idle_timeout_ms);
+
    if !config.censorship.mask {
        // Masking disabled, just consume data
-        consume_client_data_with_timeout_and_cap(reader, config.censorship.mask_relay_max_bytes)
-            .await;
+        consume_client_data_with_timeout_and_cap(
+            reader,
+            config.censorship.mask_relay_max_bytes,
+            relay_timeout,
+            idle_timeout,
+        )
+        .await;
        return;
    }

+    let client_sni = tls::extract_sni_from_client_hello(initial_data);
+    let exclusive_tcp_target = client_sni
+        .as_deref()
+        .and_then(|sni| exclusive_mask_target_for_sni(config, sni));
+
    // Connect via Unix socket or TCP
    #[cfg(unix)]
-    if let Some(ref sock_path) = config.censorship.mask_unix_sock {
+    if exclusive_tcp_target.is_none()
+        && let Some(ref sock_path) = config.censorship.mask_unix_sock
+    {
        let outcome_started = Instant::now();
        let connect_started = Instant::now();
        debug!(
@@ -674,7 +929,7 @@ pub async fn handle_bad_client<R, W>(
                    return;
                }
                if timeout(
-                    MASK_RELAY_TIMEOUT,
+                    relay_timeout,
                    relay_to_mask(
                        reader,
                        writer,
@@ -688,6 +943,7 @@ pub async fn handle_bad_client<R, W>(
                        config.censorship.mask_shape_above_cap_blur_max_bytes,
                        config.censorship.mask_shape_hardening_aggressive_mode,
                        config.censorship.mask_relay_max_bytes,
+                        idle_timeout,
                    ),
                )
                .await
@@ -703,6 +959,8 @@ pub async fn handle_bad_client<R, W>(
                consume_client_data_with_timeout_and_cap(
                    reader,
                    config.censorship.mask_relay_max_bytes,
+                    relay_timeout,
+                    idle_timeout,
                )
                .await;
                wait_mask_outcome_budget(outcome_started, config).await;
@@ -712,6 +970,8 @@ pub async fn handle_bad_client<R, W>(
                consume_client_data_with_timeout_and_cap(
                    reader,
                    config.censorship.mask_relay_max_bytes,
+                    relay_timeout,
+                    idle_timeout,
                )
                .await;
                wait_mask_outcome_budget(outcome_started, config).await;
@@ -720,12 +980,11 @@ pub async fn handle_bad_client<R, W>(
        return;
    }

-    let mask_host = config
-        .censorship
-        .mask_host
-        .as_deref()
-        .unwrap_or(&config.censorship.tls_domain);
-    let mask_port = config.censorship.mask_port;
+    let mask_target = exclusive_tcp_target.unwrap_or_else(|| {
+        default_mask_tcp_target_for_initial_data(config, initial_data, client_sni.as_deref())
+    });
+    let mask_host = mask_target.host;
+    let mask_port = mask_target.port;

    // Fail closed when fallback points at our own listener endpoint.
    // Self-referential masking can create recursive proxy loops under
@@ -742,8 +1001,13 @@ pub async fn handle_bad_client<R, W>(
            local = %local_addr,
            "Mask target resolves to local listener; refusing self-referential masking fallback"
        );
-        consume_client_data_with_timeout_and_cap(reader, config.censorship.mask_relay_max_bytes)
-            .await;
+        consume_client_data_with_timeout_and_cap(
+            reader,
+            config.censorship.mask_relay_max_bytes,
+            relay_timeout,
+            idle_timeout,
+        )
+        .await;
        wait_mask_outcome_budget(outcome_started, config).await;
        return;
    }
@@ -777,7 +1041,7 @@ pub async fn handle_bad_client<R, W>(
                return;
            }
            if timeout(
-                MASK_RELAY_TIMEOUT,
+                relay_timeout,
                relay_to_mask(
                    reader,
                    writer,
@@ -791,6 +1055,7 @@ pub async fn handle_bad_client<R, W>(
                    config.censorship.mask_shape_above_cap_blur_max_bytes,
                    config.censorship.mask_shape_hardening_aggressive_mode,
                    config.censorship.mask_relay_max_bytes,
+                    idle_timeout,
                ),
            )
            .await
@@ -806,6 +1071,8 @@ pub async fn handle_bad_client<R, W>(
            consume_client_data_with_timeout_and_cap(
                reader,
                config.censorship.mask_relay_max_bytes,
+                relay_timeout,
+                idle_timeout,
            )
            .await;
            wait_mask_outcome_budget(outcome_started, config).await;
@@ -815,6 +1082,8 @@ pub async fn handle_bad_client<R, W>(
            consume_client_data_with_timeout_and_cap(
                reader,
                config.censorship.mask_relay_max_bytes,
+                relay_timeout,
+                idle_timeout,
            )
            .await;
            wait_mask_outcome_budget(outcome_started, config).await;
@@ -836,6 +1105,7 @@ async fn relay_to_mask<R, W, MR, MW>(
    shape_above_cap_blur_max_bytes: usize,
    shape_hardening_aggressive_mode: bool,
    mask_relay_max_bytes: usize,
+    idle_timeout: Duration,
 ) where
    R: AsyncRead + Unpin + Send + 'static,
    W: AsyncWrite + Unpin + Send + 'static,
@@ -857,11 +1127,19 @@ async fn relay_to_mask<R, W, MR, MW>(
                &mut mask_write,
                mask_relay_max_bytes,
                !shape_hardening_enabled,
+                idle_timeout,
            )
            .await
        },
        async {
-            copy_with_idle_timeout(&mut mask_read, &mut writer, mask_relay_max_bytes, true).await
+            copy_with_idle_timeout(
+                &mut mask_read,
+                &mut writer,
+                mask_relay_max_bytes,
+                true,
+                idle_timeout,
+            )
+            .await
        }
    );

@@ -889,23 +1167,27 @@ async fn relay_to_mask<R, W, MR, MW>(
 }

 /// Just consume all data from client without responding.
-async fn consume_client_data<R: AsyncRead + Unpin>(mut reader: R, byte_cap: usize) {
-    if byte_cap == 0 {
-        return;
-    }
-
+async fn consume_client_data<R: AsyncRead + Unpin>(
+    mut reader: R,
+    byte_cap: usize,
+    idle_timeout: Duration,
+) {
    // Keep drain path fail-closed under slow-loris stalls.
    let mut buf = Box::new([0u8; MASK_BUFFER_SIZE]);
    let mut total = 0usize;
+    let unlimited = byte_cap == 0;

    loop {
-        let remaining_budget = byte_cap.saturating_sub(total);
-        if remaining_budget == 0 {
-            break;
-        }
-
-        let read_len = remaining_budget.min(MASK_BUFFER_SIZE);
-        let n = match timeout(MASK_RELAY_IDLE_TIMEOUT, reader.read(&mut buf[..read_len])).await {
+        let read_len = if unlimited {
+            MASK_BUFFER_SIZE
+        } else {
+            let remaining_budget = byte_cap.saturating_sub(total);
+            if remaining_budget == 0 {
+                break;
+            }
+            remaining_budget.min(MASK_BUFFER_SIZE)
+        };
+        let n = match timeout(idle_timeout, reader.read(&mut buf[..read_len])).await {
            Ok(Ok(n)) => n,
            Ok(Err(_)) | Err(_) => break,
        };
@@ -915,7 +1197,7 @@ async fn consume_client_data<R: AsyncRead + Unpin>(mut reader: R, byte_cap: usiz
        }

        total = total.saturating_add(n);
-        if total >= byte_cap {
+        if !unlimited && total >= byte_cap {
            break;
        }
    }
@@ -0,0 +1,104 @@
+use super::*;
+
+pub(in crate::proxy::middle_relay) enum C2MeCommand {
+    Data {
+        payload: PooledBuffer,
+        flags: u32,
+        _permit: OwnedSemaphorePermit,
+    },
+    Close,
+}
+
+pub(super) fn should_yield_c2me_sender(sent_since_yield: usize, has_backlog: bool) -> bool {
+    has_backlog && sent_since_yield >= C2ME_SENDER_FAIRNESS_BUDGET
+}
+
+pub(super) fn c2me_payload_permits(payload_len: usize) -> u32 {
+    payload_len
+        .max(1)
+        .div_ceil(C2ME_QUEUED_BYTE_PERMIT_UNIT)
+        .min(u32::MAX as usize) as u32
+}
+
+pub(super) fn c2me_queued_permit_budget(channel_capacity: usize, frame_limit: usize) -> usize {
+    channel_capacity
+        .saturating_mul(C2ME_QUEUED_PERMITS_PER_SLOT)
+        .max(c2me_payload_permits(frame_limit) as usize)
+        .max(1)
+}
+
+pub(super) async fn acquire_c2me_payload_permit(
+    semaphore: &Arc<Semaphore>,
+    payload_len: usize,
+    send_timeout: Option<Duration>,
+    stats: &Stats,
+) -> Result<OwnedSemaphorePermit> {
+    let permits = c2me_payload_permits(payload_len);
+    let acquire = semaphore.clone().acquire_many_owned(permits);
+    match send_timeout {
+        Some(send_timeout) => match timeout(send_timeout, acquire).await {
+            Ok(Ok(permit)) => Ok(permit),
+            Ok(Err(_)) => Err(ProxyError::Proxy("ME sender byte budget closed".into())),
+            Err(_) => {
+                stats.increment_me_c2me_send_timeout_total();
+                Err(ProxyError::Proxy("ME sender byte budget timeout".into()))
+            }
+        },
+        None => acquire
+            .await
+            .map_err(|_| ProxyError::Proxy("ME sender byte budget closed".into())),
+    }
+}
+
+pub(super) async fn enqueue_c2me_command_in(
+    shared: &ProxySharedState,
+    tx: &mpsc::Sender<C2MeCommand>,
+    cmd: C2MeCommand,
+    send_timeout: Option<Duration>,
+    stats: &Stats,
+) -> std::result::Result<(), mpsc::error::SendError<C2MeCommand>> {
+    match tx.try_send(cmd) {
+        Ok(()) => Ok(()),
+        Err(mpsc::error::TrySendError::Closed(cmd)) => Err(mpsc::error::SendError(cmd)),
+        Err(mpsc::error::TrySendError::Full(cmd)) => {
+            stats.increment_me_c2me_send_full_total();
+            stats.increment_me_c2me_send_high_water_total();
+            note_relay_pressure_event_in(shared);
+            // Cooperative yield reduces burst catch-up when the per-conn queue is near saturation.
+            if tx.capacity() <= C2ME_SOFT_PRESSURE_MIN_FREE_SLOTS {
+                tokio::task::yield_now().await;
+            }
+            let reserve_result = match send_timeout {
+                Some(send_timeout) => match timeout(send_timeout, tx.reserve()).await {
+                    Ok(result) => result,
+                    Err(_) => {
+                        stats.increment_me_c2me_send_timeout_total();
+                        return Err(mpsc::error::SendError(cmd));
+                    }
+                },
+                None => tx.reserve().await,
+            };
+            match reserve_result {
+                Ok(permit) => {
+                    permit.send(cmd);
+                    Ok(())
+                }
+                Err(_) => {
+                    stats.increment_me_c2me_send_timeout_total();
+                    Err(mpsc::error::SendError(cmd))
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+pub(crate) async fn enqueue_c2me_command(
+    tx: &mpsc::Sender<C2MeCommand>,
+    cmd: C2MeCommand,
+    send_timeout: Option<Duration>,
+    stats: &Stats,
+) -> std::result::Result<(), mpsc::error::SendError<C2MeCommand>> {
+    let shared = ProxySharedState::new();
+    enqueue_c2me_command_in(shared.as_ref(), tx, cmd, send_timeout, stats).await
+}
@@ -0,0 +1,458 @@
+use super::*;
+
+#[derive(Clone, Copy)]
+pub(super) struct MeD2cFlushPolicy {
+    pub(super) max_frames: usize,
+    pub(super) max_bytes: usize,
+    pub(super) max_delay: Duration,
+    pub(super) ack_flush_immediate: bool,
+    pub(super) quota_soft_overshoot_bytes: u64,
+    pub(super) frame_buf_shrink_threshold_bytes: usize,
+}
+
+impl MeD2cFlushPolicy {
+    pub(super) fn from_config(config: &ProxyConfig) -> Self {
+        Self {
+            max_frames: config
+                .general
+                .me_d2c_flush_batch_max_frames
+                .max(ME_D2C_FLUSH_BATCH_MAX_FRAMES_MIN),
+            max_bytes: config
+                .general
+                .me_d2c_flush_batch_max_bytes
+                .max(ME_D2C_FLUSH_BATCH_MAX_BYTES_MIN),
+            max_delay: Duration::from_micros(config.general.me_d2c_flush_batch_max_delay_us),
+            ack_flush_immediate: config.general.me_d2c_ack_flush_immediate,
+            quota_soft_overshoot_bytes: config.general.me_quota_soft_overshoot_bytes,
+            frame_buf_shrink_threshold_bytes: config
+                .general
+                .me_d2c_frame_buf_shrink_threshold_bytes
+                .max(4096),
+        }
+    }
+}
+
+pub(super) fn classify_me_d2c_flush_reason(
+    flush_immediately: bool,
+    batch_frames: usize,
+    max_frames: usize,
+    batch_bytes: usize,
+    max_bytes: usize,
+    max_delay_fired: bool,
+) -> MeD2cFlushReason {
+    if flush_immediately {
+        return MeD2cFlushReason::AckImmediate;
+    }
+    if batch_frames >= max_frames {
+        return MeD2cFlushReason::BatchFrames;
+    }
+    if batch_bytes >= max_bytes {
+        return MeD2cFlushReason::BatchBytes;
+    }
+    if max_delay_fired {
+        return MeD2cFlushReason::MaxDelay;
+    }
+    MeD2cFlushReason::QueueDrain
+}
+
+pub(super) fn observe_me_d2c_flush_event(
+    stats: &Stats,
+    reason: MeD2cFlushReason,
+    batch_frames: usize,
+    batch_bytes: usize,
+    flush_duration_us: Option<u64>,
+) {
+    stats.increment_me_d2c_flush_reason(reason);
+    if batch_frames > 0 || batch_bytes > 0 {
+        stats.increment_me_d2c_batches_total();
+        stats.add_me_d2c_batch_frames_total(batch_frames as u64);
+        stats.add_me_d2c_batch_bytes_total(batch_bytes as u64);
+        stats.observe_me_d2c_batch_frames(batch_frames as u64);
+        stats.observe_me_d2c_batch_bytes(batch_bytes as u64);
+    }
+    if let Some(duration_us) = flush_duration_us {
+        stats.observe_me_d2c_flush_duration_us(duration_us);
+    }
+}
+
+pub(super) enum MeWriterResponseOutcome {
+    Continue {
+        frames: usize,
+        bytes: usize,
+        flush_immediately: bool,
+    },
+    Close,
+}
+
+#[cfg(test)]
+pub(crate) async fn process_me_writer_response<W>(
+    response: MeResponse,
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    rng: &SecureRandom,
+    frame_buf: &mut Vec<u8>,
+    stats: &Stats,
+    user: &str,
+    quota_user_stats: Option<&UserStats>,
+    quota_limit: Option<u64>,
+    quota_soft_overshoot_bytes: u64,
+    bytes_me2c: &AtomicU64,
+    conn_id: u64,
+    ack_flush_immediate: bool,
+    batched: bool,
+) -> Result<MeWriterResponseOutcome>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    process_me_writer_response_with_traffic_lease(
+        response,
+        client_writer,
+        proto_tag,
+        rng,
+        frame_buf,
+        stats,
+        user,
+        quota_user_stats,
+        quota_limit,
+        quota_soft_overshoot_bytes,
+        None,
+        &CancellationToken::new(),
+        bytes_me2c,
+        conn_id,
+        ack_flush_immediate,
+        batched,
+    )
+    .await
+}
+
+pub(crate) async fn process_me_writer_response_with_traffic_lease<W>(
+    response: MeResponse,
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    rng: &SecureRandom,
+    frame_buf: &mut Vec<u8>,
+    stats: &Stats,
+    user: &str,
+    quota_user_stats: Option<&UserStats>,
+    quota_limit: Option<u64>,
+    quota_soft_overshoot_bytes: u64,
+    traffic_lease: Option<&Arc<TrafficLease>>,
+    cancel: &CancellationToken,
+    bytes_me2c: &AtomicU64,
+    conn_id: u64,
+    ack_flush_immediate: bool,
+    batched: bool,
+) -> Result<MeWriterResponseOutcome>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    match response {
+        MeResponse::Data { flags, data, .. } => {
+            if batched {
+                trace!(conn_id, bytes = data.len(), flags, "ME->C data (batched)");
+            } else {
+                trace!(conn_id, bytes = data.len(), flags, "ME->C data");
+            }
+            let data_len = data.len() as u64;
+            if let (Some(limit), Some(user_stats)) = (quota_limit, quota_user_stats) {
+                let soft_limit = quota_soft_cap(limit, quota_soft_overshoot_bytes);
+                match reserve_user_quota_with_yield(
+                    user_stats, data_len, soft_limit, stats, cancel, None,
+                )
+                .await
+                {
+                    Ok(_) => {}
+                    Err(MiddleQuotaReserveError::LimitExceeded) => {
+                        stats.increment_me_d2c_quota_reject_total(MeD2cQuotaRejectStage::PreWrite);
+                        return Err(ProxyError::DataQuotaExceeded {
+                            user: user.to_string(),
+                        });
+                    }
+                    Err(MiddleQuotaReserveError::Contended) => {
+                        return Err(ProxyError::Proxy(
+                            "ME D->C quota reservation contended".into(),
+                        ));
+                    }
+                    Err(MiddleQuotaReserveError::Cancelled) => {
+                        return Err(ProxyError::Proxy(
+                            "ME D->C quota reservation cancelled".into(),
+                        ));
+                    }
+                    Err(MiddleQuotaReserveError::DeadlineExceeded) => {
+                        return Err(ProxyError::Proxy(
+                            "ME D->C quota reservation deadline exceeded".into(),
+                        ));
+                    }
+                }
+            }
+            wait_for_traffic_budget_or_cancel(
+                traffic_lease,
+                RateDirection::Down,
+                data_len,
+                cancel,
+                stats,
+                None,
+            )
+            .await?;
+
+            let write_mode = match write_client_payload(
+                client_writer,
+                proto_tag,
+                flags,
+                &data,
+                rng,
+                frame_buf,
+                cancel,
+            )
+            .await
+            {
+                Ok(mode) => mode,
+                Err(err) => {
+                    if quota_limit.is_some() {
+                        stats.add_quota_write_fail_bytes_total(data_len);
+                        stats.increment_quota_write_fail_events_total();
+                    }
+                    return Err(err);
+                }
+            };
+
+            bytes_me2c.fetch_add(data_len, Ordering::Relaxed);
+            if let Some(user_stats) = quota_user_stats {
+                stats.add_user_octets_to_handle(user_stats, data_len);
+            } else {
+                stats.add_user_octets_to(user, data_len);
+            }
+            stats.increment_me_d2c_data_frames_total();
+            stats.add_me_d2c_payload_bytes_total(data_len);
+            stats.increment_me_d2c_write_mode(write_mode);
+
+            Ok(MeWriterResponseOutcome::Continue {
+                frames: 1,
+                bytes: data.len(),
+                flush_immediately: false,
+            })
+        }
+        MeResponse::Ack(confirm) => {
+            if batched {
+                trace!(conn_id, confirm, "ME->C quickack (batched)");
+            } else {
+                trace!(conn_id, confirm, "ME->C quickack");
+            }
+            wait_for_traffic_budget_or_cancel(
+                traffic_lease,
+                RateDirection::Down,
+                4,
+                cancel,
+                stats,
+                None,
+            )
+            .await?;
+            write_client_ack(client_writer, proto_tag, confirm, cancel).await?;
+            stats.increment_me_d2c_ack_frames_total();
+
+            Ok(MeWriterResponseOutcome::Continue {
+                frames: 1,
+                bytes: 4,
+                flush_immediately: ack_flush_immediate,
+            })
+        }
+        MeResponse::Close => {
+            if batched {
+                debug!(conn_id, "ME sent close (batched)");
+            } else {
+                debug!(conn_id, "ME sent close");
+            }
+            Ok(MeWriterResponseOutcome::Close)
+        }
+    }
+}
+
+/// Computes the intermediate/secure wire length while rejecting lossy casts.
+pub(in crate::proxy::middle_relay) fn compute_intermediate_secure_wire_len(
+    data_len: usize,
+    padding_len: usize,
+    quickack: bool,
+) -> Result<(u32, usize)> {
+    let wire_len = data_len
+        .checked_add(padding_len)
+        .ok_or_else(|| ProxyError::Proxy("Frame length overflow".into()))?;
+    if wire_len > 0x7fff_ffffusize {
+        return Err(ProxyError::Proxy(format!(
+            "Intermediate/Secure frame too large: {wire_len}"
+        )));
+    }
+
+    let total = 4usize
+        .checked_add(wire_len)
+        .ok_or_else(|| ProxyError::Proxy("Frame buffer size overflow".into()))?;
+    let mut len_val = u32::try_from(wire_len)
+        .map_err(|_| ProxyError::Proxy("Frame length conversion overflow".into()))?;
+    if quickack {
+        len_val |= 0x8000_0000;
+    }
+    Ok((len_val, total))
+}
+
+pub(super) async fn write_client_payload<W>(
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    flags: u32,
+    data: &[u8],
+    rng: &SecureRandom,
+    frame_buf: &mut Vec<u8>,
+    cancel: &CancellationToken,
+) -> Result<MeD2cWriteMode>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let quickack = (flags & RPC_FLAG_QUICKACK) != 0;
+
+    let write_mode = match proto_tag {
+        ProtoTag::Abridged => {
+            if !data.len().is_multiple_of(4) {
+                return Err(ProxyError::Proxy(format!(
+                    "Abridged payload must be 4-byte aligned, got {}",
+                    data.len()
+                )));
+            }
+
+            let len_words = data.len() / 4;
+            if len_words < 0x7f {
+                let mut first = len_words as u8;
+                if quickack {
+                    first |= 0x80;
+                }
+                let wire_len = 1usize.saturating_add(data.len());
+                if wire_len <= ME_D2C_SINGLE_WRITE_COALESCE_MAX_BYTES {
+                    frame_buf.clear();
+                    frame_buf.reserve(wire_len);
+                    frame_buf.push(first);
+                    frame_buf.extend_from_slice(data);
+                    write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                    MeD2cWriteMode::Coalesced
+                } else {
+                    let header = [first];
+                    write_all_client_or_cancel(client_writer, &header, cancel).await?;
+                    write_all_client_or_cancel(client_writer, data, cancel).await?;
+                    MeD2cWriteMode::Split
+                }
+            } else if len_words < (1 << 24) {
+                let mut first = 0x7fu8;
+                if quickack {
+                    first |= 0x80;
+                }
+                let lw = (len_words as u32).to_le_bytes();
+                let wire_len = 4usize.saturating_add(data.len());
+                if wire_len <= ME_D2C_SINGLE_WRITE_COALESCE_MAX_BYTES {
+                    frame_buf.clear();
+                    frame_buf.reserve(wire_len);
+                    frame_buf.extend_from_slice(&[first, lw[0], lw[1], lw[2]]);
+                    frame_buf.extend_from_slice(data);
+                    write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                    MeD2cWriteMode::Coalesced
+                } else {
+                    let header = [first, lw[0], lw[1], lw[2]];
+                    write_all_client_or_cancel(client_writer, &header, cancel).await?;
+                    write_all_client_or_cancel(client_writer, data, cancel).await?;
+                    MeD2cWriteMode::Split
+                }
+            } else {
+                return Err(ProxyError::Proxy(format!(
+                    "Abridged frame too large: {}",
+                    data.len()
+                )));
+            }
+        }
+        ProtoTag::Intermediate | ProtoTag::Secure => {
+            let padding_len = if proto_tag == ProtoTag::Secure {
+                if !is_valid_secure_payload_len(data.len()) {
+                    return Err(ProxyError::Proxy(format!(
+                        "Secure payload must be 4-byte aligned, got {}",
+                        data.len()
+                    )));
+                }
+                secure_padding_len(data.len(), rng)
+            } else {
+                0
+            };
+
+            let (len_val, total) =
+                compute_intermediate_secure_wire_len(data.len(), padding_len, quickack)?;
+            if total <= ME_D2C_SINGLE_WRITE_COALESCE_MAX_BYTES {
+                frame_buf.clear();
+                frame_buf.reserve(total);
+                frame_buf.extend_from_slice(&len_val.to_le_bytes());
+                frame_buf.extend_from_slice(data);
+                if padding_len > 0 {
+                    let start = frame_buf.len();
+                    frame_buf.resize(start + padding_len, 0);
+                    rng.fill(&mut frame_buf[start..]);
+                }
+                write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                MeD2cWriteMode::Coalesced
+            } else {
+                let header = len_val.to_le_bytes();
+                write_all_client_or_cancel(client_writer, &header, cancel).await?;
+                write_all_client_or_cancel(client_writer, data, cancel).await?;
+                if padding_len > 0 {
+                    frame_buf.clear();
+                    if frame_buf.capacity() < padding_len {
+                        frame_buf.reserve(padding_len);
+                    }
+                    frame_buf.resize(padding_len, 0);
+                    rng.fill(frame_buf.as_mut_slice());
+                    write_all_client_or_cancel(client_writer, frame_buf.as_slice(), cancel).await?;
+                }
+                MeD2cWriteMode::Split
+            }
+        }
+    };
+
+    Ok(write_mode)
+}
+
+pub(super) async fn write_client_ack<W>(
+    client_writer: &mut CryptoWriter<W>,
+    proto_tag: ProtoTag,
+    confirm: u32,
+    cancel: &CancellationToken,
+) -> Result<()>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let bytes = if proto_tag == ProtoTag::Abridged {
+        confirm.to_be_bytes()
+    } else {
+        confirm.to_le_bytes()
+    };
+    write_all_client_or_cancel(client_writer, &bytes, cancel).await
+}
+
+pub(super) async fn write_all_client_or_cancel<W>(
+    client_writer: &mut CryptoWriter<W>,
+    bytes: &[u8],
+    cancel: &CancellationToken,
+) -> Result<()>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    tokio::select! {
+        biased;
+        _ = cancel.cancelled() => Err(ProxyError::MiddleClientWriterCancelled),
+        result = client_writer.write_all(bytes) => result.map_err(ProxyError::Io),
+    }
+}
+
+pub(super) async fn flush_client_or_cancel<W>(
+    client_writer: &mut CryptoWriter<W>,
+    cancel: &CancellationToken,
+) -> Result<()>
+where
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    tokio::select! {
+        biased;
+        _ = cancel.cancelled() => Err(ProxyError::MiddleClientWriterCancelled),
+        result = client_writer.flush() => result.map_err(ProxyError::Io),
+    }
+}
@@ -0,0 +1,406 @@
+use super::*;
+
+#[derive(Default)]
+pub(crate) struct DesyncDedupRotationState {
+    current_started_at: Option<Instant>,
+}
+
+pub(in crate::proxy::middle_relay) struct RelayForensicsState {
+    pub(in crate::proxy::middle_relay) trace_id: u64,
+    pub(in crate::proxy::middle_relay) conn_id: u64,
+    pub(in crate::proxy::middle_relay) user: String,
+    pub(in crate::proxy::middle_relay) peer: SocketAddr,
+    pub(in crate::proxy::middle_relay) peer_hash: u64,
+    pub(in crate::proxy::middle_relay) started_at: Instant,
+    pub(in crate::proxy::middle_relay) bytes_c2me: u64,
+    pub(in crate::proxy::middle_relay) bytes_me2c: Arc<AtomicU64>,
+    pub(in crate::proxy::middle_relay) desync_all_full: bool,
+}
+
+#[cfg(test)]
+pub(crate) fn hash_value<T: Hash>(value: &T) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    value.hash(&mut hasher);
+    hasher.finish()
+}
+
+fn hash_value_in<T: Hash>(shared: &ProxySharedState, value: &T) -> u64 {
+    shared.middle_relay.desync_hasher.hash_one(value)
+}
+
+#[cfg(test)]
+pub(crate) fn hash_ip(ip: IpAddr) -> u64 {
+    hash_value(&ip)
+}
+
+pub(super) fn hash_ip_in(shared: &ProxySharedState, ip: IpAddr) -> u64 {
+    hash_value_in(shared, &ip)
+}
+
+fn should_emit_full_desync_in(
+    shared: &ProxySharedState,
+    key: u64,
+    all_full: bool,
+    now: Instant,
+) -> bool {
+    if all_full {
+        return true;
+    }
+
+    let dedup_current = &shared.middle_relay.desync_dedup;
+    let dedup_previous = &shared.middle_relay.desync_dedup_previous;
+    let rotation_state = &shared.middle_relay.desync_dedup_rotation_state;
+
+    let mut state = match rotation_state.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut guard = poisoned.into_inner();
+            *guard = DesyncDedupRotationState::default();
+            rotation_state.clear_poison();
+            guard
+        }
+    };
+
+    let rotate_now = match state.current_started_at {
+        Some(current_started_at) => match now.checked_duration_since(current_started_at) {
+            Some(elapsed) => elapsed >= DESYNC_DEDUP_WINDOW,
+            None => true,
+        },
+        None => true,
+    };
+    if rotate_now {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+    }
+
+    if let Some(seen_at) = dedup_current.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            return false;
+        }
+        dedup_current.insert(key, now);
+        return true;
+    }
+
+    if let Some(seen_at) = dedup_previous.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            dedup_current.insert(key, seen_at);
+            return false;
+        }
+        dedup_previous.remove(&key);
+    }
+
+    if dedup_current.len() >= DESYNC_DEDUP_MAX_ENTRIES {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+        dedup_current.insert(key, now);
+        should_emit_full_desync_full_cache_in(shared, now)
+    } else {
+        dedup_current.insert(key, now);
+        true
+    }
+}
+
+fn should_emit_full_desync_full_cache_in(shared: &ProxySharedState, now: Instant) -> bool {
+    let gate = &shared.middle_relay.desync_full_cache_last_emit_at;
+    let Ok(mut last_emit_at) = gate.lock() else {
+        return false;
+    };
+
+    match *last_emit_at {
+        None => {
+            *last_emit_at = Some(now);
+            true
+        }
+        Some(last) => {
+            let Some(elapsed) = now.checked_duration_since(last) else {
+                *last_emit_at = Some(now);
+                return true;
+            };
+            if elapsed >= DESYNC_FULL_CACHE_EMIT_MIN_INTERVAL {
+                *last_emit_at = Some(now);
+                true
+            } else {
+                false
+            }
+        }
+    }
+}
+
+pub(crate) fn desync_forensics_len_bytes(len: usize) -> ([u8; 4], bool) {
+    match u32::try_from(len) {
+        Ok(value) => (value.to_le_bytes(), false),
+        Err(_) => (u32::MAX.to_le_bytes(), true),
+    }
+}
+
+pub(super) fn report_desync_frame_too_large_in(
+    shared: &ProxySharedState,
+    state: &RelayForensicsState,
+    proto_tag: ProtoTag,
+    frame_counter: u64,
+    max_frame: usize,
+    len: usize,
+    raw_len_bytes: Option<[u8; 4]>,
+    stats: &Stats,
+) -> ProxyError {
+    let (fallback_len_buf, len_buf_truncated) = desync_forensics_len_bytes(len);
+    let len_buf = raw_len_bytes.unwrap_or(fallback_len_buf);
+    let looks_like_tls = raw_len_bytes
+        .map(|b| b[0] == 0x16 && b[1] == 0x03)
+        .unwrap_or(false);
+    let looks_like_http = raw_len_bytes
+        .map(|b| matches!(b[0], b'G' | b'P' | b'H' | b'C' | b'D'))
+        .unwrap_or(false);
+    let now = Instant::now();
+    let dedup_key = hash_value_in(
+        shared,
+        &(
+            state.user.as_str(),
+            state.peer_hash,
+            proto_tag,
+            DESYNC_ERROR_CLASS,
+        ),
+    );
+    let emit_full = should_emit_full_desync_in(shared, dedup_key, state.desync_all_full, now);
+    let duration_ms = state.started_at.elapsed().as_millis() as u64;
+    let bytes_me2c = state.bytes_me2c.load(Ordering::Relaxed);
+
+    stats.increment_desync_total();
+    stats.increment_relay_protocol_desync_close_total();
+    stats.observe_desync_frames_ok(frame_counter);
+    if emit_full {
+        stats.increment_desync_full_logged();
+        warn!(
+            trace_id = format_args!("0x{:016x}", state.trace_id),
+            conn_id = state.conn_id,
+            user = %state.user,
+            peer_hash = format_args!("0x{:016x}", state.peer_hash),
+            proto = ?proto_tag,
+            mode = "middle_proxy",
+            is_tls = true,
+            duration_ms,
+            bytes_c2me = state.bytes_c2me,
+            bytes_me2c,
+            raw_len = len,
+            raw_len_hex = format_args!("0x{:08x}", len),
+            raw_len_bytes_truncated = len_buf_truncated,
+            raw_bytes = format_args!(
+                "{:02x} {:02x} {:02x} {:02x}",
+                len_buf[0], len_buf[1], len_buf[2], len_buf[3]
+            ),
+            max_frame,
+            tls_like = looks_like_tls,
+            http_like = looks_like_http,
+            frames_ok = frame_counter,
+            dedup_window_secs = DESYNC_DEDUP_WINDOW.as_secs(),
+            desync_all_full = state.desync_all_full,
+            full_reason = if state.desync_all_full { "desync_all_full" } else { "first_in_dedup_window" },
+            error_class = DESYNC_ERROR_CLASS,
+            "Frame too large — crypto desync forensics"
+        );
+        debug!(
+            trace_id = format_args!("0x{:016x}", state.trace_id),
+            conn_id = state.conn_id,
+            user = %state.user,
+            peer = %state.peer,
+            "Frame too large forensic peer detail"
+        );
+    } else {
+        stats.increment_desync_suppressed();
+        debug!(
+            trace_id = format_args!("0x{:016x}", state.trace_id),
+            conn_id = state.conn_id,
+            user = %state.user,
+            peer_hash = format_args!("0x{:016x}", state.peer_hash),
+            proto = ?proto_tag,
+            duration_ms,
+            bytes_c2me = state.bytes_c2me,
+            bytes_me2c,
+            raw_len = len,
+            frames_ok = frame_counter,
+            dedup_window_secs = DESYNC_DEDUP_WINDOW.as_secs(),
+            error_class = DESYNC_ERROR_CLASS,
+            "Frame too large — crypto desync forensic suppressed"
+        );
+    }
+
+    ProxyError::Proxy(format!(
+        "Frame too large: {len} (max {max_frame}), frames_ok={frame_counter}, conn_id={}, trace_id=0x{:016x}",
+        state.conn_id, state.trace_id
+    ))
+}
+
+#[cfg(test)]
+pub(crate) fn report_desync_frame_too_large(
+    state: &RelayForensicsState,
+    proto_tag: ProtoTag,
+    frame_counter: u64,
+    max_frame: usize,
+    len: usize,
+    raw_len_bytes: Option<[u8; 4]>,
+    stats: &Stats,
+) -> ProxyError {
+    let shared = ProxySharedState::new();
+    report_desync_frame_too_large_in(
+        shared.as_ref(),
+        state,
+        proto_tag,
+        frame_counter,
+        max_frame,
+        len,
+        raw_len_bytes,
+        stats,
+    )
+}
+
+#[cfg(test)]
+pub(crate) fn should_emit_full_desync_for_testing(
+    shared: &ProxySharedState,
+    key: u64,
+    all_full: bool,
+    now: Instant,
+) -> bool {
+    if all_full {
+        return true;
+    }
+
+    let dedup_current = &shared.middle_relay.desync_dedup;
+    let dedup_previous = &shared.middle_relay.desync_dedup_previous;
+
+    let Ok(mut state) = shared.middle_relay.desync_dedup_rotation_state.lock() else {
+        return false;
+    };
+
+    let rotate_now = match state.current_started_at {
+        Some(current_started_at) => match now.checked_duration_since(current_started_at) {
+            Some(elapsed) => elapsed >= DESYNC_DEDUP_WINDOW,
+            None => true,
+        },
+        None => true,
+    };
+    if rotate_now {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+    }
+
+    if let Some(seen_at) = dedup_current.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            return false;
+        }
+        dedup_current.insert(key, now);
+        return true;
+    }
+
+    if let Some(seen_at) = dedup_previous.get(&key).map(|entry| *entry.value()) {
+        let within_window = match now.checked_duration_since(seen_at) {
+            Some(elapsed) => elapsed < DESYNC_DEDUP_WINDOW,
+            None => true,
+        };
+        if within_window {
+            dedup_current.insert(key, seen_at);
+            return false;
+        }
+        dedup_previous.remove(&key);
+    }
+
+    if dedup_current.len() >= DESYNC_DEDUP_MAX_ENTRIES {
+        dedup_previous.clear();
+        for entry in dedup_current.iter() {
+            dedup_previous.insert(*entry.key(), *entry.value());
+        }
+        dedup_current.clear();
+        state.current_started_at = Some(now);
+        dedup_current.insert(key, now);
+        let Ok(mut last_emit_at) = shared.middle_relay.desync_full_cache_last_emit_at.lock() else {
+            return false;
+        };
+        return match *last_emit_at {
+            None => {
+                *last_emit_at = Some(now);
+                true
+            }
+            Some(last) => {
+                let Some(elapsed) = now.checked_duration_since(last) else {
+                    *last_emit_at = Some(now);
+                    return true;
+                };
+                if elapsed >= DESYNC_FULL_CACHE_EMIT_MIN_INTERVAL {
+                    *last_emit_at = Some(now);
+                    true
+                } else {
+                    false
+                }
+            }
+        };
+    }
+
+    dedup_current.insert(key, now);
+    true
+}
+
+#[cfg(test)]
+pub(crate) fn clear_desync_dedup_for_testing_in_shared(shared: &ProxySharedState) {
+    shared.middle_relay.desync_dedup.clear();
+    shared.middle_relay.desync_dedup_previous.clear();
+    if let Ok(mut rotation_state) = shared.middle_relay.desync_dedup_rotation_state.lock() {
+        *rotation_state = DesyncDedupRotationState::default();
+    }
+    if let Ok(mut last_emit_at) = shared.middle_relay.desync_full_cache_last_emit_at.lock() {
+        *last_emit_at = None;
+    }
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_len_for_testing(shared: &ProxySharedState) -> usize {
+    shared.middle_relay.desync_dedup.len()
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_insert_for_testing(shared: &ProxySharedState, key: u64, at: Instant) {
+    shared.middle_relay.desync_dedup.insert(key, at);
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_get_for_testing(shared: &ProxySharedState, key: u64) -> Option<Instant> {
+    shared
+        .middle_relay
+        .desync_dedup
+        .get(&key)
+        .map(|entry| *entry.value())
+}
+
+#[cfg(test)]
+pub(crate) fn desync_dedup_keys_for_testing(
+    shared: &ProxySharedState,
+) -> std::collections::HashSet<u64> {
+    shared
+        .middle_relay
+        .desync_dedup
+        .iter()
+        .map(|entry| *entry.key())
+        .collect()
+}
@@ -0,0 +1,341 @@
+use super::*;
+
+mod read;
+
+pub(crate) use self::read::read_client_payload_with_idle_policy_in;
+#[cfg(test)]
+pub(crate) use self::read::{
+    read_client_payload, read_client_payload_legacy, read_client_payload_with_idle_policy,
+};
+
+#[derive(Default)]
+pub(crate) struct RelayIdleCandidateRegistry {
+    pub(in crate::proxy::middle_relay) by_conn_id: HashMap<u64, RelayIdleCandidateMeta>,
+    pub(in crate::proxy::middle_relay) ordered: BTreeSet<(u64, u64)>,
+    pressure_event_seq: u64,
+    pressure_consumed_seq: u64,
+}
+
+/// Queue metadata used to preserve FIFO ordering for idle relay eviction.
+#[derive(Clone, Copy)]
+pub(in crate::proxy::middle_relay) struct RelayIdleCandidateMeta {
+    pub(in crate::proxy::middle_relay) mark_order_seq: u64,
+    pub(in crate::proxy::middle_relay) mark_pressure_seq: u64,
+}
+
+pub(super) fn relay_idle_candidate_registry_lock_in(
+    shared: &ProxySharedState,
+) -> std::sync::MutexGuard<'_, RelayIdleCandidateRegistry> {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    match registry.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut guard = poisoned.into_inner();
+            *guard = RelayIdleCandidateRegistry::default();
+            registry.clear_poison();
+            guard
+        }
+    }
+}
+
+pub(super) fn mark_relay_idle_candidate_in(shared: &ProxySharedState, conn_id: u64) -> bool {
+    let mut guard = relay_idle_candidate_registry_lock_in(shared);
+
+    if guard.by_conn_id.contains_key(&conn_id) {
+        return false;
+    }
+
+    let mark_order_seq = shared
+        .middle_relay
+        .relay_idle_mark_seq
+        .fetch_add(1, Ordering::Relaxed)
+        .saturating_add(1);
+    let meta = RelayIdleCandidateMeta {
+        mark_order_seq,
+        mark_pressure_seq: guard.pressure_event_seq,
+    };
+    guard.by_conn_id.insert(conn_id, meta);
+    guard.ordered.insert((meta.mark_order_seq, conn_id));
+    true
+}
+
+pub(super) fn clear_relay_idle_candidate_in(shared: &ProxySharedState, conn_id: u64) {
+    let mut guard = relay_idle_candidate_registry_lock_in(shared);
+
+    if let Some(meta) = guard.by_conn_id.remove(&conn_id) {
+        guard.ordered.remove(&(meta.mark_order_seq, conn_id));
+    }
+}
+
+pub(super) fn note_relay_pressure_event_in(shared: &ProxySharedState) {
+    let mut guard = relay_idle_candidate_registry_lock_in(shared);
+    guard.pressure_event_seq = guard.pressure_event_seq.wrapping_add(1);
+}
+
+pub(crate) fn note_global_relay_pressure(shared: &ProxySharedState) {
+    note_relay_pressure_event_in(shared);
+}
+
+pub(super) fn relay_pressure_event_seq_in(shared: &ProxySharedState) -> u64 {
+    let guard = relay_idle_candidate_registry_lock_in(shared);
+    guard.pressure_event_seq
+}
+
+pub(super) fn maybe_evict_idle_candidate_on_pressure_in(
+    shared: &ProxySharedState,
+    conn_id: u64,
+    seen_pressure_seq: &mut u64,
+    stats: &Stats,
+) -> bool {
+    let mut guard = relay_idle_candidate_registry_lock_in(shared);
+
+    let latest_pressure_seq = guard.pressure_event_seq;
+    if latest_pressure_seq == *seen_pressure_seq {
+        return false;
+    }
+    *seen_pressure_seq = latest_pressure_seq;
+
+    if latest_pressure_seq == guard.pressure_consumed_seq {
+        return false;
+    }
+
+    if guard.ordered.is_empty() {
+        guard.pressure_consumed_seq = latest_pressure_seq;
+        return false;
+    }
+
+    let oldest = guard
+        .ordered
+        .iter()
+        .next()
+        .map(|(_, candidate_conn_id)| *candidate_conn_id);
+    if oldest != Some(conn_id) {
+        return false;
+    }
+
+    let Some(candidate_meta) = guard.by_conn_id.get(&conn_id).copied() else {
+        return false;
+    };
+
+    if latest_pressure_seq == candidate_meta.mark_pressure_seq {
+        return false;
+    }
+
+    if let Some(meta) = guard.by_conn_id.remove(&conn_id) {
+        guard.ordered.remove(&(meta.mark_order_seq, conn_id));
+    }
+    guard.pressure_consumed_seq = latest_pressure_seq;
+    stats.increment_relay_pressure_evict_total();
+    true
+}
+
+#[derive(Clone, Copy)]
+pub(in crate::proxy::middle_relay) struct RelayClientIdlePolicy {
+    pub(in crate::proxy::middle_relay) enabled: bool,
+    pub(in crate::proxy::middle_relay) soft_idle: Duration,
+    pub(in crate::proxy::middle_relay) hard_idle: Duration,
+    pub(in crate::proxy::middle_relay) grace_after_downstream_activity: Duration,
+    pub(in crate::proxy::middle_relay) legacy_frame_read_timeout: Duration,
+}
+
+impl RelayClientIdlePolicy {
+    pub(super) fn from_config(config: &ProxyConfig) -> Self {
+        let frame_read_timeout =
+            Duration::from_secs(config.timeouts.relay_client_idle_hard_secs.max(1));
+        if !config.timeouts.relay_idle_policy_v2_enabled {
+            return Self::disabled(frame_read_timeout);
+        }
+
+        let soft_idle = Duration::from_secs(config.timeouts.relay_client_idle_soft_secs.max(1));
+        let hard_idle = Duration::from_secs(config.timeouts.relay_client_idle_hard_secs.max(1));
+        let grace_after_downstream_activity = Duration::from_secs(
+            config
+                .timeouts
+                .relay_idle_grace_after_downstream_activity_secs,
+        );
+
+        Self {
+            enabled: true,
+            soft_idle,
+            hard_idle,
+            grace_after_downstream_activity,
+            legacy_frame_read_timeout: frame_read_timeout,
+        }
+    }
+
+    pub(in crate::proxy::middle_relay) fn disabled(frame_read_timeout: Duration) -> Self {
+        Self {
+            enabled: false,
+            soft_idle: frame_read_timeout,
+            hard_idle: frame_read_timeout,
+            grace_after_downstream_activity: Duration::ZERO,
+            legacy_frame_read_timeout: frame_read_timeout,
+        }
+    }
+
+    pub(super) fn apply_pressure_caps(&mut self, profile: ConntrackPressureProfile) {
+        let pressure_soft_idle_cap = Duration::from_secs(profile.middle_soft_idle_cap_secs());
+        let pressure_hard_idle_cap = Duration::from_secs(profile.middle_hard_idle_cap_secs());
+
+        self.soft_idle = self.soft_idle.min(pressure_soft_idle_cap);
+        self.hard_idle = self.hard_idle.min(pressure_hard_idle_cap);
+        if self.soft_idle > self.hard_idle {
+            self.soft_idle = self.hard_idle;
+        }
+        self.legacy_frame_read_timeout = self.legacy_frame_read_timeout.min(pressure_hard_idle_cap);
+        if self.grace_after_downstream_activity > self.hard_idle {
+            self.grace_after_downstream_activity = self.hard_idle;
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+pub(in crate::proxy::middle_relay) struct RelayClientIdleState {
+    pub(in crate::proxy::middle_relay) last_client_frame_at: Instant,
+    pub(in crate::proxy::middle_relay) soft_idle_marked: bool,
+    pub(in crate::proxy::middle_relay) tiny_frame_debt: u32,
+}
+
+impl RelayClientIdleState {
+    pub(super) fn new(now: Instant) -> Self {
+        Self {
+            last_client_frame_at: now,
+            soft_idle_marked: false,
+            tiny_frame_debt: 0,
+        }
+    }
+
+    pub(super) fn on_client_frame(&mut self, now: Instant) {
+        self.last_client_frame_at = now;
+        self.soft_idle_marked = false;
+    }
+
+    pub(super) fn on_client_tiny_frame(&mut self, now: Instant) {
+        self.last_client_frame_at = now;
+    }
+}
+
+#[cfg(test)]
+pub(crate) fn mark_relay_idle_candidate_for_testing(
+    shared: &ProxySharedState,
+    conn_id: u64,
+) -> bool {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    let mut guard = match registry.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut guard = poisoned.into_inner();
+            *guard = RelayIdleCandidateRegistry::default();
+            registry.clear_poison();
+            guard
+        }
+    };
+
+    if guard.by_conn_id.contains_key(&conn_id) {
+        return false;
+    }
+
+    let mark_order_seq = shared
+        .middle_relay
+        .relay_idle_mark_seq
+        .fetch_add(1, Ordering::Relaxed);
+    let mark_pressure_seq = guard.pressure_event_seq;
+    let meta = RelayIdleCandidateMeta {
+        mark_order_seq,
+        mark_pressure_seq,
+    };
+    guard.by_conn_id.insert(conn_id, meta);
+    guard.ordered.insert((mark_order_seq, conn_id));
+    true
+}
+
+#[cfg(test)]
+pub(crate) fn oldest_relay_idle_candidate_for_testing(shared: &ProxySharedState) -> Option<u64> {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    let guard = match registry.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut guard = poisoned.into_inner();
+            *guard = RelayIdleCandidateRegistry::default();
+            registry.clear_poison();
+            guard
+        }
+    };
+    guard.ordered.iter().next().map(|(_, conn_id)| *conn_id)
+}
+
+#[cfg(test)]
+pub(crate) fn clear_relay_idle_candidate_for_testing(shared: &ProxySharedState, conn_id: u64) {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    let mut guard = match registry.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut guard = poisoned.into_inner();
+            *guard = RelayIdleCandidateRegistry::default();
+            registry.clear_poison();
+            guard
+        }
+    };
+    if let Some(meta) = guard.by_conn_id.remove(&conn_id) {
+        guard.ordered.remove(&(meta.mark_order_seq, conn_id));
+    }
+}
+
+#[cfg(test)]
+pub(crate) fn clear_relay_idle_pressure_state_for_testing_in_shared(shared: &ProxySharedState) {
+    if let Ok(mut guard) = shared.middle_relay.relay_idle_registry.lock() {
+        *guard = RelayIdleCandidateRegistry::default();
+    }
+    shared
+        .middle_relay
+        .relay_idle_mark_seq
+        .store(0, Ordering::Relaxed);
+}
+
+#[cfg(test)]
+pub(crate) fn note_relay_pressure_event_for_testing(shared: &ProxySharedState) {
+    note_relay_pressure_event_in(shared);
+}
+
+#[cfg(test)]
+pub(crate) fn relay_pressure_event_seq_for_testing(shared: &ProxySharedState) -> u64 {
+    relay_pressure_event_seq_in(shared)
+}
+
+#[cfg(test)]
+pub(crate) fn relay_idle_mark_seq_for_testing(shared: &ProxySharedState) -> u64 {
+    shared
+        .middle_relay
+        .relay_idle_mark_seq
+        .load(Ordering::Relaxed)
+}
+
+#[cfg(test)]
+pub(crate) fn maybe_evict_idle_candidate_on_pressure_for_testing(
+    shared: &ProxySharedState,
+    conn_id: u64,
+    seen_pressure_seq: &mut u64,
+    stats: &Stats,
+) -> bool {
+    maybe_evict_idle_candidate_on_pressure_in(shared, conn_id, seen_pressure_seq, stats)
+}
+
+#[cfg(test)]
+pub(crate) fn set_relay_pressure_state_for_testing(
+    shared: &ProxySharedState,
+    pressure_event_seq: u64,
+    pressure_consumed_seq: u64,
+) {
+    let registry = &shared.middle_relay.relay_idle_registry;
+    let mut guard = match registry.lock() {
+        Ok(guard) => guard,
+        Err(poisoned) => {
+            let mut guard = poisoned.into_inner();
+            *guard = RelayIdleCandidateRegistry::default();
+            registry.clear_poison();
+            guard
+        }
+    };
+    guard.pressure_event_seq = pressure_event_seq;
+    guard.pressure_consumed_seq = pressure_consumed_seq;
+}
@@ -0,0 +1,442 @@
+use super::*;
+
+pub(crate) async fn read_client_payload_with_idle_policy_in<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+    shared: &ProxySharedState,
+    idle_policy: &RelayClientIdlePolicy,
+    idle_state: &mut RelayClientIdleState,
+    last_downstream_activity_ms: &AtomicU64,
+    session_started_at: Instant,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    const LEGACY_MAX_CONSECUTIVE_ZERO_LEN_FRAMES: u32 = 4;
+
+    async fn read_exact_with_policy<R>(
+        client_reader: &mut CryptoReader<R>,
+        buf: &mut [u8],
+        idle_policy: &RelayClientIdlePolicy,
+        idle_state: &mut RelayClientIdleState,
+        last_downstream_activity_ms: &AtomicU64,
+        session_started_at: Instant,
+        forensics: &RelayForensicsState,
+        stats: &Stats,
+        shared: &ProxySharedState,
+        read_label: &'static str,
+    ) -> Result<()>
+    where
+        R: AsyncRead + Unpin + Send + 'static,
+    {
+        fn hard_deadline(
+            idle_policy: &RelayClientIdlePolicy,
+            idle_state: &RelayClientIdleState,
+            session_started_at: Instant,
+            last_downstream_activity_ms: u64,
+        ) -> Instant {
+            let mut deadline = idle_state.last_client_frame_at + idle_policy.hard_idle;
+            if idle_policy.grace_after_downstream_activity.is_zero() {
+                return deadline;
+            }
+
+            let downstream_at =
+                session_started_at + Duration::from_millis(last_downstream_activity_ms);
+            if downstream_at > idle_state.last_client_frame_at {
+                let grace_deadline = downstream_at + idle_policy.grace_after_downstream_activity;
+                if grace_deadline > deadline {
+                    deadline = grace_deadline;
+                }
+            }
+            deadline
+        }
+
+        let mut filled = 0usize;
+        while filled < buf.len() {
+            let timeout_window = if idle_policy.enabled {
+                let now = Instant::now();
+                let downstream_ms = last_downstream_activity_ms.load(Ordering::Relaxed);
+                let hard_deadline =
+                    hard_deadline(idle_policy, idle_state, session_started_at, downstream_ms);
+                if !idle_state.soft_idle_marked
+                    && now.saturating_duration_since(idle_state.last_client_frame_at)
+                        >= idle_policy.soft_idle
+                {
+                    idle_state.soft_idle_marked = true;
+                    if mark_relay_idle_candidate_in(shared, forensics.conn_id) {
+                        stats.increment_relay_idle_soft_mark_total();
+                    }
+                    info!(
+                        trace_id = format_args!("0x{:016x}", forensics.trace_id),
+                        conn_id = forensics.conn_id,
+                        user = %forensics.user,
+                        read_label,
+                        soft_idle_secs = idle_policy.soft_idle.as_secs(),
+                        hard_idle_secs = idle_policy.hard_idle.as_secs(),
+                        grace_secs = idle_policy.grace_after_downstream_activity.as_secs(),
+                        "Middle-relay soft idle mark"
+                    );
+                }
+
+                let soft_deadline = idle_state.last_client_frame_at + idle_policy.soft_idle;
+                let next_deadline = if idle_state.soft_idle_marked {
+                    hard_deadline
+                } else {
+                    soft_deadline.min(hard_deadline)
+                };
+                let mut remaining = next_deadline.saturating_duration_since(now);
+                if remaining.is_zero() {
+                    remaining = Duration::from_millis(1);
+                }
+                remaining.min(RELAY_IDLE_IO_POLL_MAX)
+            } else {
+                idle_policy.legacy_frame_read_timeout
+            };
+
+            let read_result = timeout(timeout_window, client_reader.read(&mut buf[filled..])).await;
+            match read_result {
+                Ok(Ok(0)) => {
+                    return Err(ProxyError::Io(std::io::Error::from(
+                        std::io::ErrorKind::UnexpectedEof,
+                    )));
+                }
+                Ok(Ok(n)) => {
+                    filled = filled.saturating_add(n);
+                }
+                Ok(Err(e)) => return Err(ProxyError::Io(e)),
+                Err(_) if !idle_policy.enabled => {
+                    return Err(ProxyError::Io(std::io::Error::new(
+                        std::io::ErrorKind::TimedOut,
+                        format!(
+                            "middle-relay client frame read timeout while reading {read_label}"
+                        ),
+                    )));
+                }
+                Err(_) => {
+                    let now = Instant::now();
+                    let downstream_ms = last_downstream_activity_ms.load(Ordering::Relaxed);
+                    let hard_deadline =
+                        hard_deadline(idle_policy, idle_state, session_started_at, downstream_ms);
+                    if now >= hard_deadline {
+                        clear_relay_idle_candidate_in(shared, forensics.conn_id);
+                        stats.increment_relay_idle_hard_close_total();
+                        let client_idle_secs = now
+                            .saturating_duration_since(idle_state.last_client_frame_at)
+                            .as_secs();
+                        let downstream_idle_secs = now
+                            .saturating_duration_since(
+                                session_started_at + Duration::from_millis(downstream_ms),
+                            )
+                            .as_secs();
+                        warn!(
+                            trace_id = format_args!("0x{:016x}", forensics.trace_id),
+                            conn_id = forensics.conn_id,
+                            user = %forensics.user,
+                            read_label,
+                            client_idle_secs,
+                            downstream_idle_secs,
+                            soft_idle_secs = idle_policy.soft_idle.as_secs(),
+                            hard_idle_secs = idle_policy.hard_idle.as_secs(),
+                            grace_secs = idle_policy.grace_after_downstream_activity.as_secs(),
+                            "Middle-relay hard idle close"
+                        );
+                        return Err(ProxyError::Io(std::io::Error::new(
+                            std::io::ErrorKind::TimedOut,
+                            format!(
+                                "middle-relay hard idle timeout while reading {read_label}: client_idle_secs={client_idle_secs}, downstream_idle_secs={downstream_idle_secs}, soft_idle_secs={}, hard_idle_secs={}, grace_secs={}",
+                                idle_policy.soft_idle.as_secs(),
+                                idle_policy.hard_idle.as_secs(),
+                                idle_policy.grace_after_downstream_activity.as_secs(),
+                            ),
+                        )));
+                    }
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    let mut consecutive_zero_len_frames = 0u32;
+    loop {
+        let (len, quickack, raw_len_bytes) = match proto_tag {
+            ProtoTag::Abridged => {
+                let mut first = [0u8; 1];
+                match read_exact_with_policy(
+                    client_reader,
+                    &mut first,
+                    idle_policy,
+                    idle_state,
+                    last_downstream_activity_ms,
+                    session_started_at,
+                    forensics,
+                    stats,
+                    shared,
+                    "abridged.first_len_byte",
+                )
+                .await
+                {
+                    Ok(()) => {}
+                    Err(ProxyError::Io(e)) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
+                        return Ok(None);
+                    }
+                    Err(e) => return Err(e),
+                }
+
+                let quickack = (first[0] & 0x80) != 0;
+                let len_words = if (first[0] & 0x7f) == 0x7f {
+                    let mut ext = [0u8; 3];
+                    read_exact_with_policy(
+                        client_reader,
+                        &mut ext,
+                        idle_policy,
+                        idle_state,
+                        last_downstream_activity_ms,
+                        session_started_at,
+                        forensics,
+                        stats,
+                        shared,
+                        "abridged.extended_len",
+                    )
+                    .await?;
+                    u32::from_le_bytes([ext[0], ext[1], ext[2], 0]) as usize
+                } else {
+                    (first[0] & 0x7f) as usize
+                };
+
+                let len = len_words
+                    .checked_mul(4)
+                    .ok_or_else(|| ProxyError::Proxy("Abridged frame length overflow".into()))?;
+                (len, quickack, None)
+            }
+            ProtoTag::Intermediate | ProtoTag::Secure => {
+                let mut len_buf = [0u8; 4];
+                match read_exact_with_policy(
+                    client_reader,
+                    &mut len_buf,
+                    idle_policy,
+                    idle_state,
+                    last_downstream_activity_ms,
+                    session_started_at,
+                    forensics,
+                    stats,
+                    shared,
+                    "len_prefix",
+                )
+                .await
+                {
+                    Ok(()) => {}
+                    Err(ProxyError::Io(e)) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
+                        return Ok(None);
+                    }
+                    Err(e) => return Err(e),
+                }
+                let quickack = (len_buf[3] & 0x80) != 0;
+                (
+                    (u32::from_le_bytes(len_buf) & 0x7fff_ffff) as usize,
+                    quickack,
+                    Some(len_buf),
+                )
+            }
+        };
+
+        if len == 0 {
+            idle_state.on_client_tiny_frame(Instant::now());
+            idle_state.tiny_frame_debt = idle_state
+                .tiny_frame_debt
+                .saturating_add(TINY_FRAME_DEBT_PER_TINY);
+            if idle_state.tiny_frame_debt >= TINY_FRAME_DEBT_LIMIT {
+                stats.increment_relay_protocol_desync_close_total();
+                return Err(ProxyError::Proxy(format!(
+                    "Tiny frame overhead limit exceeded: debt={}, conn_id={}",
+                    idle_state.tiny_frame_debt, forensics.conn_id
+                )));
+            }
+
+            if !idle_policy.enabled {
+                consecutive_zero_len_frames = consecutive_zero_len_frames.saturating_add(1);
+                if consecutive_zero_len_frames > LEGACY_MAX_CONSECUTIVE_ZERO_LEN_FRAMES {
+                    stats.increment_relay_protocol_desync_close_total();
+                    return Err(ProxyError::Proxy(
+                        "Excessive zero-length abridged frames".to_string(),
+                    ));
+                }
+            }
+            continue;
+        }
+        if len < 4 && proto_tag != ProtoTag::Abridged {
+            warn!(
+                trace_id = format_args!("0x{:016x}", forensics.trace_id),
+                conn_id = forensics.conn_id,
+                user = %forensics.user,
+                len,
+                proto = ?proto_tag,
+                "Frame too small — corrupt or probe"
+            );
+            stats.increment_relay_protocol_desync_close_total();
+            return Err(ProxyError::Proxy(format!("Frame too small: {len}")));
+        }
+
+        if len > max_frame {
+            return Err(report_desync_frame_too_large_in(
+                shared,
+                forensics,
+                proto_tag,
+                *frame_counter,
+                max_frame,
+                len,
+                raw_len_bytes,
+                stats,
+            ));
+        }
+
+        let secure_payload_len = if proto_tag == ProtoTag::Secure {
+            match secure_payload_len_from_wire_len(len) {
+                Some(payload_len) => payload_len,
+                None => {
+                    stats.increment_secure_padding_invalid();
+                    stats.increment_relay_protocol_desync_close_total();
+                    return Err(ProxyError::Proxy(format!(
+                        "Invalid secure frame length: {len}"
+                    )));
+                }
+            }
+        } else {
+            len
+        };
+
+        let mut payload = buffer_pool.get();
+        payload.clear();
+        let current_cap = payload.capacity();
+        if current_cap < len {
+            payload.reserve(len - current_cap);
+        }
+        payload.resize(len, 0);
+        read_exact_with_policy(
+            client_reader,
+            &mut payload[..len],
+            idle_policy,
+            idle_state,
+            last_downstream_activity_ms,
+            session_started_at,
+            forensics,
+            stats,
+            shared,
+            "payload",
+        )
+        .await?;
+
+        // Secure Intermediate: strip validated trailing padding bytes.
+        if proto_tag == ProtoTag::Secure {
+            payload.truncate(secure_payload_len);
+        }
+        *frame_counter += 1;
+        idle_state.on_client_frame(Instant::now());
+        idle_state.tiny_frame_debt = idle_state.tiny_frame_debt.saturating_sub(1);
+        clear_relay_idle_candidate_in(shared, forensics.conn_id);
+        return Ok(Some((payload, quickack)));
+    }
+}
+
+#[cfg(test)]
+pub(crate) async fn read_client_payload_with_idle_policy<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+    idle_policy: &RelayClientIdlePolicy,
+    idle_state: &mut RelayClientIdleState,
+    last_downstream_activity_ms: &AtomicU64,
+    session_started_at: Instant,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    let shared = ProxySharedState::new();
+    read_client_payload_with_idle_policy_in(
+        client_reader,
+        proto_tag,
+        max_frame,
+        buffer_pool,
+        forensics,
+        frame_counter,
+        stats,
+        shared.as_ref(),
+        idle_policy,
+        idle_state,
+        last_downstream_activity_ms,
+        session_started_at,
+    )
+    .await
+}
+
+#[cfg(test)]
+pub(crate) async fn read_client_payload_legacy<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    frame_read_timeout: Duration,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    let now = Instant::now();
+    let shared = ProxySharedState::new();
+    let mut idle_state = RelayClientIdleState::new(now);
+    let last_downstream_activity_ms = AtomicU64::new(0);
+    let idle_policy = RelayClientIdlePolicy::disabled(frame_read_timeout);
+    read_client_payload_with_idle_policy_in(
+        client_reader,
+        proto_tag,
+        max_frame,
+        buffer_pool,
+        forensics,
+        frame_counter,
+        stats,
+        shared.as_ref(),
+        &idle_policy,
+        &mut idle_state,
+        &last_downstream_activity_ms,
+        now,
+    )
+    .await
+}
+
+#[cfg(test)]
+pub(crate) async fn read_client_payload<R>(
+    client_reader: &mut CryptoReader<R>,
+    proto_tag: ProtoTag,
+    max_frame: usize,
+    frame_read_timeout: Duration,
+    buffer_pool: &Arc<BufferPool>,
+    forensics: &RelayForensicsState,
+    frame_counter: &mut u64,
+    stats: &Stats,
+) -> Result<Option<(PooledBuffer, bool)>>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+{
+    read_client_payload_legacy(
+        client_reader,
+        proto_tag,
+        max_frame,
+        frame_read_timeout,
+        buffer_pool,
+        forensics,
+        frame_counter,
+        stats,
+    )
+    .await
+}
@@ -0,0 +1,151 @@
+use super::*;
+
+pub(super) enum MiddleQuotaReserveError {
+    LimitExceeded,
+    Contended,
+    Cancelled,
+    DeadlineExceeded,
+}
+
+pub(super) fn quota_soft_cap(limit: u64, overshoot: u64) -> u64 {
+    limit.saturating_add(overshoot)
+}
+
+pub(super) async fn reserve_user_quota_with_yield(
+    user_stats: &UserStats,
+    bytes: u64,
+    limit: u64,
+    stats: &Stats,
+    cancel: &CancellationToken,
+    deadline: Option<Instant>,
+) -> std::result::Result<u64, MiddleQuotaReserveError> {
+    let mut backoff_ms = QUOTA_RESERVE_BACKOFF_MIN_MS;
+    let mut backoff_rounds = 0usize;
+    loop {
+        for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+            match user_stats.quota_try_reserve(bytes, limit) {
+                Ok(total) => return Ok(total),
+                Err(QuotaReserveError::LimitExceeded) => {
+                    return Err(MiddleQuotaReserveError::LimitExceeded);
+                }
+                Err(QuotaReserveError::Contended) => {
+                    stats.increment_quota_contention_total();
+                    std::hint::spin_loop();
+                }
+            }
+        }
+
+        tokio::task::yield_now().await;
+        if deadline.is_some_and(|deadline| Instant::now() >= deadline) {
+            stats.increment_quota_contention_timeout_total();
+            return Err(MiddleQuotaReserveError::DeadlineExceeded);
+        }
+        tokio::select! {
+            _ = tokio::time::sleep(Duration::from_millis(backoff_ms)) => {}
+            _ = cancel.cancelled() => {
+                stats.increment_quota_acquire_cancelled_total();
+                return Err(MiddleQuotaReserveError::Cancelled);
+            }
+        }
+        backoff_rounds = backoff_rounds.saturating_add(1);
+        if backoff_rounds >= QUOTA_RESERVE_MAX_BACKOFF_ROUNDS {
+            stats.increment_quota_contention_timeout_total();
+            return Err(MiddleQuotaReserveError::Contended);
+        }
+        backoff_ms = backoff_ms
+            .saturating_mul(2)
+            .min(QUOTA_RESERVE_BACKOFF_MAX_MS);
+    }
+}
+
+pub(super) async fn wait_for_traffic_budget(
+    lease: Option<&Arc<TrafficLease>>,
+    direction: RateDirection,
+    bytes: u64,
+    deadline: Option<Instant>,
+) -> Result<()> {
+    if bytes == 0 {
+        return Ok(());
+    }
+    let Some(lease) = lease else {
+        return Ok(());
+    };
+
+    let mut remaining = bytes;
+    while remaining > 0 {
+        let consume = lease.try_consume(direction, remaining);
+        if consume.granted > 0 {
+            remaining = remaining.saturating_sub(consume.granted);
+            continue;
+        }
+
+        let wait_started_at = Instant::now();
+        if deadline.is_some_and(|deadline| wait_started_at >= deadline) {
+            return Err(ProxyError::TrafficBudgetWaitDeadlineExceeded);
+        }
+        tokio::time::sleep(next_refill_delay()).await;
+        let wait_ms = wait_started_at
+            .elapsed()
+            .as_millis()
+            .min(u128::from(u64::MAX)) as u64;
+        lease.observe_wait_ms(
+            direction,
+            consume.blocked_user,
+            consume.blocked_cidr,
+            wait_ms,
+        );
+    }
+
+    Ok(())
+}
+
+pub(super) async fn wait_for_traffic_budget_or_cancel(
+    lease: Option<&Arc<TrafficLease>>,
+    direction: RateDirection,
+    bytes: u64,
+    cancel: &CancellationToken,
+    stats: &Stats,
+    deadline: Option<Instant>,
+) -> Result<()> {
+    if bytes == 0 {
+        return Ok(());
+    }
+    let Some(lease) = lease else {
+        return Ok(());
+    };
+
+    let mut remaining = bytes;
+    while remaining > 0 {
+        let consume = lease.try_consume(direction, remaining);
+        if consume.granted > 0 {
+            remaining = remaining.saturating_sub(consume.granted);
+            continue;
+        }
+
+        let wait_started_at = Instant::now();
+        if deadline.is_some_and(|deadline| wait_started_at >= deadline) {
+            stats.increment_flow_wait_middle_rate_limit_cancelled_total();
+            return Err(ProxyError::TrafficBudgetWaitDeadlineExceeded);
+        }
+        tokio::select! {
+            _ = tokio::time::sleep(next_refill_delay()) => {}
+            _ = cancel.cancelled() => {
+                stats.increment_flow_wait_middle_rate_limit_cancelled_total();
+                return Err(ProxyError::TrafficBudgetWaitCancelled);
+            }
+        }
+        let wait_ms = wait_started_at
+            .elapsed()
+            .as_millis()
+            .min(u128::from(u64::MAX)) as u64;
+        lease.observe_wait_ms(
+            direction,
+            consume.blocked_user,
+            consume.blocked_cidr,
+            wait_ms,
+        );
+        stats.observe_flow_wait_middle_rate_limit_ms(wait_ms);
+    }
+
+    Ok(())
+}
@@ -0,0 +1,830 @@
+use super::*;
+
+pub(crate) async fn handle_via_middle_proxy<R, W>(
+    mut crypto_reader: CryptoReader<R>,
+    crypto_writer: CryptoWriter<W>,
+    success: HandshakeSuccess,
+    me_pool: Arc<MePool>,
+    stats: Arc<Stats>,
+    config: Arc<ProxyConfig>,
+    buffer_pool: Arc<BufferPool>,
+    local_addr: SocketAddr,
+    rng: Arc<SecureRandom>,
+    mut route_rx: watch::Receiver<RouteCutoverState>,
+    route_snapshot: RouteCutoverState,
+    session_id: u64,
+    shared: Arc<ProxySharedState>,
+) -> Result<()>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let user = success.user.clone();
+    let quota_limit = config.access.user_data_quota.get(&user).copied();
+    let quota_user_stats = quota_limit.map(|_| stats.get_or_create_user_stats_handle(&user));
+    let peer = success.peer;
+    let traffic_lease = shared.traffic_limiter.acquire_lease(&user, peer.ip());
+    let proto_tag = success.proto_tag;
+    let pool_generation = me_pool.current_generation();
+
+    debug!(
+        user = %user,
+        peer = %peer,
+        dc = success.dc_idx,
+        proto = ?proto_tag,
+        mode = "middle_proxy",
+        pool_generation,
+        "Routing via Middle-End"
+    );
+
+    let (conn_id, me_rx) = me_pool.registry().register().await;
+    let trace_id = session_id;
+    let bytes_me2c = Arc::new(AtomicU64::new(0));
+    let mut forensics = RelayForensicsState {
+        trace_id,
+        conn_id,
+        user: user.clone(),
+        peer,
+        peer_hash: hash_ip_in(shared.as_ref(), peer.ip()),
+        started_at: Instant::now(),
+        bytes_c2me: 0,
+        bytes_me2c: bytes_me2c.clone(),
+        desync_all_full: config.general.desync_all_full,
+    };
+
+    stats.increment_user_connects(&user);
+    let _me_connection_lease = stats.acquire_me_connection_lease();
+
+    if let Some(cutover) =
+        affected_cutover_state(&route_rx, RelayRouteMode::Middle, route_snapshot.generation)
+    {
+        let delay = cutover_stagger_delay(session_id, cutover.generation);
+        warn!(
+            conn_id,
+            target_mode = cutover.mode.as_str(),
+            cutover_generation = cutover.generation,
+            delay_ms = delay.as_millis() as u64,
+            "Cutover affected middle session before relay start, closing client connection"
+        );
+        let _cutover_park_lease = stats.acquire_middle_cutover_park_lease();
+        tokio::time::sleep(delay).await;
+        let _ = me_pool.send_close(conn_id).await;
+        me_pool.registry().unregister(conn_id).await;
+        return Err(ProxyError::RouteSwitched);
+    }
+
+    // Per-user ad_tag from access.user_ad_tags; fallback to general.ad_tag (hot-reloadable)
+    let user_tag: Option<Vec<u8>> = config
+        .access
+        .user_ad_tags
+        .get(&user)
+        .and_then(|s| hex::decode(s).ok())
+        .filter(|v| v.len() == 16);
+    let global_tag: Option<Vec<u8>> = config
+        .general
+        .ad_tag
+        .as_ref()
+        .and_then(|s| hex::decode(s).ok())
+        .filter(|v| v.len() == 16);
+    let effective_tag = user_tag.or(global_tag);
+
+    let proto_flags = proto_flags_for_tag(proto_tag, effective_tag.is_some());
+    let effective_tag_array = effective_tag
+        .as_deref()
+        .and_then(|tag| <[u8; 16]>::try_from(tag).ok());
+    debug!(
+        trace_id = format_args!("0x{:016x}", trace_id),
+        user = %user,
+        conn_id,
+        peer_hash = format_args!("0x{:016x}", forensics.peer_hash),
+        desync_all_full = forensics.desync_all_full,
+        proto_flags = format_args!("0x{:08x}", proto_flags),
+        pool_generation,
+        "ME relay started"
+    );
+
+    let translated_local_addr = me_pool.translate_our_addr(local_addr);
+
+    let frame_limit = config.general.max_client_frame;
+    let mut relay_idle_policy = RelayClientIdlePolicy::from_config(&config);
+    let mut pressure_caps_applied = false;
+    if shared.conntrack_pressure_active() {
+        relay_idle_policy.apply_pressure_caps(config.server.conntrack_control.profile);
+        pressure_caps_applied = true;
+    }
+    let session_started_at = forensics.started_at;
+    let mut relay_idle_state = RelayClientIdleState::new(session_started_at);
+    let last_downstream_activity_ms = Arc::new(AtomicU64::new(0));
+
+    let c2me_channel_capacity = config
+        .general
+        .me_c2me_channel_capacity
+        .max(C2ME_CHANNEL_CAPACITY_FALLBACK);
+    let c2me_send_timeout = match config.general.me_c2me_send_timeout_ms {
+        0 => None,
+        timeout_ms => Some(Duration::from_millis(timeout_ms)),
+    };
+    let c2me_byte_budget = c2me_queued_permit_budget(c2me_channel_capacity, frame_limit);
+    let c2me_byte_semaphore = Arc::new(Semaphore::new(c2me_byte_budget));
+    let (c2me_tx, mut c2me_rx) = mpsc::channel::<C2MeCommand>(c2me_channel_capacity);
+    let me_pool_c2me = me_pool.clone();
+    let mut c2me_sender = tokio::spawn(async move {
+        let mut sent_since_yield = 0usize;
+        while let Some(cmd) = c2me_rx.recv().await {
+            match cmd {
+                C2MeCommand::Data {
+                    payload,
+                    flags,
+                    _permit,
+                } => {
+                    me_pool_c2me
+                        .send_proxy_req_pooled(
+                            conn_id,
+                            success.dc_idx,
+                            peer,
+                            translated_local_addr,
+                            payload,
+                            flags,
+                            effective_tag_array,
+                        )
+                        .await?;
+                    sent_since_yield = sent_since_yield.saturating_add(1);
+                    if should_yield_c2me_sender(sent_since_yield, !c2me_rx.is_empty()) {
+                        sent_since_yield = 0;
+                        tokio::task::yield_now().await;
+                    }
+                }
+                C2MeCommand::Close => {
+                    let _ = me_pool_c2me.send_close(conn_id).await;
+                    return Ok(());
+                }
+            }
+        }
+        Ok(())
+    });
+
+    let (stop_tx, mut stop_rx) = oneshot::channel::<()>();
+    let flow_cancel = CancellationToken::new();
+    let mut me_rx_task = me_rx;
+    let stats_clone = stats.clone();
+    let rng_clone = rng.clone();
+    let user_clone = user.clone();
+    let quota_user_stats_me_writer = quota_user_stats.clone();
+    let traffic_lease_me_writer = traffic_lease.clone();
+    let flow_cancel_me_writer = flow_cancel.clone();
+    let last_downstream_activity_ms_clone = last_downstream_activity_ms.clone();
+    let bytes_me2c_clone = bytes_me2c.clone();
+    let d2c_flush_policy = MeD2cFlushPolicy::from_config(&config);
+    let mut me_writer = tokio::spawn(async move {
+        let mut writer = crypto_writer;
+        let mut frame_buf = Vec::with_capacity(16 * 1024);
+        let shrink_threshold = d2c_flush_policy.frame_buf_shrink_threshold_bytes;
+
+        fn shrink_session_vec(buf: &mut Vec<u8>, threshold: usize) {
+            if buf.capacity() > threshold {
+                buf.clear();
+                buf.shrink_to(threshold);
+            } else {
+                buf.clear();
+            }
+        }
+
+        loop {
+            tokio::select! {
+                msg = me_rx_task.recv() => {
+                    let Some(first) = msg else {
+                        debug!(conn_id, "ME channel closed");
+                        shrink_session_vec(&mut frame_buf, shrink_threshold);
+                        return Err(ProxyError::MiddleConnectionLost);
+                    };
+
+                    let mut batch_frames = 0usize;
+                    let mut batch_bytes = 0usize;
+                    let mut flush_immediately;
+                    let mut max_delay_fired = false;
+
+                    let first_is_downstream_activity =
+                        matches!(&first, MeResponse::Data { .. } | MeResponse::Ack(_));
+                    match process_me_writer_response_with_traffic_lease(
+                        first,
+                        &mut writer,
+                        proto_tag,
+                        rng_clone.as_ref(),
+                        &mut frame_buf,
+                        stats_clone.as_ref(),
+                        &user_clone,
+                        quota_user_stats_me_writer.as_deref(),
+                        quota_limit,
+                        d2c_flush_policy.quota_soft_overshoot_bytes,
+                        traffic_lease_me_writer.as_ref(),
+                        &flow_cancel_me_writer,
+                        bytes_me2c_clone.as_ref(),
+                        conn_id,
+                        d2c_flush_policy.ack_flush_immediate,
+                        false,
+                    ).await? {
+                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                            if first_is_downstream_activity {
+                                last_downstream_activity_ms_clone
+                                    .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                            }
+                            batch_frames = batch_frames.saturating_add(frames);
+                            batch_bytes = batch_bytes.saturating_add(bytes);
+                            flush_immediately = immediate;
+                        }
+                        MeWriterResponseOutcome::Close => {
+                            let flush_started_at = if stats_clone.telemetry_policy().me_level.allows_debug() {
+                                Some(Instant::now())
+                            } else {
+                                None
+                            };
+                            let _ = flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await;
+                            let flush_duration_us = flush_started_at.map(|started| {
+                                started
+                                    .elapsed()
+                                    .as_micros()
+                                    .min(u128::from(u64::MAX)) as u64
+                            });
+                            observe_me_d2c_flush_event(
+                                stats_clone.as_ref(),
+                                MeD2cFlushReason::Close,
+                                batch_frames,
+                                batch_bytes,
+                                flush_duration_us,
+                            );
+                            shrink_session_vec(&mut frame_buf, shrink_threshold);
+                            return Ok(());
+                        }
+                    }
+
+                    while !flush_immediately
+                        && batch_frames < d2c_flush_policy.max_frames
+                        && batch_bytes < d2c_flush_policy.max_bytes
+                    {
+                        let Ok(next) = me_rx_task.try_recv() else {
+                            break;
+                        };
+
+                        let next_is_downstream_activity =
+                            matches!(&next, MeResponse::Data { .. } | MeResponse::Ack(_));
+                        match process_me_writer_response_with_traffic_lease(
+                            next,
+                            &mut writer,
+                            proto_tag,
+                            rng_clone.as_ref(),
+                            &mut frame_buf,
+                            stats_clone.as_ref(),
+                            &user_clone,
+                            quota_user_stats_me_writer.as_deref(),
+                            quota_limit,
+                            d2c_flush_policy.quota_soft_overshoot_bytes,
+                            traffic_lease_me_writer.as_ref(),
+                            &flow_cancel_me_writer,
+                            bytes_me2c_clone.as_ref(),
+                            conn_id,
+                            d2c_flush_policy.ack_flush_immediate,
+                            true,
+                        ).await? {
+                            MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                if next_is_downstream_activity {
+                                    last_downstream_activity_ms_clone
+                                        .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                                }
+                                batch_frames = batch_frames.saturating_add(frames);
+                                batch_bytes = batch_bytes.saturating_add(bytes);
+                                flush_immediately |= immediate;
+                            }
+                            MeWriterResponseOutcome::Close => {
+                                let flush_started_at =
+                                    if stats_clone.telemetry_policy().me_level.allows_debug() {
+                                        Some(Instant::now())
+                                    } else {
+                                        None
+                                    };
+                                let _ =
+                                    flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await;
+                                let flush_duration_us = flush_started_at.map(|started| {
+                                    started
+                                        .elapsed()
+                                        .as_micros()
+                                        .min(u128::from(u64::MAX))
+                                        as u64
+                                });
+                                observe_me_d2c_flush_event(
+                                    stats_clone.as_ref(),
+                                    MeD2cFlushReason::Close,
+                                    batch_frames,
+                                    batch_bytes,
+                                    flush_duration_us,
+                                );
+                                shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                return Ok(());
+                            }
+                        }
+                    }
+
+                    if !flush_immediately
+                        && !d2c_flush_policy.max_delay.is_zero()
+                        && batch_frames < d2c_flush_policy.max_frames
+                        && batch_bytes < d2c_flush_policy.max_bytes
+                    {
+                        stats_clone.increment_me_d2c_batch_timeout_armed_total();
+                        match tokio::time::timeout(d2c_flush_policy.max_delay, me_rx_task.recv()).await {
+                            Ok(Some(next)) => {
+                                let next_is_downstream_activity =
+                                    matches!(&next, MeResponse::Data { .. } | MeResponse::Ack(_));
+                                match process_me_writer_response_with_traffic_lease(
+                                    next,
+                                    &mut writer,
+                                    proto_tag,
+                                    rng_clone.as_ref(),
+                                    &mut frame_buf,
+                                    stats_clone.as_ref(),
+                                    &user_clone,
+                                    quota_user_stats_me_writer.as_deref(),
+                                    quota_limit,
+                                    d2c_flush_policy.quota_soft_overshoot_bytes,
+                                    traffic_lease_me_writer.as_ref(),
+                                    &flow_cancel_me_writer,
+                                    bytes_me2c_clone.as_ref(),
+                                    conn_id,
+                                    d2c_flush_policy.ack_flush_immediate,
+                                    true,
+                                ).await? {
+                                    MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                        if next_is_downstream_activity {
+                                            last_downstream_activity_ms_clone
+                                                .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                                        }
+                                        batch_frames = batch_frames.saturating_add(frames);
+                                        batch_bytes = batch_bytes.saturating_add(bytes);
+                                        flush_immediately |= immediate;
+                                    }
+                                    MeWriterResponseOutcome::Close => {
+                                        let flush_started_at = if stats_clone
+                                            .telemetry_policy()
+                                            .me_level
+                                            .allows_debug()
+                                        {
+                                            Some(Instant::now())
+                                        } else {
+                                            None
+                                        };
+                                        let _ = flush_client_or_cancel(
+                                            &mut writer,
+                                            &flow_cancel_me_writer,
+                                        )
+                                        .await;
+                                        let flush_duration_us = flush_started_at.map(|started| {
+                                            started
+                                                .elapsed()
+                                                .as_micros()
+                                                .min(u128::from(u64::MAX))
+                                                as u64
+                                        });
+                                        observe_me_d2c_flush_event(
+                                            stats_clone.as_ref(),
+                                            MeD2cFlushReason::Close,
+                                            batch_frames,
+                                            batch_bytes,
+                                            flush_duration_us,
+                                        );
+                                        shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                        return Ok(());
+                                    }
+                                }
+
+                                while !flush_immediately
+                                    && batch_frames < d2c_flush_policy.max_frames
+                                    && batch_bytes < d2c_flush_policy.max_bytes
+                                {
+                                    let Ok(extra) = me_rx_task.try_recv() else {
+                                        break;
+                                    };
+
+                                    let extra_is_downstream_activity =
+                                        matches!(&extra, MeResponse::Data { .. } | MeResponse::Ack(_));
+                                    match process_me_writer_response_with_traffic_lease(
+                                        extra,
+                                        &mut writer,
+                                        proto_tag,
+                                        rng_clone.as_ref(),
+                                        &mut frame_buf,
+                                        stats_clone.as_ref(),
+                                        &user_clone,
+                                        quota_user_stats_me_writer.as_deref(),
+                                        quota_limit,
+                                        d2c_flush_policy.quota_soft_overshoot_bytes,
+                                        traffic_lease_me_writer.as_ref(),
+                                        &flow_cancel_me_writer,
+                                        bytes_me2c_clone.as_ref(),
+                                        conn_id,
+                                        d2c_flush_policy.ack_flush_immediate,
+                                        true,
+                                    ).await? {
+                                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                            if extra_is_downstream_activity {
+                                                last_downstream_activity_ms_clone
+                                                    .store(session_started_at.elapsed().as_millis() as u64, Ordering::Relaxed);
+                                            }
+                                            batch_frames = batch_frames.saturating_add(frames);
+                                            batch_bytes = batch_bytes.saturating_add(bytes);
+                                            flush_immediately |= immediate;
+                                        }
+                                        MeWriterResponseOutcome::Close => {
+                                            let flush_started_at = if stats_clone
+                                                .telemetry_policy()
+                                                .me_level
+                                                .allows_debug()
+                                            {
+                                                Some(Instant::now())
+                                            } else {
+                                                None
+                                            };
+                                            let _ = flush_client_or_cancel(
+                                                &mut writer,
+                                                &flow_cancel_me_writer,
+                                            )
+                                            .await;
+                                            let flush_duration_us = flush_started_at.map(|started| {
+                                                started
+                                                    .elapsed()
+                                                    .as_micros()
+                                                    .min(u128::from(u64::MAX))
+                                                    as u64
+                                            });
+                                            observe_me_d2c_flush_event(
+                                                stats_clone.as_ref(),
+                                                MeD2cFlushReason::Close,
+                                                batch_frames,
+                                                batch_bytes,
+                                                flush_duration_us,
+                                            );
+                                            shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                            return Ok(());
+                                        }
+                                    }
+                                }
+                            }
+                            Ok(None) => {
+                                debug!(conn_id, "ME channel closed");
+                                shrink_session_vec(&mut frame_buf, shrink_threshold);
+                                return Err(ProxyError::MiddleConnectionLost);
+                            }
+                            Err(_) => {
+                                max_delay_fired = true;
+                                stats_clone.increment_me_d2c_batch_timeout_fired_total();
+                            }
+                        }
+                    }
+
+                    let flush_reason = classify_me_d2c_flush_reason(
+                        flush_immediately,
+                        batch_frames,
+                        d2c_flush_policy.max_frames,
+                        batch_bytes,
+                        d2c_flush_policy.max_bytes,
+                        max_delay_fired,
+                    );
+                    let flush_started_at = if stats_clone.telemetry_policy().me_level.allows_debug() {
+                        Some(Instant::now())
+                    } else {
+                        None
+                    };
+                    flush_client_or_cancel(&mut writer, &flow_cancel_me_writer).await?;
+                    let flush_duration_us = flush_started_at.map(|started| {
+                        started
+                            .elapsed()
+                            .as_micros()
+                            .min(u128::from(u64::MAX)) as u64
+                    });
+                    observe_me_d2c_flush_event(
+                        stats_clone.as_ref(),
+                        flush_reason,
+                        batch_frames,
+                        batch_bytes,
+                        flush_duration_us,
+                    );
+                    let shrink_threshold = d2c_flush_policy.frame_buf_shrink_threshold_bytes;
+                    let shrink_trigger = shrink_threshold
+                        .saturating_mul(ME_D2C_FRAME_BUF_SHRINK_HYSTERESIS_FACTOR);
+                    if frame_buf.capacity() > shrink_trigger {
+                        let cap_before = frame_buf.capacity();
+                        frame_buf.shrink_to(shrink_threshold);
+                        let cap_after = frame_buf.capacity();
+                        let bytes_freed = cap_before.saturating_sub(cap_after) as u64;
+                        stats_clone.observe_me_d2c_frame_buf_shrink(bytes_freed);
+                    }
+                }
+                _ = &mut stop_rx => {
+                    debug!(conn_id, "ME writer stop signal");
+                    shrink_session_vec(&mut frame_buf, shrink_threshold);
+                    return Ok(());
+                }
+            }
+        }
+    });
+
+    let mut main_result: Result<()> = Ok(());
+    let mut client_closed = false;
+    let mut frame_counter: u64 = 0;
+    let mut route_watch_open = true;
+    let mut seen_pressure_seq = relay_pressure_event_seq_in(shared.as_ref());
+    loop {
+        if shared.conntrack_pressure_active() && !pressure_caps_applied {
+            relay_idle_policy.apply_pressure_caps(config.server.conntrack_control.profile);
+            pressure_caps_applied = true;
+        }
+
+        if relay_idle_policy.enabled
+            && maybe_evict_idle_candidate_on_pressure_in(
+                shared.as_ref(),
+                conn_id,
+                &mut seen_pressure_seq,
+                stats.as_ref(),
+            )
+        {
+            info!(
+                conn_id,
+                trace_id = format_args!("0x{:016x}", trace_id),
+                user = %user,
+                "Middle-relay pressure eviction for idle-candidate session"
+            );
+            let _ = enqueue_c2me_command_in(
+                shared.as_ref(),
+                &c2me_tx,
+                C2MeCommand::Close,
+                c2me_send_timeout,
+                stats.as_ref(),
+            )
+            .await;
+            main_result = Err(ProxyError::Proxy(
+                "middle-relay session evicted under pressure (idle-candidate)".to_string(),
+            ));
+            break;
+        }
+
+        if let Some(cutover) =
+            affected_cutover_state(&route_rx, RelayRouteMode::Middle, route_snapshot.generation)
+        {
+            let delay = cutover_stagger_delay(session_id, cutover.generation);
+            warn!(
+                conn_id,
+                target_mode = cutover.mode.as_str(),
+                cutover_generation = cutover.generation,
+                delay_ms = delay.as_millis() as u64,
+                "Cutover affected middle session, closing client connection"
+            );
+            let _cutover_park_lease = stats.acquire_middle_cutover_park_lease();
+            tokio::time::sleep(delay).await;
+            let _ = enqueue_c2me_command_in(
+                shared.as_ref(),
+                &c2me_tx,
+                C2MeCommand::Close,
+                c2me_send_timeout,
+                stats.as_ref(),
+            )
+            .await;
+            main_result = Err(ProxyError::RouteSwitched);
+            break;
+        }
+
+        tokio::select! {
+            changed = route_rx.changed(), if route_watch_open => {
+                if changed.is_err() {
+                    route_watch_open = false;
+                }
+            }
+            payload_result = read_client_payload_with_idle_policy_in(
+                &mut crypto_reader,
+                proto_tag,
+                frame_limit,
+                &buffer_pool,
+                &forensics,
+                &mut frame_counter,
+                &stats,
+                shared.as_ref(),
+                &relay_idle_policy,
+                &mut relay_idle_state,
+                last_downstream_activity_ms.as_ref(),
+                session_started_at,
+            ) => {
+                match payload_result {
+                    Ok(Some((payload, quickack))) => {
+                        trace!(conn_id, bytes = payload.len(), "C->ME frame");
+                        wait_for_traffic_budget(
+                            traffic_lease.as_ref(),
+                            RateDirection::Up,
+                            payload.len() as u64,
+                            None,
+                        )
+                        .await?;
+                        forensics.bytes_c2me = forensics
+                            .bytes_c2me
+                            .saturating_add(payload.len() as u64);
+                        if let (Some(limit), Some(user_stats)) =
+                            (quota_limit, quota_user_stats.as_deref())
+                        {
+                            match reserve_user_quota_with_yield(
+                                user_stats,
+                                payload.len() as u64,
+                                limit,
+                                stats.as_ref(),
+                                &flow_cancel,
+                                None,
+                            )
+                            .await
+                            {
+                                Ok(_) => {}
+                                Err(MiddleQuotaReserveError::LimitExceeded) => {
+                                    main_result = Err(ProxyError::DataQuotaExceeded {
+                                        user: user.clone(),
+                                    });
+                                    break;
+                                }
+                                Err(MiddleQuotaReserveError::Contended) => {
+                                    main_result = Err(ProxyError::Proxy(
+                                        "ME C->ME quota reservation contended".into(),
+                                    ));
+                                    break;
+                                }
+                                Err(MiddleQuotaReserveError::Cancelled) => {
+                                    main_result = Err(ProxyError::Proxy(
+                                        "ME C->ME quota reservation cancelled".into(),
+                                    ));
+                                    break;
+                                }
+                                Err(MiddleQuotaReserveError::DeadlineExceeded) => {
+                                    main_result = Err(ProxyError::Proxy(
+                                        "ME C->ME quota reservation deadline exceeded".into(),
+                                    ));
+                                    break;
+                                }
+                            }
+                            stats.add_user_octets_from_handle(user_stats, payload.len() as u64);
+                        } else {
+                            stats.add_user_octets_from(&user, payload.len() as u64);
+                        }
+                        let mut flags = proto_flags;
+                        if quickack {
+                            flags |= RPC_FLAG_QUICKACK;
+                        }
+                        if payload.len() >= 8 && payload[..8].iter().all(|b| *b == 0) {
+                            flags |= RPC_FLAG_NOT_ENCRYPTED;
+                        }
+                        let payload_permit = match acquire_c2me_payload_permit(
+                            &c2me_byte_semaphore,
+                            payload.len(),
+                            c2me_send_timeout,
+                            stats.as_ref(),
+                        )
+                        .await
+                        {
+                            Ok(permit) => permit,
+                            Err(e) => {
+                                main_result = Err(e);
+                                break;
+                            }
+                        };
+                        // Keep client read loop lightweight: route heavy ME send path via a dedicated task.
+                        if enqueue_c2me_command_in(
+                            shared.as_ref(),
+                            &c2me_tx,
+                            C2MeCommand::Data {
+                                payload,
+                                flags,
+                                _permit: payload_permit,
+                            },
+                            c2me_send_timeout,
+                            stats.as_ref(),
+                        )
+                        .await
+                            .is_err()
+                        {
+                            main_result = Err(ProxyError::Proxy("ME sender channel closed".into()));
+                            break;
+                        }
+                    }
+                    Ok(None) => {
+                        debug!(conn_id, "Client EOF");
+                        client_closed = true;
+                        let _ = enqueue_c2me_command_in(
+                            shared.as_ref(),
+                            &c2me_tx,
+                            C2MeCommand::Close,
+                            c2me_send_timeout,
+                            stats.as_ref(),
+                        )
+                        .await;
+                        break;
+                    }
+                    Err(e) => {
+                        main_result = Err(e);
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    drop(c2me_tx);
+    let c2me_result = match timeout(ME_CHILD_JOIN_TIMEOUT, &mut c2me_sender).await {
+        Ok(joined) => {
+            joined.unwrap_or_else(|e| Err(ProxyError::Proxy(format!("ME sender join error: {e}"))))
+        }
+        Err(_) => {
+            stats.increment_me_child_join_timeout_total();
+            stats.increment_me_child_abort_total();
+            c2me_sender.abort();
+            Err(ProxyError::Proxy("ME sender join timeout".into()))
+        }
+    };
+
+    flow_cancel.cancel();
+    let _ = stop_tx.send(());
+    let mut writer_result = match timeout(ME_CHILD_JOIN_TIMEOUT, &mut me_writer).await {
+        Ok(joined) => {
+            joined.unwrap_or_else(|e| Err(ProxyError::Proxy(format!("ME writer join error: {e}"))))
+        }
+        Err(_) => {
+            stats.increment_me_child_join_timeout_total();
+            stats.increment_me_child_abort_total();
+            me_writer.abort();
+            Err(ProxyError::Proxy("ME writer join timeout".into()))
+        }
+    };
+
+    // When client closes, but ME channel stopped as unregistered - it isnt error
+    if client_closed && matches!(writer_result, Err(ProxyError::MiddleConnectionLost)) {
+        writer_result = Ok(());
+    }
+
+    let result = match (main_result, c2me_result, writer_result) {
+        (Ok(()), Ok(()), Ok(())) => Ok(()),
+        (Err(e), _, _) => Err(e),
+        (_, Err(e), _) => Err(e),
+        (_, _, Err(e)) => Err(e),
+    };
+
+    debug!(
+        user = %user,
+        conn_id,
+        trace_id = format_args!("0x{:016x}", trace_id),
+        duration_ms = forensics.started_at.elapsed().as_millis() as u64,
+        bytes_c2me = forensics.bytes_c2me,
+        bytes_me2c = forensics.bytes_me2c.load(Ordering::Relaxed),
+        frames_ok = frame_counter,
+        "ME relay cleanup"
+    );
+
+    let close_reason = classify_conntrack_close_reason(&result);
+    let publish_result = shared.publish_conntrack_close_event(ConntrackCloseEvent {
+        src: peer,
+        dst: local_addr,
+        reason: close_reason,
+    });
+    if !matches!(
+        publish_result,
+        ConntrackClosePublishResult::Sent | ConntrackClosePublishResult::Disabled
+    ) {
+        stats.increment_conntrack_close_event_drop_total();
+    }
+
+    clear_relay_idle_candidate_in(shared.as_ref(), conn_id);
+    me_pool.registry().unregister(conn_id).await;
+    buffer_pool.trim_to(buffer_pool.max_buffers().min(64));
+    let pool_snapshot = buffer_pool.stats();
+    stats.set_buffer_pool_gauges(
+        pool_snapshot.pooled,
+        pool_snapshot.allocated,
+        pool_snapshot.allocated.saturating_sub(pool_snapshot.pooled),
+    );
+    result
+}
+
+fn classify_conntrack_close_reason(result: &Result<()>) -> ConntrackCloseReason {
+    match result {
+        Ok(()) => ConntrackCloseReason::NormalEof,
+        Err(ProxyError::Io(error)) if matches!(error.kind(), std::io::ErrorKind::TimedOut) => {
+            ConntrackCloseReason::Timeout
+        }
+        Err(ProxyError::Io(error))
+            if matches!(
+                error.kind(),
+                std::io::ErrorKind::ConnectionReset
+                    | std::io::ErrorKind::ConnectionAborted
+                    | std::io::ErrorKind::BrokenPipe
+                    | std::io::ErrorKind::NotConnected
+                    | std::io::ErrorKind::UnexpectedEof
+            ) =>
+        {
+            ConntrackCloseReason::Reset
+        }
+        Err(ProxyError::Proxy(message))
+            if message.contains("pressure") || message.contains("evicted") =>
+        {
+            ConntrackCloseReason::Pressure
+        }
+        Err(_) => ConntrackCloseReason::Other,
+    }
+}
@@ -68,6 +68,7 @@ pub mod relay;
 pub mod route_mode;
 pub mod session_eviction;
 pub mod shared_state;
+pub mod traffic_limiter;

 pub use client::ClientHandler;
 #[allow(unused_imports)]
@@ -52,17 +52,15 @@
 //! - `SharedCounters` (atomics) let the watchdog read stats without locking

 use crate::error::{ProxyError, Result};
-use crate::stats::{Stats, UserStats};
+use crate::proxy::traffic_limiter::TrafficLease;
+use crate::stats::Stats;
 use crate::stream::BufferPool;
-use std::io;
-use std::pin::Pin;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::task::{Context, Poll};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
-use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional_with_sizes};
+use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, copy_bidirectional_with_sizes};
 use tokio::time::Instant;
-use tracing::{debug, trace, warn};
+use tracing::{debug, warn};

 // ============= Constants =============

@@ -84,482 +82,11 @@ fn watchdog_delta(current: u64, previous: u64) -> u64 {
    current.saturating_sub(previous)
 }

-// ============= CombinedStream =============
-
-/// Combines separate read and write halves into a single bidirectional stream.
-///
-/// `copy_bidirectional` requires `AsyncRead + AsyncWrite` on each side,
-/// but the handshake layer produces split reader/writer pairs
-/// (e.g. `CryptoReader<FakeTlsReader<OwnedReadHalf>>` + `CryptoWriter<...>`).
-///
-/// This wrapper reunifies them with zero overhead — each trait method
-/// delegates directly to the corresponding half. No buffering, no copies.
-///
-/// Safety: `poll_read` only touches `reader`, `poll_write` only touches `writer`,
-/// so there's no aliasing even though both are called on the same `&mut self`.
-struct CombinedStream<R, W> {
-    reader: R,
-    writer: W,
-}
-
-impl<R, W> CombinedStream<R, W> {
-    fn new(reader: R, writer: W) -> Self {
-        Self { reader, writer }
-    }
-}
-
-impl<R: AsyncRead + Unpin, W: Unpin> AsyncRead for CombinedStream<R, W> {
-    #[inline]
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().reader).poll_read(cx, buf)
-    }
-}
-
-impl<R: Unpin, W: AsyncWrite + Unpin> AsyncWrite for CombinedStream<R, W> {
-    #[inline]
-    fn poll_write(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        Pin::new(&mut self.get_mut().writer).poll_write(cx, buf)
-    }
-
-    #[inline]
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().writer).poll_flush(cx)
-    }
-
-    #[inline]
-    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().writer).poll_shutdown(cx)
-    }
-}
-
-// ============= SharedCounters =============
-
-/// Atomic counters shared between the relay (via StatsIo) and the watchdog task.
-///
-/// Using `Relaxed` ordering is sufficient because:
-/// - Counters are monotonically increasing (no ABA problem)
-/// - Slight staleness in watchdog reads is harmless (±10s check interval anyway)
-/// - No ordering dependencies between different counters
-struct SharedCounters {
-    /// Bytes read from client (C→S direction)
-    c2s_bytes: AtomicU64,
-    /// Bytes written to client (S→C direction)
-    s2c_bytes: AtomicU64,
-    /// Number of poll_read completions (≈ C→S chunks)
-    c2s_ops: AtomicU64,
-    /// Number of poll_write completions (≈ S→C chunks)
-    s2c_ops: AtomicU64,
-    /// Milliseconds since relay epoch of last I/O activity
-    last_activity_ms: AtomicU64,
-}
-
-impl SharedCounters {
-    fn new() -> Self {
-        Self {
-            c2s_bytes: AtomicU64::new(0),
-            s2c_bytes: AtomicU64::new(0),
-            c2s_ops: AtomicU64::new(0),
-            s2c_ops: AtomicU64::new(0),
-            last_activity_ms: AtomicU64::new(0),
-        }
-    }
-
-    /// Record activity at this instant.
-    #[inline]
-    fn touch(&self, now: Instant, epoch: Instant) {
-        let ms = now.duration_since(epoch).as_millis() as u64;
-        self.last_activity_ms.store(ms, Ordering::Relaxed);
-    }
-
-    /// How long since last recorded activity.
-    fn idle_duration(&self, now: Instant, epoch: Instant) -> Duration {
-        let last_ms = self.last_activity_ms.load(Ordering::Relaxed);
-        let now_ms = now.duration_since(epoch).as_millis() as u64;
-        Duration::from_millis(now_ms.saturating_sub(last_ms))
-    }
-}
-
-// ============= StatsIo =============
-
-/// Transparent I/O wrapper that tracks per-user statistics and activity.
-///
-/// Wraps the **client** side of the relay. Direction mapping:
-///
-/// | poll method  | direction | stats updated                        |
-/// |-------------|-----------|--------------------------------------|
-/// | `poll_read`  | C→S       | `octets_from`, `msgs_from`, counters |
-/// | `poll_write` | S→C       | `octets_to`, `msgs_to`, counters     |
-///
-/// Both update the shared activity timestamp for the watchdog.
-///
-/// Note on message counts: the original code counted one `read()`/`write_all()`
-/// as one "message". Here we count `poll_read`/`poll_write` completions instead.
-/// Byte counts are identical; op counts may differ slightly due to different
-/// internal buffering in `copy_bidirectional`. This is fine for monitoring.
-struct StatsIo<S> {
-    inner: S,
-    counters: Arc<SharedCounters>,
-    stats: Arc<Stats>,
-    user: String,
-    user_stats: Arc<UserStats>,
-    quota_limit: Option<u64>,
-    quota_exceeded: Arc<AtomicBool>,
-    quota_bytes_since_check: u64,
-    epoch: Instant,
-}
-
-impl<S> StatsIo<S> {
-    fn new(
-        inner: S,
-        counters: Arc<SharedCounters>,
-        stats: Arc<Stats>,
-        user: String,
-        quota_limit: Option<u64>,
-        quota_exceeded: Arc<AtomicBool>,
-        epoch: Instant,
-    ) -> Self {
-        // Mark initial activity so the watchdog doesn't fire before data flows
-        counters.touch(Instant::now(), epoch);
-        let user_stats = stats.get_or_create_user_stats_handle(&user);
-        Self {
-            inner,
-            counters,
-            stats,
-            user,
-            user_stats,
-            quota_limit,
-            quota_exceeded,
-            quota_bytes_since_check: 0,
-            epoch,
-        }
-    }
-}
-
-#[derive(Debug)]
-struct QuotaIoSentinel;
-
-impl std::fmt::Display for QuotaIoSentinel {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("user data quota exceeded")
-    }
-}
-
-impl std::error::Error for QuotaIoSentinel {}
-
-fn quota_io_error() -> io::Error {
-    io::Error::new(io::ErrorKind::PermissionDenied, QuotaIoSentinel)
-}
-
-fn is_quota_io_error(err: &io::Error) -> bool {
-    err.kind() == io::ErrorKind::PermissionDenied
-        && err
-            .get_ref()
-            .and_then(|source| source.downcast_ref::<QuotaIoSentinel>())
-            .is_some()
-}
-
-const QUOTA_NEAR_LIMIT_BYTES: u64 = 64 * 1024;
-const QUOTA_LARGE_CHARGE_BYTES: u64 = 16 * 1024;
-const QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES: u64 = 4 * 1024;
-const QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES: u64 = 64 * 1024;
-const QUOTA_RESERVE_SPIN_RETRIES: usize = 64;
-const QUOTA_RESERVE_MAX_ROUNDS: usize = 8;
-
-#[inline]
-fn quota_adaptive_interval_bytes(remaining_before: u64) -> u64 {
-    remaining_before.saturating_div(2).clamp(
-        QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES,
-        QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES,
-    )
-}
-
-#[inline]
-fn should_immediate_quota_check(remaining_before: u64, charge_bytes: u64) -> bool {
-    remaining_before <= QUOTA_NEAR_LIMIT_BYTES || charge_bytes >= QUOTA_LARGE_CHARGE_BYTES
-}
-
-impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
-    fn poll_read(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &mut ReadBuf<'_>,
-    ) -> Poll<io::Result<()>> {
-        let this = self.get_mut();
-        if this.quota_exceeded.load(Ordering::Acquire) {
-            return Poll::Ready(Err(quota_io_error()));
-        }
-
-        let mut remaining_before = None;
-        if let Some(limit) = this.quota_limit {
-            let used_before = this.user_stats.quota_used();
-            let remaining = limit.saturating_sub(used_before);
-            if remaining == 0 {
-                this.quota_exceeded.store(true, Ordering::Release);
-                return Poll::Ready(Err(quota_io_error()));
-            }
-            remaining_before = Some(remaining);
-        }
-
-        let before = buf.filled().len();
-
-        match Pin::new(&mut this.inner).poll_read(cx, buf) {
-            Poll::Ready(Ok(())) => {
-                let n = buf.filled().len() - before;
-                if n > 0 {
-                    let n_to_charge = n as u64;
-
-                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
-                        let mut reserved_total = None;
-                        let mut reserve_rounds = 0usize;
-                        while reserved_total.is_none() {
-                            let mut saw_contention = false;
-                            for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
-                                match this.user_stats.quota_try_reserve(n_to_charge, limit) {
-                                    Ok(total) => {
-                                        reserved_total = Some(total);
-                                        break;
-                                    }
-                                    Err(crate::stats::QuotaReserveError::LimitExceeded) => {
-                                        this.quota_exceeded.store(true, Ordering::Release);
-                                        buf.set_filled(before);
-                                        return Poll::Ready(Err(quota_io_error()));
-                                    }
-                                    Err(crate::stats::QuotaReserveError::Contended) => {
-                                        saw_contention = true;
-                                    }
-                                }
-                            }
-                            if reserved_total.is_none() {
-                                reserve_rounds = reserve_rounds.saturating_add(1);
-                                if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
-                                    this.quota_exceeded.store(true, Ordering::Release);
-                                    buf.set_filled(before);
-                                    return Poll::Ready(Err(quota_io_error()));
-                                }
-                                if saw_contention {
-                                    std::thread::yield_now();
-                                }
-                            }
-                        }
-
-                        if should_immediate_quota_check(remaining, n_to_charge) {
-                            this.quota_bytes_since_check = 0;
-                        } else {
-                            this.quota_bytes_since_check =
-                                this.quota_bytes_since_check.saturating_add(n_to_charge);
-                            let interval = quota_adaptive_interval_bytes(remaining);
-                            if this.quota_bytes_since_check >= interval {
-                                this.quota_bytes_since_check = 0;
-                            }
-                        }
-
-                        if reserved_total.unwrap_or(0) >= limit {
-                            this.quota_exceeded.store(true, Ordering::Release);
-                        }
-                    }
-
-                    // C→S: client sent data
-                    this.counters
-                        .c2s_bytes
-                        .fetch_add(n_to_charge, Ordering::Relaxed);
-                    this.counters.c2s_ops.fetch_add(1, Ordering::Relaxed);
-                    this.counters.touch(Instant::now(), this.epoch);
-
-                    this.stats
-                        .add_user_octets_from_handle(this.user_stats.as_ref(), n_to_charge);
-                    this.stats
-                        .increment_user_msgs_from_handle(this.user_stats.as_ref());
-
-                    trace!(user = %this.user, bytes = n, "C->S");
-                }
-                Poll::Ready(Ok(()))
-            }
-            other => other,
-        }
-    }
-}
-
-impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
-    fn poll_write(
-        self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-        buf: &[u8],
-    ) -> Poll<io::Result<usize>> {
-        let this = self.get_mut();
-        if this.quota_exceeded.load(Ordering::Acquire) {
-            return Poll::Ready(Err(quota_io_error()));
-        }
-
-        let mut remaining_before = None;
-        let mut reserved_bytes = 0u64;
-        let mut write_buf = buf;
-        if let Some(limit) = this.quota_limit {
-            if !buf.is_empty() {
-                let mut reserve_rounds = 0usize;
-                while reserved_bytes == 0 {
-                    let used_before = this.user_stats.quota_used();
-                    let remaining = limit.saturating_sub(used_before);
-                    if remaining == 0 {
-                        this.quota_exceeded.store(true, Ordering::Release);
-                        return Poll::Ready(Err(quota_io_error()));
-                    }
-                    remaining_before = Some(remaining);
-
-                    let desired = remaining.min(buf.len() as u64);
-                    let mut saw_contention = false;
-                    for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
-                        match this.user_stats.quota_try_reserve(desired, limit) {
-                            Ok(_) => {
-                                reserved_bytes = desired;
-                                write_buf = &buf[..desired as usize];
-                                break;
-                            }
-                            Err(crate::stats::QuotaReserveError::LimitExceeded) => {
-                                break;
-                            }
-                            Err(crate::stats::QuotaReserveError::Contended) => {
-                                saw_contention = true;
-                            }
-                        }
-                    }
-
-                    if reserved_bytes == 0 {
-                        reserve_rounds = reserve_rounds.saturating_add(1);
-                        if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
-                            this.quota_exceeded.store(true, Ordering::Release);
-                            return Poll::Ready(Err(quota_io_error()));
-                        }
-                        if saw_contention {
-                            std::thread::yield_now();
-                        }
-                    }
-                }
-            } else {
-                let used_before = this.user_stats.quota_used();
-                let remaining = limit.saturating_sub(used_before);
-                if remaining == 0 {
-                    this.quota_exceeded.store(true, Ordering::Release);
-                    return Poll::Ready(Err(quota_io_error()));
-                }
-                remaining_before = Some(remaining);
-            }
-        }
-
-        match Pin::new(&mut this.inner).poll_write(cx, write_buf) {
-            Poll::Ready(Ok(n)) => {
-                if reserved_bytes > n as u64 {
-                    let refund = reserved_bytes - n as u64;
-                    let mut current = this.user_stats.quota_used.load(Ordering::Relaxed);
-                    loop {
-                        let next = current.saturating_sub(refund);
-                        match this.user_stats.quota_used.compare_exchange_weak(
-                            current,
-                            next,
-                            Ordering::Relaxed,
-                            Ordering::Relaxed,
-                        ) {
-                            Ok(_) => break,
-                            Err(observed) => current = observed,
-                        }
-                    }
-                }
-
-                if n > 0 {
-                    let n_to_charge = n as u64;
-
-                    // S→C: data written to client
-                    this.counters
-                        .s2c_bytes
-                        .fetch_add(n_to_charge, Ordering::Relaxed);
-                    this.counters.s2c_ops.fetch_add(1, Ordering::Relaxed);
-                    this.counters.touch(Instant::now(), this.epoch);
-
-                    this.stats
-                        .add_user_octets_to_handle(this.user_stats.as_ref(), n_to_charge);
-                    this.stats
-                        .increment_user_msgs_to_handle(this.user_stats.as_ref());
-
-                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
-                        if should_immediate_quota_check(remaining, n_to_charge) {
-                            this.quota_bytes_since_check = 0;
-                            if this.user_stats.quota_used() >= limit {
-                                this.quota_exceeded.store(true, Ordering::Release);
-                            }
-                        } else {
-                            this.quota_bytes_since_check =
-                                this.quota_bytes_since_check.saturating_add(n_to_charge);
-                            let interval = quota_adaptive_interval_bytes(remaining);
-                            if this.quota_bytes_since_check >= interval {
-                                this.quota_bytes_since_check = 0;
-                                if this.user_stats.quota_used() >= limit {
-                                    this.quota_exceeded.store(true, Ordering::Release);
-                                }
-                            }
-                        }
-                    }
-
-                    trace!(user = %this.user, bytes = n, "S->C");
-                }
-                Poll::Ready(Ok(n))
-            }
-            Poll::Ready(Err(err)) => {
-                if reserved_bytes > 0 {
-                    let mut current = this.user_stats.quota_used.load(Ordering::Relaxed);
-                    loop {
-                        let next = current.saturating_sub(reserved_bytes);
-                        match this.user_stats.quota_used.compare_exchange_weak(
-                            current,
-                            next,
-                            Ordering::Relaxed,
-                            Ordering::Relaxed,
-                        ) {
-                            Ok(_) => break,
-                            Err(observed) => current = observed,
-                        }
-                    }
-                }
-                Poll::Ready(Err(err))
-            }
-            Poll::Pending => {
-                if reserved_bytes > 0 {
-                    let mut current = this.user_stats.quota_used.load(Ordering::Relaxed);
-                    loop {
-                        let next = current.saturating_sub(reserved_bytes);
-                        match this.user_stats.quota_used.compare_exchange_weak(
-                            current,
-                            next,
-                            Ordering::Relaxed,
-                            Ordering::Relaxed,
-                        ) {
-                            Ok(_) => break,
-                            Err(observed) => current = observed,
-                        }
-                    }
-                }
-                Poll::Pending
-            }
-        }
-    }
-
-    #[inline]
-    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().inner).poll_flush(cx)
-    }
-
-    #[inline]
-    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
-        Pin::new(&mut self.get_mut().inner).poll_shutdown(cx)
-    }
-}
+mod io;

+use self::io::{CombinedStream, SharedCounters, StatsIo, is_quota_io_error};
+#[cfg(test)]
+use self::io::{quota_adaptive_interval_bytes, should_immediate_quota_check};
 // ============= Relay =============

 /// Relay data bidirectionally between client and server.
@@ -627,6 +154,43 @@ pub async fn relay_bidirectional_with_activity_timeout<CR, CW, SR, SW>(
    _buffer_pool: Arc<BufferPool>,
    activity_timeout: Duration,
 ) -> Result<()>
+where
+    CR: AsyncRead + Unpin + Send + 'static,
+    CW: AsyncWrite + Unpin + Send + 'static,
+    SR: AsyncRead + Unpin + Send + 'static,
+    SW: AsyncWrite + Unpin + Send + 'static,
+{
+    relay_bidirectional_with_activity_timeout_and_lease(
+        client_reader,
+        client_writer,
+        server_reader,
+        server_writer,
+        c2s_buf_size,
+        s2c_buf_size,
+        user,
+        stats,
+        quota_limit,
+        _buffer_pool,
+        None,
+        activity_timeout,
+    )
+    .await
+}
+
+pub async fn relay_bidirectional_with_activity_timeout_and_lease<CR, CW, SR, SW>(
+    client_reader: CR,
+    client_writer: CW,
+    server_reader: SR,
+    server_writer: SW,
+    c2s_buf_size: usize,
+    s2c_buf_size: usize,
+    user: &str,
+    stats: Arc<Stats>,
+    quota_limit: Option<u64>,
+    _buffer_pool: Arc<BufferPool>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    activity_timeout: Duration,
+) -> Result<()>
 where
    CR: AsyncRead + Unpin + Send + 'static,
    CW: AsyncWrite + Unpin + Send + 'static,
@@ -644,11 +208,12 @@ where
    let mut server = CombinedStream::new(server_reader, server_writer);

    // Wrap client with stats/activity tracking
-    let mut client = StatsIo::new(
+    let mut client = StatsIo::new_with_traffic_lease(
        client_combined,
        Arc::clone(&counters),
        Arc::clone(&stats),
        user_owned.clone(),
+        traffic_lease,
        quota_limit,
        Arc::clone(&quota_exceeded),
        epoch,
@@ -0,0 +1,551 @@
+use crate::proxy::traffic_limiter::{RateDirection, TrafficLease, next_refill_delay};
+use crate::stats::{Stats, UserStats};
+use std::io;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::task::{Context, Poll};
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+use tokio::time::{Instant, Sleep};
+use tracing::trace;
+
+mod combined;
+mod counters;
+mod quota;
+
+pub(super) use self::combined::CombinedStream;
+pub(super) use self::counters::SharedCounters;
+pub(super) use self::quota::is_quota_io_error;
+use self::quota::{
+    QUOTA_RESERVE_MAX_ROUNDS, QUOTA_RESERVE_SPIN_RETRIES, quota_io_error,
+    refund_reserved_quota_bytes,
+};
+pub(super) use self::quota::{quota_adaptive_interval_bytes, should_immediate_quota_check};
+
+/// Transparent I/O wrapper that tracks per-user statistics and activity.
+///
+/// Wraps the **client** side of the relay. Direction mapping:
+///
+/// | poll method  | direction | stats updated                        |
+/// |-------------|-----------|--------------------------------------|
+/// | `poll_read`  | C→S       | `octets_from`, `msgs_from`, counters |
+/// | `poll_write` | S→C       | `octets_to`, `msgs_to`, counters     |
+///
+/// Both update the shared activity timestamp for the watchdog.
+///
+/// Note on message counts: the original code counted one `read()`/`write_all()`
+/// as one "message". Here we count `poll_read`/`poll_write` completions instead.
+/// Byte counts are identical; op counts may differ slightly due to different
+/// internal buffering in `copy_bidirectional`. This is fine for monitoring.
+pub(super) struct StatsIo<S> {
+    inner: S,
+    counters: Arc<SharedCounters>,
+    stats: Arc<Stats>,
+    user: String,
+    user_stats: Arc<UserStats>,
+    traffic_lease: Option<Arc<TrafficLease>>,
+    c2s_rate_debt_bytes: u64,
+    c2s_wait: RateWaitState,
+    s2c_wait: RateWaitState,
+    quota_wait: RateWaitState,
+    quota_limit: Option<u64>,
+    quota_exceeded: Arc<AtomicBool>,
+    pub(super) quota_bytes_since_check: u64,
+    epoch: Instant,
+}
+
+#[derive(Default)]
+struct RateWaitState {
+    sleep: Option<Pin<Box<Sleep>>>,
+    started_at: Option<Instant>,
+    blocked_user: bool,
+    blocked_cidr: bool,
+}
+
+impl<S> StatsIo<S> {
+    /// Creates a StatsIo wrapper without a traffic lease for relay unit tests.
+    #[cfg(test)]
+    pub(super) fn new(
+        inner: S,
+        counters: Arc<SharedCounters>,
+        stats: Arc<Stats>,
+        user: String,
+        quota_limit: Option<u64>,
+        quota_exceeded: Arc<AtomicBool>,
+        epoch: Instant,
+    ) -> Self {
+        Self::new_with_traffic_lease(
+            inner,
+            counters,
+            stats,
+            user,
+            None,
+            quota_limit,
+            quota_exceeded,
+            epoch,
+        )
+    }
+
+    pub(super) fn new_with_traffic_lease(
+        inner: S,
+        counters: Arc<SharedCounters>,
+        stats: Arc<Stats>,
+        user: String,
+        traffic_lease: Option<Arc<TrafficLease>>,
+        quota_limit: Option<u64>,
+        quota_exceeded: Arc<AtomicBool>,
+        epoch: Instant,
+    ) -> Self {
+        // Mark initial activity so the watchdog doesn't fire before data flows
+        counters.touch(Instant::now(), epoch);
+        let user_stats = stats.get_or_create_user_stats_handle(&user);
+        Self {
+            inner,
+            counters,
+            stats,
+            user,
+            user_stats,
+            traffic_lease,
+            c2s_rate_debt_bytes: 0,
+            c2s_wait: RateWaitState::default(),
+            s2c_wait: RateWaitState::default(),
+            quota_wait: RateWaitState::default(),
+            quota_limit,
+            quota_exceeded,
+            quota_bytes_since_check: 0,
+            epoch,
+        }
+    }
+
+    fn record_wait(
+        wait: &mut RateWaitState,
+        lease: Option<&Arc<TrafficLease>>,
+        direction: RateDirection,
+    ) {
+        let Some(started_at) = wait.started_at.take() else {
+            return;
+        };
+        let wait_ms = started_at.elapsed().as_millis().min(u128::from(u64::MAX)) as u64;
+        if let Some(lease) = lease {
+            lease.observe_wait_ms(direction, wait.blocked_user, wait.blocked_cidr, wait_ms);
+        }
+        wait.blocked_user = false;
+        wait.blocked_cidr = false;
+    }
+
+    fn arm_wait(wait: &mut RateWaitState, blocked_user: bool, blocked_cidr: bool) {
+        if wait.sleep.is_none() {
+            wait.sleep = Some(Box::pin(tokio::time::sleep(next_refill_delay())));
+            wait.started_at = Some(Instant::now());
+        }
+        wait.blocked_user |= blocked_user;
+        wait.blocked_cidr |= blocked_cidr;
+    }
+
+    fn poll_wait(
+        wait: &mut RateWaitState,
+        cx: &mut Context<'_>,
+        lease: Option<&Arc<TrafficLease>>,
+        direction: RateDirection,
+    ) -> Poll<()> {
+        let Some(sleep) = wait.sleep.as_mut() else {
+            return Poll::Ready(());
+        };
+        if sleep.as_mut().poll(cx).is_pending() {
+            return Poll::Pending;
+        }
+        wait.sleep = None;
+        Self::record_wait(wait, lease, direction);
+        Poll::Ready(())
+    }
+
+    fn settle_c2s_rate_debt(&mut self, cx: &mut Context<'_>) -> Poll<()> {
+        let Some(lease) = self.traffic_lease.as_ref() else {
+            self.c2s_rate_debt_bytes = 0;
+            return Poll::Ready(());
+        };
+
+        while self.c2s_rate_debt_bytes > 0 {
+            let consume = lease.try_consume(RateDirection::Up, self.c2s_rate_debt_bytes);
+            if consume.granted > 0 {
+                self.c2s_rate_debt_bytes = self.c2s_rate_debt_bytes.saturating_sub(consume.granted);
+                continue;
+            }
+            Self::arm_wait(
+                &mut self.c2s_wait,
+                consume.blocked_user,
+                consume.blocked_cidr,
+            );
+            if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending()
+            {
+                return Poll::Pending;
+            }
+        }
+
+        if Self::poll_wait(&mut self.c2s_wait, cx, Some(lease), RateDirection::Up).is_pending() {
+            return Poll::Pending;
+        }
+
+        Poll::Ready(())
+    }
+
+    fn arm_quota_wait(&mut self, cx: &mut Context<'_>) -> Poll<()> {
+        Self::arm_wait(&mut self.quota_wait, false, false);
+        Self::poll_wait(&mut self.quota_wait, cx, None, RateDirection::Up)
+    }
+}
+
+impl<S: AsyncRead + Unpin> AsyncRead for StatsIo<S> {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        let this = self.get_mut();
+        if this.quota_exceeded.load(Ordering::Acquire) {
+            return Poll::Ready(Err(quota_io_error()));
+        }
+        if this.settle_c2s_rate_debt(cx).is_pending() {
+            return Poll::Pending;
+        }
+        if buf.remaining() == 0 {
+            return Pin::new(&mut this.inner).poll_read(cx, buf);
+        }
+
+        let mut remaining_before = None;
+        let mut reserved_read_bytes = 0u64;
+        let mut read_limit = buf.remaining();
+        if let Some(limit) = this.quota_limit {
+            let used_before = this.user_stats.quota_used();
+            let remaining = limit.saturating_sub(used_before);
+            if remaining == 0 {
+                this.quota_exceeded.store(true, Ordering::Release);
+                return Poll::Ready(Err(quota_io_error()));
+            }
+            remaining_before = Some(remaining);
+            read_limit = read_limit.min(remaining as usize);
+            if read_limit == 0 {
+                this.quota_exceeded.store(true, Ordering::Release);
+                return Poll::Ready(Err(quota_io_error()));
+            }
+
+            let desired = read_limit as u64;
+            let mut reserve_rounds = 0usize;
+            while reserved_read_bytes == 0 {
+                for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+                    match this.user_stats.quota_try_reserve(desired, limit) {
+                        Ok(_) => {
+                            reserved_read_bytes = desired;
+                            break;
+                        }
+                        Err(crate::stats::QuotaReserveError::LimitExceeded) => {
+                            this.quota_exceeded.store(true, Ordering::Release);
+                            return Poll::Ready(Err(quota_io_error()));
+                        }
+                        Err(crate::stats::QuotaReserveError::Contended) => {
+                            this.stats.increment_quota_contention_total();
+                        }
+                    }
+                }
+
+                if reserved_read_bytes == 0 {
+                    reserve_rounds = reserve_rounds.saturating_add(1);
+                    if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
+                        this.stats.increment_quota_contention_timeout_total();
+                        if this.arm_quota_wait(cx).is_pending() {
+                            return Poll::Pending;
+                        }
+                        reserve_rounds = 0;
+                    }
+                }
+            }
+        }
+
+        let limited_read = read_limit < buf.remaining();
+        let read_result = if limited_read {
+            let mut limited_buf = ReadBuf::new(buf.initialize_unfilled_to(read_limit));
+            match Pin::new(&mut this.inner).poll_read(cx, &mut limited_buf) {
+                Poll::Ready(Ok(())) => {
+                    let n = limited_buf.filled().len();
+                    buf.advance(n);
+                    Poll::Ready(Ok(n))
+                }
+                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
+                Poll::Pending => Poll::Pending,
+            }
+        } else {
+            let before = buf.filled().len();
+            match Pin::new(&mut this.inner).poll_read(cx, buf) {
+                Poll::Ready(Ok(())) => {
+                    let n = buf.filled().len() - before;
+                    Poll::Ready(Ok(n))
+                }
+                Poll::Ready(Err(err)) => Poll::Ready(Err(err)),
+                Poll::Pending => Poll::Pending,
+            }
+        };
+
+        match read_result {
+            Poll::Ready(Ok(n)) => {
+                if reserved_read_bytes > n as u64 {
+                    let refund_bytes = reserved_read_bytes - n as u64;
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
+                    this.stats.add_quota_refund_bytes_total(refund_bytes);
+                }
+                if n > 0 {
+                    let n_to_charge = n as u64;
+
+                    if let Some(remaining) = remaining_before {
+                        if should_immediate_quota_check(remaining, n_to_charge) {
+                            this.quota_bytes_since_check = 0;
+                        } else {
+                            this.quota_bytes_since_check =
+                                this.quota_bytes_since_check.saturating_add(n_to_charge);
+                            let interval = quota_adaptive_interval_bytes(remaining);
+                            if this.quota_bytes_since_check >= interval {
+                                this.quota_bytes_since_check = 0;
+                            }
+                        }
+                    }
+                    if let Some(limit) = this.quota_limit
+                        && this.user_stats.quota_used() >= limit
+                    {
+                        this.quota_exceeded.store(true, Ordering::Release);
+                    }
+
+                    // C→S: client sent data
+                    this.counters
+                        .c2s_bytes
+                        .fetch_add(n_to_charge, Ordering::Relaxed);
+                    this.counters.c2s_ops.fetch_add(1, Ordering::Relaxed);
+                    this.counters.touch(Instant::now(), this.epoch);
+
+                    this.stats
+                        .add_user_traffic_from_handle(this.user_stats.as_ref(), n_to_charge);
+                    if this.traffic_lease.is_some() {
+                        this.c2s_rate_debt_bytes =
+                            this.c2s_rate_debt_bytes.saturating_add(n_to_charge);
+                        let _ = this.settle_c2s_rate_debt(cx);
+                    }
+
+                    trace!(user = %this.user, bytes = n, "C->S");
+                }
+                Poll::Ready(Ok(()))
+            }
+            Poll::Pending => {
+                if reserved_read_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
+                }
+                Poll::Pending
+            }
+            Poll::Ready(Err(err)) => {
+                if reserved_read_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_read_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_read_bytes);
+                }
+                Poll::Ready(Err(err))
+            }
+        }
+    }
+}
+
+impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<io::Result<usize>> {
+        let this = self.get_mut();
+        if this.quota_exceeded.load(Ordering::Acquire) {
+            return Poll::Ready(Err(quota_io_error()));
+        }
+
+        let mut shaper_reserved_bytes = 0u64;
+        let mut write_buf = buf;
+        if let Some(lease) = this.traffic_lease.as_ref() {
+            if !buf.is_empty() {
+                loop {
+                    let consume = lease.try_consume(RateDirection::Down, buf.len() as u64);
+                    if consume.granted > 0 {
+                        shaper_reserved_bytes = consume.granted;
+                        if consume.granted < buf.len() as u64 {
+                            write_buf = &buf[..consume.granted as usize];
+                        }
+                        let _ = Self::poll_wait(
+                            &mut this.s2c_wait,
+                            cx,
+                            Some(lease),
+                            RateDirection::Down,
+                        );
+                        break;
+                    }
+
+                    Self::arm_wait(
+                        &mut this.s2c_wait,
+                        consume.blocked_user,
+                        consume.blocked_cidr,
+                    );
+                    if Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down)
+                        .is_pending()
+                    {
+                        return Poll::Pending;
+                    }
+                }
+            } else {
+                let _ = Self::poll_wait(&mut this.s2c_wait, cx, Some(lease), RateDirection::Down);
+            }
+        }
+
+        let mut remaining_before = None;
+        let mut reserved_bytes = 0u64;
+        if let Some(limit) = this.quota_limit {
+            if !write_buf.is_empty() {
+                let mut reserve_rounds = 0usize;
+                while reserved_bytes == 0 {
+                    let used_before = this.user_stats.quota_used();
+                    let remaining = limit.saturating_sub(used_before);
+                    if remaining == 0 {
+                        if let Some(lease) = this.traffic_lease.as_ref() {
+                            lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                        }
+                        this.quota_exceeded.store(true, Ordering::Release);
+                        return Poll::Ready(Err(quota_io_error()));
+                    }
+                    remaining_before = Some(remaining);
+
+                    let desired = remaining.min(write_buf.len() as u64);
+                    let mut saw_contention = false;
+                    for _ in 0..QUOTA_RESERVE_SPIN_RETRIES {
+                        match this.user_stats.quota_try_reserve(desired, limit) {
+                            Ok(_) => {
+                                reserved_bytes = desired;
+                                write_buf = &write_buf[..desired as usize];
+                                break;
+                            }
+                            Err(crate::stats::QuotaReserveError::LimitExceeded) => {
+                                break;
+                            }
+                            Err(crate::stats::QuotaReserveError::Contended) => {
+                                this.stats.increment_quota_contention_total();
+                                saw_contention = true;
+                            }
+                        }
+                    }
+
+                    if reserved_bytes == 0 {
+                        reserve_rounds = reserve_rounds.saturating_add(1);
+                        if reserve_rounds >= QUOTA_RESERVE_MAX_ROUNDS {
+                            this.stats.increment_quota_contention_timeout_total();
+                            if let Some(lease) = this.traffic_lease.as_ref() {
+                                lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                            }
+                            let _ = this.arm_quota_wait(cx);
+                            return Poll::Pending;
+                        } else if saw_contention {
+                            std::hint::spin_loop();
+                        }
+                    }
+                }
+            } else {
+                let used_before = this.user_stats.quota_used();
+                let remaining = limit.saturating_sub(used_before);
+                if remaining == 0 {
+                    if let Some(lease) = this.traffic_lease.as_ref() {
+                        lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                    }
+                    this.quota_exceeded.store(true, Ordering::Release);
+                    return Poll::Ready(Err(quota_io_error()));
+                }
+                remaining_before = Some(remaining);
+            }
+        }
+
+        match Pin::new(&mut this.inner).poll_write(cx, write_buf) {
+            Poll::Ready(Ok(n)) => {
+                if reserved_bytes > n as u64 {
+                    let refund_bytes = reserved_bytes - n as u64;
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), refund_bytes);
+                    this.stats.add_quota_refund_bytes_total(refund_bytes);
+                }
+                if shaper_reserved_bytes > n as u64
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes - n as u64);
+                }
+                if n > 0 {
+                    if let Some(lease) = this.traffic_lease.as_ref() {
+                        Self::record_wait(&mut this.s2c_wait, Some(lease), RateDirection::Down);
+                    }
+                    let n_to_charge = n as u64;
+
+                    // S→C: data written to client
+                    this.counters
+                        .s2c_bytes
+                        .fetch_add(n_to_charge, Ordering::Relaxed);
+                    this.counters.s2c_ops.fetch_add(1, Ordering::Relaxed);
+                    this.counters.touch(Instant::now(), this.epoch);
+
+                    this.stats
+                        .add_user_traffic_to_handle(this.user_stats.as_ref(), n_to_charge);
+
+                    if let (Some(limit), Some(remaining)) = (this.quota_limit, remaining_before) {
+                        if should_immediate_quota_check(remaining, n_to_charge) {
+                            this.quota_bytes_since_check = 0;
+                            if this.user_stats.quota_used() >= limit {
+                                this.quota_exceeded.store(true, Ordering::Release);
+                            }
+                        } else {
+                            this.quota_bytes_since_check =
+                                this.quota_bytes_since_check.saturating_add(n_to_charge);
+                            let interval = quota_adaptive_interval_bytes(remaining);
+                            if this.quota_bytes_since_check >= interval {
+                                this.quota_bytes_since_check = 0;
+                                if this.user_stats.quota_used() >= limit {
+                                    this.quota_exceeded.store(true, Ordering::Release);
+                                }
+                            }
+                        }
+                    }
+
+                    trace!(user = %this.user, bytes = n, "S->C");
+                }
+                Poll::Ready(Ok(n))
+            }
+            Poll::Ready(Err(err)) => {
+                if reserved_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
+                }
+                if shaper_reserved_bytes > 0
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                }
+                Poll::Ready(Err(err))
+            }
+            Poll::Pending => {
+                if reserved_bytes > 0 {
+                    refund_reserved_quota_bytes(this.user_stats.as_ref(), reserved_bytes);
+                    this.stats.add_quota_refund_bytes_total(reserved_bytes);
+                }
+                if shaper_reserved_bytes > 0
+                    && let Some(lease) = this.traffic_lease.as_ref()
+                {
+                    lease.refund(RateDirection::Down, shaper_reserved_bytes);
+                }
+                Poll::Pending
+            }
+        }
+    }
+
+    #[inline]
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_flush(cx)
+    }
+
+    #[inline]
+    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().inner).poll_shutdown(cx)
+    }
+}
@@ -0,0 +1,61 @@
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+
+// ============= CombinedStream =============
+
+/// Combines separate read and write halves into a single bidirectional stream.
+///
+/// `copy_bidirectional` requires `AsyncRead + AsyncWrite` on each side,
+/// but the handshake layer produces split reader/writer pairs
+/// (e.g. `CryptoReader<FakeTlsReader<OwnedReadHalf>>` + `CryptoWriter<...>`).
+///
+/// This wrapper reunifies them with zero overhead — each trait method
+/// delegates directly to the corresponding half. No buffering, no copies.
+///
+/// Safety: `poll_read` only touches `reader`, `poll_write` only touches `writer`,
+/// so there's no aliasing even though both are called on the same `&mut self`.
+pub(in crate::proxy::relay) struct CombinedStream<R, W> {
+    reader: R,
+    writer: W,
+}
+
+impl<R, W> CombinedStream<R, W> {
+    pub(in crate::proxy::relay) fn new(reader: R, writer: W) -> Self {
+        Self { reader, writer }
+    }
+}
+
+impl<R: AsyncRead + Unpin, W: Unpin> AsyncRead for CombinedStream<R, W> {
+    #[inline]
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().reader).poll_read(cx, buf)
+    }
+}
+
+impl<R: Unpin, W: AsyncWrite + Unpin> AsyncWrite for CombinedStream<R, W> {
+    #[inline]
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<io::Result<usize>> {
+        Pin::new(&mut self.get_mut().writer).poll_write(cx, buf)
+    }
+
+    #[inline]
+    fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().writer).poll_flush(cx)
+    }
+
+    #[inline]
+    fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<io::Result<()>> {
+        Pin::new(&mut self.get_mut().writer).poll_shutdown(cx)
+    }
+}
@@ -0,0 +1,51 @@
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::Duration;
+
+use tokio::time::Instant;
+
+// ============= SharedCounters =============
+
+/// Atomic counters shared between the relay (via StatsIo) and the watchdog task.
+///
+/// Using `Relaxed` ordering is sufficient because:
+/// - Counters are monotonically increasing (no ABA problem)
+/// - Slight staleness in watchdog reads is harmless (±10s check interval anyway)
+/// - No ordering dependencies between different counters
+pub(in crate::proxy::relay) struct SharedCounters {
+    /// Bytes read from client (C→S direction)
+    pub(in crate::proxy::relay) c2s_bytes: AtomicU64,
+    /// Bytes written to client (S→C direction)
+    pub(in crate::proxy::relay) s2c_bytes: AtomicU64,
+    /// Number of poll_read completions (≈ C→S chunks)
+    pub(in crate::proxy::relay) c2s_ops: AtomicU64,
+    /// Number of poll_write completions (≈ S→C chunks)
+    pub(in crate::proxy::relay) s2c_ops: AtomicU64,
+    /// Milliseconds since relay epoch of last I/O activity
+    last_activity_ms: AtomicU64,
+}
+
+impl SharedCounters {
+    pub(in crate::proxy::relay) fn new() -> Self {
+        Self {
+            c2s_bytes: AtomicU64::new(0),
+            s2c_bytes: AtomicU64::new(0),
+            c2s_ops: AtomicU64::new(0),
+            s2c_ops: AtomicU64::new(0),
+            last_activity_ms: AtomicU64::new(0),
+        }
+    }
+
+    /// Record activity at this instant.
+    #[inline]
+    pub(in crate::proxy::relay) fn touch(&self, now: Instant, epoch: Instant) {
+        let ms = now.duration_since(epoch).as_millis() as u64;
+        self.last_activity_ms.store(ms, Ordering::Relaxed);
+    }
+
+    /// How long since last recorded activity.
+    pub(in crate::proxy::relay) fn idle_duration(&self, now: Instant, epoch: Instant) -> Duration {
+        let last_ms = self.last_activity_ms.load(Ordering::Relaxed);
+        let now_ms = now.duration_since(epoch).as_millis() as u64;
+        Duration::from_millis(now_ms.saturating_sub(last_ms))
+    }
+}
@@ -0,0 +1,68 @@
+use crate::stats::UserStats;
+use std::io;
+use std::sync::atomic::Ordering;
+
+#[derive(Debug)]
+struct QuotaIoSentinel;
+
+impl std::fmt::Display for QuotaIoSentinel {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("user data quota exceeded")
+    }
+}
+
+impl std::error::Error for QuotaIoSentinel {}
+
+pub(super) fn quota_io_error() -> io::Error {
+    io::Error::new(io::ErrorKind::PermissionDenied, QuotaIoSentinel)
+}
+
+pub(in crate::proxy::relay) fn is_quota_io_error(err: &io::Error) -> bool {
+    err.kind() == io::ErrorKind::PermissionDenied
+        && err
+            .get_ref()
+            .and_then(|source| source.downcast_ref::<QuotaIoSentinel>())
+            .is_some()
+}
+
+const QUOTA_NEAR_LIMIT_BYTES: u64 = 64 * 1024;
+const QUOTA_LARGE_CHARGE_BYTES: u64 = 16 * 1024;
+const QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES: u64 = 4 * 1024;
+const QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES: u64 = 64 * 1024;
+pub(super) const QUOTA_RESERVE_SPIN_RETRIES: usize = 64;
+pub(super) const QUOTA_RESERVE_MAX_ROUNDS: usize = 8;
+
+#[inline]
+pub(in crate::proxy::relay) fn quota_adaptive_interval_bytes(remaining_before: u64) -> u64 {
+    remaining_before.saturating_div(2).clamp(
+        QUOTA_ADAPTIVE_INTERVAL_MIN_BYTES,
+        QUOTA_ADAPTIVE_INTERVAL_MAX_BYTES,
+    )
+}
+
+#[inline]
+pub(in crate::proxy::relay) fn should_immediate_quota_check(
+    remaining_before: u64,
+    charge_bytes: u64,
+) -> bool {
+    remaining_before <= QUOTA_NEAR_LIMIT_BYTES || charge_bytes >= QUOTA_LARGE_CHARGE_BYTES
+}
+
+pub(super) fn refund_reserved_quota_bytes(user_stats: &UserStats, reserved_bytes: u64) {
+    if reserved_bytes == 0 {
+        return;
+    }
+    let mut current = user_stats.quota_used.load(Ordering::Relaxed);
+    loop {
+        let next = current.saturating_sub(reserved_bytes);
+        match user_stats.quota_used.compare_exchange_weak(
+            current,
+            next,
+            Ordering::Relaxed,
+            Ordering::Relaxed,
+        ) {
+            Ok(_) => return,
+            Err(observed) => current = observed,
+        }
+    }
+}
@@ -4,8 +4,6 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};

 use tokio::sync::watch;

-pub(crate) const ROUTE_SWITCH_ERROR_MSG: &str = "Session terminated";
-
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(u8)]
 pub(crate) enum RelayRouteMode {
@@ -10,6 +10,7 @@ use tokio::sync::mpsc;

 use crate::proxy::handshake::{AuthProbeSaturationState, AuthProbeState};
 use crate::proxy::middle_relay::{DesyncDedupRotationState, RelayIdleCandidateRegistry};
+use crate::proxy::traffic_limiter::TrafficLimiter;

 const HANDSHAKE_RECENT_USER_RING_LEN: usize = 64;

@@ -65,6 +66,7 @@ pub(crate) struct MiddleRelaySharedState {
 pub(crate) struct ProxySharedState {
    pub(crate) handshake: HandshakeSharedState,
    pub(crate) middle_relay: MiddleRelaySharedState,
+    pub(crate) traffic_limiter: Arc<TrafficLimiter>,
    pub(crate) conntrack_pressure_active: AtomicBool,
    pub(crate) conntrack_close_tx: Mutex<Option<mpsc::Sender<ConntrackCloseEvent>>>,
 }
@@ -98,6 +100,7 @@ impl ProxySharedState {
                relay_idle_registry: Mutex::new(RelayIdleCandidateRegistry::default()),
                relay_idle_mark_seq: AtomicU64::new(0),
            },
+            traffic_limiter: TrafficLimiter::new(),
            conntrack_pressure_active: AtomicBool::new(false),
            conntrack_close_tx: Mutex::new(None),
        })
@@ -31,11 +31,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -27,11 +27,14 @@ fn build_harness(config: ProxyConfig) -> PipelineHarness {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -25,11 +25,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -38,11 +38,14 @@ fn build_harness(secret_hex: &str, mask_port: u16) -> PipelineHarness {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -16,11 +16,14 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -39,11 +39,14 @@ fn build_harness(secret_hex: &str, mask_port: u16) -> RedTeamHarness {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -229,11 +232,14 @@ async fn redteam_03_masking_duration_must_be_less_than_1ms_when_backend_down() {
                upstream_type: UpstreamType::Direct {
                    interface: None,
                    bind_addresses: None,
+                    bindtodevice: None,
                },
                weight: 1,
                enabled: true,
                scopes: String::new(),
                selected_scope: String::new(),
+                ipv4: None,
+                ipv6: None,
            }],
            1,
            1,
@@ -470,11 +476,14 @@ async fn measure_invalid_probe_duration_ms(delay_ms: u64, tls_len: u16, body_sen
                upstream_type: UpstreamType::Direct {
                    interface: None,
                    bind_addresses: None,
+                    bindtodevice: None,
                },
                weight: 1,
                enabled: true,
                scopes: String::new(),
                selected_scope: String::new(),
+                ipv4: None,
+                ipv6: None,
            }],
            1,
            1,
@@ -544,11 +553,14 @@ async fn capture_forwarded_probe_len(tls_len: u16, body_sent: usize) -> usize {
                upstream_type: UpstreamType::Direct {
                    interface: None,
                    bind_addresses: None,
+                    bindtodevice: None,
                },
                weight: 1,
                enabled: true,
                scopes: String::new(),
                selected_scope: String::new(),
+                ipv4: None,
+                ipv6: None,
            }],
            1,
            1,
@@ -13,11 +13,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -11,11 +11,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -25,11 +25,14 @@ fn new_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -282,7 +282,7 @@ async fn user_connection_reservation_drop_enqueues_cleanup_synchronously() {
    assert_eq!(stats.get_user_curr_connects(&user), 1);

    let reservation =
-        UserConnectionReservation::new(stats.clone(), ip_tracker.clone(), user.clone(), ip);
+        UserConnectionReservation::new(stats.clone(), ip_tracker.clone(), user.clone(), ip, true);

    // Drop the reservation synchronously without any tokio::spawn/await yielding!
    drop(reservation);
@@ -320,6 +320,7 @@ async fn relay_task_abort_releases_user_gate_and_ip_reservation() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 8).await;

    let mut cfg = ProxyConfig::default();
    cfg.access.user_max_tcp_conns.insert(user.to_string(), 8);
@@ -332,11 +333,14 @@ async fn relay_task_abort_releases_user_gate_and_ip_reservation() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -434,6 +438,7 @@ async fn relay_cutover_releases_user_gate_and_ip_reservation() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 8).await;

    let mut cfg = ProxyConfig::default();
    cfg.access.user_max_tcp_conns.insert(user.to_string(), 8);
@@ -446,11 +451,14 @@ async fn relay_cutover_releases_user_gate_and_ip_reservation() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -570,11 +578,14 @@ async fn integration_route_cutover_and_quota_overlap_fails_closed_and_releases_s
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -650,7 +661,7 @@ async fn integration_route_cutover_and_quota_overlap_fails_closed_and_releases_s

    assert!(
        matches!(relay_result, Err(ProxyError::DataQuotaExceeded { .. }))
-            || matches!(relay_result, Err(ProxyError::Proxy(ref msg)) if msg == crate::proxy::route_mode::ROUTE_SWITCH_ERROR_MSG),
+            || matches!(relay_result, Err(ProxyError::RouteSwitched)),
        "overlap race must fail closed via quota enforcement or generic cutover termination"
    );

@@ -740,11 +751,14 @@ async fn proxy_protocol_header_is_rejected_when_trust_list_is_empty() {
            upstream_type: crate::config::UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -817,11 +831,14 @@ async fn proxy_protocol_header_from_untrusted_peer_range_is_rejected_under_load(
                upstream_type: crate::config::UpstreamType::Direct {
                    interface: None,
                    bind_addresses: None,
+                    bindtodevice: None,
                },
                weight: 1,
                enabled: true,
                scopes: String::new(),
                selected_scope: String::new(),
+                ipv4: None,
+                ipv6: None,
            }],
            1,
            1,
@@ -943,6 +960,36 @@ async fn reservation_limit_failure_does_not_leak_curr_connects_counter() {
    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
 }

+#[tokio::test]
+async fn unlimited_unique_ip_user_is_still_visible_in_active_ip_tracker() {
+    let user = "active-ip-observed-user";
+    let config = crate::config::ProxyConfig::default();
+    let stats = Arc::new(crate::stats::Stats::new());
+    let ip_tracker = Arc::new(crate::ip_tracker::UserIpTracker::new());
+    let peer = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(198, 51, 200, 17)), 50017);
+
+    let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
+        user,
+        &config,
+        stats.clone(),
+        peer,
+        ip_tracker.clone(),
+    )
+    .await
+    .expect("reservation without unique-IP limit must succeed");
+
+    assert_eq!(stats.get_user_curr_connects(user), 1);
+    assert_eq!(
+        ip_tracker.get_active_ip_count(user).await,
+        1,
+        "active IP observability must not depend on unique-IP limit enforcement"
+    );
+
+    reservation.release().await;
+    assert_eq!(stats.get_user_curr_connects(user), 0);
+    assert_eq!(ip_tracker.get_active_ip_count(user).await, 0);
+}
+
 #[tokio::test]
 async fn short_tls_probe_is_masked_through_client_pipeline() {
    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
@@ -977,11 +1024,14 @@ async fn short_tls_probe_is_masked_through_client_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1065,11 +1115,14 @@ async fn tls12_record_probe_is_masked_through_client_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1151,11 +1204,14 @@ async fn handle_client_stream_increments_connects_all_exactly_once() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1244,11 +1300,14 @@ async fn running_client_handler_increments_connects_all_exactly_once() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1334,11 +1393,14 @@ async fn idle_pooled_connection_closes_cleanly_in_generic_stream_path() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1405,11 +1467,14 @@ async fn idle_pooled_connection_closes_cleanly_in_client_handler_path() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1491,11 +1556,14 @@ async fn partial_tls_header_stall_triggers_handshake_timeout() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1816,11 +1884,14 @@ async fn valid_tls_path_does_not_fall_back_to_mask_backend() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -1925,11 +1996,14 @@ async fn valid_tls_with_invalid_mtproto_falls_back_to_mask_backend() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -2032,11 +2106,14 @@ async fn client_handler_tls_bad_mtproto_is_forwarded_to_mask_backend() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -2154,11 +2231,14 @@ async fn alpn_mismatch_tls_probe_is_masked_through_client_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -2247,11 +2327,14 @@ async fn invalid_hmac_tls_probe_is_masked_through_client_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -2346,11 +2429,14 @@ async fn burst_invalid_tls_probes_are_masked_verbatim() {
                upstream_type: UpstreamType::Direct {
                    interface: None,
                    bind_addresses: None,
+                    bindtodevice: None,
                },
                weight: 1,
                enabled: true,
                scopes: String::new(),
                selected_scope: String::new(),
+                ipv4: None,
+                ipv6: None,
            }],
            1,
            1,
@@ -2439,6 +2525,46 @@ fn unexpected_eof_is_classified_without_string_matching() {
    );
 }

+#[test]
+fn connection_reset_is_classified_as_expected_handshake_close() {
+    let beobachten = BeobachtenStore::new();
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = 1;
+
+    let reset = ProxyError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionReset));
+    let peer_ip: IpAddr = "198.51.100.202".parse().unwrap();
+
+    record_handshake_failure_class(&beobachten, &config, peer_ip, &reset);
+
+    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
+    assert!(
+        snapshot.contains("[expected_64_got_0]"),
+        "ConnectionReset must be classified as expected handshake close"
+    );
+}
+
+#[test]
+fn stream_io_unexpected_eof_is_classified_without_string_matching() {
+    let beobachten = BeobachtenStore::new();
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = 1;
+
+    let eof = ProxyError::Stream(StreamError::Io(std::io::Error::from(
+        std::io::ErrorKind::UnexpectedEof,
+    )));
+    let peer_ip: IpAddr = "198.51.100.203".parse().unwrap();
+
+    record_handshake_failure_class(&beobachten, &config, peer_ip, &eof);
+
+    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
+    assert!(
+        snapshot.contains("[expected_64_got_0]"),
+        "StreamError::Io(UnexpectedEof) must be classified as expected handshake close"
+    );
+}
+
 #[test]
 fn non_eof_error_is_classified_as_other() {
    let beobachten = BeobachtenStore::new();
@@ -2785,6 +2911,7 @@ async fn explicit_reservation_release_cleans_user_and_ip_immediately() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 4).await;

    let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
        user,
@@ -2823,6 +2950,7 @@ async fn explicit_reservation_release_does_not_double_decrement_on_drop() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 4).await;

    let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
        user,
@@ -2853,6 +2981,7 @@ async fn drop_fallback_eventually_cleans_user_and_ip_reservation() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;

    let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
        user,
@@ -2935,6 +3064,7 @@ async fn release_abort_storm_does_not_leak_user_or_ip_reservations() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, ATTEMPTS + 16).await;

    for idx in 0..ATTEMPTS {
        let peer = SocketAddr::new(
@@ -2985,6 +3115,7 @@ async fn release_abort_loop_preserves_immediate_same_ip_reacquire() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;

    for _ in 0..ITERATIONS {
        let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
@@ -3043,6 +3174,7 @@ async fn adversarial_mixed_release_drop_abort_wave_converges_to_zero() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, RESERVATIONS + 8).await;

    let mut reservations = Vec::with_capacity(RESERVATIONS);
    for idx in 0..RESERVATIONS {
@@ -3123,6 +3255,8 @@ async fn parallel_users_abort_release_isolation_preserves_independent_cleanup()

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user_a, 64).await;
+    ip_tracker.set_user_limit(user_b, 64).await;

    let mut tasks = tokio::task::JoinSet::new();
    for idx in 0..64usize {
@@ -3184,6 +3318,7 @@ async fn concurrent_release_storm_leaves_zero_user_and_ip_footprint() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, RESERVATIONS + 8).await;

    let mut reservations = Vec::with_capacity(RESERVATIONS);
    for idx in 0..RESERVATIONS {
@@ -3238,6 +3373,7 @@ async fn relay_connect_error_releases_user_and_ip_before_return() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 8).await;

    let mut config = ProxyConfig::default();
    config.access.user_max_tcp_conns.insert(user.to_string(), 1);
@@ -3251,11 +3387,14 @@ async fn relay_connect_error_releases_user_and_ip_before_return() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -3330,6 +3469,7 @@ async fn mixed_release_and_drop_same_ip_preserves_counter_correctness() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;

    let reservation_a = RunningClientHandler::acquire_user_connection_reservation_static(
        user,
@@ -3390,6 +3530,7 @@ async fn drop_one_of_two_same_ip_reservations_keeps_ip_active() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;

    let reservation_a = RunningClientHandler::acquire_user_connection_reservation_static(
        user,
@@ -3599,6 +3740,7 @@ async fn cross_thread_drop_uses_captured_runtime_for_ip_cleanup() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 8).await;

    let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
        user,
@@ -3643,6 +3785,7 @@ async fn immediate_reacquire_after_cross_thread_drop_succeeds() {

    let stats = Arc::new(Stats::new());
    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker.set_user_limit(user, 1).await;

    let reservation = RunningClientHandler::acquire_user_connection_reservation_static(
        user,
@@ -3812,11 +3955,14 @@ async fn untrusted_proxy_header_source_is_rejected() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -3882,11 +4028,14 @@ async fn empty_proxy_trusted_cidrs_rejects_proxy_header_by_default() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -3979,11 +4128,14 @@ async fn oversized_tls_record_is_masked_in_generic_stream_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -4082,11 +4234,14 @@ async fn oversized_tls_record_is_masked_in_client_handler_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -4199,11 +4354,14 @@ async fn tls_record_len_min_minus_1_is_rejected_in_generic_stream_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -4302,11 +4460,14 @@ async fn tls_record_len_min_minus_1_is_rejected_in_client_handler_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -4408,11 +4569,14 @@ async fn tls_record_len_16384_is_accepted_in_generic_stream_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -4509,11 +4673,14 @@ async fn tls_record_len_16384_is_accepted_in_client_handler_pipeline() {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -24,11 +24,14 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -26,11 +26,14 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -27,11 +27,14 @@ fn make_test_upstream_manager(stats: Arc<Stats>) -> Arc<UpstreamManager> {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
@@ -41,11 +41,14 @@ fn build_harness(secret_hex: &str, mask_port: u16) -> PipelineHarness {
            upstream_type: UpstreamType::Direct {
                interface: None,
                bind_addresses: None,
+                bindtodevice: None,
            },
            weight: 1,
            enabled: true,
            scopes: String::new(),
            selected_scope: String::new(),
+            ipv4: None,
+            ipv6: None,
        }],
        1,
        1,
--- a/Show More
+++ b/Show More