Merge pull request #454 from DavidOsipov/pr-sec-1

PR-SEC-1: Доп. харденинг и маскинг

.cargo/deny.toml

@@ -0,0 +1,15 @@
+[bans]
+multiple-versions = "deny"
+wildcards = "allow"
+highlight = "all"
+
+# Explicitly flag the weak cryptography so the agent is forced to justify its existence
+[[bans.skip]]
+name = "md-5"
+version = "*"
+reason = "MUST VERIFY: Only allowed for legacy checksums, never for security."
+
+[[bans.skip]]
+name = "sha1"
+version = "*"
+reason = "MUST VERIFY: Only allowed for backwards compatibility."

.github/instructions/rust_rules.instructions.md

@@ -0,0 +1,135 @@
+---
+description: 'Rust programming language coding conventions and best practices'
+applyTo: '**/*.rs'
+---
+
+# Rust Coding Conventions and Best Practices
+
+Follow idiomatic Rust practices and community standards when writing Rust code. 
+
+These instructions are based on [The Rust Book](https://doc.rust-lang.org/book/), [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/), [RFC 430 naming conventions](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md), and the broader Rust community at [users.rust-lang.org](https://users.rust-lang.org).
+
+## General Instructions
+
+- Always prioritize readability, safety, and maintainability.
+- Use strong typing and leverage Rust's ownership system for memory safety.
+- Break down complex functions into smaller, more manageable functions.
+- For algorithm-related code, include explanations of the approach used.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle errors gracefully using `Result<T, E>` and provide meaningful error messages.
+- For external dependencies, mention their usage and purpose in documentation.
+- Use consistent naming conventions following [RFC 430](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md).
+- Write idiomatic, safe, and efficient Rust code that follows the borrow checker's rules.
+- Ensure code compiles without warnings.
+
+## Patterns to Follow
+
+- Use modules (`mod`) and public interfaces (`pub`) to encapsulate logic.
+- Handle errors properly using `?`, `match`, or `if let`.
+- Use `serde` for serialization and `thiserror` or `anyhow` for custom errors.
+- Implement traits to abstract services or external dependencies.
+- Structure async code using `async/await` and `tokio` or `async-std`.
+- Prefer enums over flags and states for type safety.
+- Use builders for complex object creation.
+- Split binary and library code (`main.rs` vs `lib.rs`) for testability and reuse.
+- Use `rayon` for data parallelism and CPU-bound tasks.
+- Use iterators instead of index-based loops as they're often faster and safer.
+- Use `&str` instead of `String` for function parameters when you don't need ownership.
+- Prefer borrowing and zero-copy operations to avoid unnecessary allocations.
+
+### Ownership, Borrowing, and Lifetimes
+
+- Prefer borrowing (`&T`) over cloning unless ownership transfer is necessary.
+- Use `&mut T` when you need to modify borrowed data.
+- Explicitly annotate lifetimes when the compiler cannot infer them.
+- Use `Rc<T>` for single-threaded reference counting and `Arc<T>` for thread-safe reference counting.
+- Use `RefCell<T>` for interior mutability in single-threaded contexts and `Mutex<T>` or `RwLock<T>` for multi-threaded contexts.
+
+## Patterns to Avoid
+
+- Don't use `unwrap()` or `expect()` unless absolutely necessary—prefer proper error handling.
+- Avoid panics in library code—return `Result` instead.
+- Don't rely on global mutable state—use dependency injection or thread-safe containers.
+- Avoid deeply nested logic—refactor with functions or combinators.
+- Don't ignore warnings—treat them as errors during CI.
+- Avoid `unsafe` unless required and fully documented.
+- Don't overuse `clone()`, use borrowing instead of cloning unless ownership transfer is needed.
+- Avoid premature `collect()`, keep iterators lazy until you actually need the collection.
+- Avoid unnecessary allocations—prefer borrowing and zero-copy operations.
+
+## Code Style and Formatting
+
+- Follow the Rust Style Guide and use `rustfmt` for automatic formatting.
+- Keep lines under 100 characters when possible.
+- Place function and struct documentation immediately before the item using `///`.
+- Use `cargo clippy` to catch common mistakes and enforce best practices.
+
+## Error Handling
+
+- Use `Result<T, E>` for recoverable errors and `panic!` only for unrecoverable errors.
+- Prefer `?` operator over `unwrap()` or `expect()` for error propagation.
+- Create custom error types using `thiserror` or implement `std::error::Error`.
+- Use `Option<T>` for values that may or may not exist.
+- Provide meaningful error messages and context.
+- Error types should be meaningful and well-behaved (implement standard traits).
+- Validate function arguments and return appropriate errors for invalid input.
+
+## API Design Guidelines
+
+### Common Traits Implementation
+Eagerly implement common traits where appropriate:
+- `Copy`, `Clone`, `Eq`, `PartialEq`, `Ord`, `PartialOrd`, `Hash`, `Debug`, `Display`, `Default`
+- Use standard conversion traits: `From`, `AsRef`, `AsMut`
+- Collections should implement `FromIterator` and `Extend`
+- Note: `Send` and `Sync` are auto-implemented by the compiler when safe; avoid manual implementation unless using `unsafe` code
+
+### Type Safety and Predictability
+- Use newtypes to provide static distinctions
+- Arguments should convey meaning through types; prefer specific types over generic `bool` parameters
+- Use `Option<T>` appropriately for truly optional values
+- Functions with a clear receiver should be methods
+- Only smart pointers should implement `Deref` and `DerefMut`
+
+### Future Proofing
+- Use sealed traits to protect against downstream implementations
+- Structs should have private fields
+- Functions should validate their arguments
+- All public types must implement `Debug`
+
+## Testing and Documentation
+
+- Write comprehensive unit tests using `#[cfg(test)]` modules and `#[test]` annotations.
+- Use test modules alongside the code they test (`mod tests { ... }`).
+- Write integration tests in `tests/` directory with descriptive filenames.
+- Write clear and concise comments for each function, struct, enum, and complex logic.
+- Ensure functions have descriptive names and include comprehensive documentation.
+- Document all public APIs with rustdoc (`///` comments) following the [API Guidelines](https://rust-lang.github.io/api-guidelines/).
+- Use `#[doc(hidden)]` to hide implementation details from public documentation.
+- Document error conditions, panic scenarios, and safety considerations.
+- Examples should use `?` operator, not `unwrap()` or deprecated `try!` macro.
+
+## Project Organization
+
+- Use semantic versioning in `Cargo.toml`.
+- Include comprehensive metadata: `description`, `license`, `repository`, `keywords`, `categories`.
+- Use feature flags for optional functionality.
+- Organize code into modules using `mod.rs` or named files.
+- Keep `main.rs` or `lib.rs` minimal - move logic to modules.
+
+## Quality Checklist
+
+Before publishing or reviewing Rust code, ensure:
+
+### Core Requirements
+- [ ] **Naming**: Follows RFC 430 naming conventions
+- [ ] **Traits**: Implements `Debug`, `Clone`, `PartialEq` where appropriate
+- [ ] **Error Handling**: Uses `Result<T, E>` and provides meaningful error types
+- [ ] **Documentation**: All public items have rustdoc comments with examples
+- [ ] **Testing**: Comprehensive test coverage including edge cases
+
+### Safety and Quality
+- [ ] **Safety**: No unnecessary `unsafe` code, proper error handling
+- [ ] **Performance**: Efficient use of iterators, minimal allocations
+- [ ] **API Design**: Functions are predictable, flexible, and type-safe
+- [ ] **Future Proofing**: Private fields in structs, sealed traits where appropriate
+- [ ] **Tooling**: Code passes `cargo fmt`, `cargo clippy`, and `cargo test`

.github/instructions/self-explanatory-code-commenting.instructions.md

@@ -0,0 +1,162 @@
+---
+description: 'Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments.'
+applyTo: '**'
+---
+
+# Self-explanatory Code Commenting Instructions
+
+## Core Principle
+**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**
+We do not need comments most of the time.
+
+## Commenting Guidelines
+
+### ❌ AVOID These Comment Types
+
+**Obvious Comments**
+```javascript
+// Bad: States the obvious
+let counter = 0;  // Initialize counter to zero
+counter++;  // Increment counter by one
+```
+
+**Redundant Comments**
+```javascript
+// Bad: Comment repeats the code
+function getUserName() {
+    return user.name;  // Return the user's name
+}
+```
+
+**Outdated Comments**
+```javascript
+// Bad: Comment doesn't match the code
+// Calculate tax at 5% rate
+const tax = price * 0.08;  // Actually 8%
+```
+
+### ✅ WRITE These Comment Types
+
+**Complex Business Logic**
+```javascript
+// Good: Explains WHY this specific calculation
+// Apply progressive tax brackets: 10% up to 10k, 20% above
+const tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);
+```
+
+**Non-obvious Algorithms**
+```javascript
+// Good: Explains the algorithm choice
+// Using Floyd-Warshall for all-pairs shortest paths
+// because we need distances between all nodes
+for (let k = 0; k < vertices; k++) {
+    for (let i = 0; i < vertices; i++) {
+        for (let j = 0; j < vertices; j++) {
+            // ... implementation
+        }
+    }
+}
+```
+
+**Regex Patterns**
+```javascript
+// Good: Explains what the regex matches
+// Match email format: username@domain.extension
+const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+```
+
+**API Constraints or Gotchas**
+```javascript
+// Good: Explains external constraint
+// GitHub API rate limit: 5000 requests/hour for authenticated users
+await rateLimiter.wait();
+const response = await fetch(githubApiUrl);
+```
+
+## Decision Framework
+
+Before writing a comment, ask:
+1. **Is the code self-explanatory?** → No comment needed
+2. **Would a better variable/function name eliminate the need?** → Refactor instead
+3. **Does this explain WHY, not WHAT?** → Good comment
+4. **Will this help future maintainers?** → Good comment
+
+## Special Cases for Comments
+
+### Public APIs
+```javascript
+/**
+ * Calculate compound interest using the standard formula.
+ * 
+ * @param {number} principal - Initial amount invested
+ * @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)
+ * @param {number} time - Time period in years
+ * @param {number} compoundFrequency - How many times per year interest compounds (default: 1)
+ * @returns {number} Final amount after compound interest
+ */
+function calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {
+    // ... implementation
+}
+```
+
+### Configuration and Constants
+```javascript
+// Good: Explains the source or reasoning
+const MAX_RETRIES = 3;  // Based on network reliability studies
+const API_TIMEOUT = 5000;  // AWS Lambda timeout is 15s, leaving buffer
+```
+
+### Annotations
+```javascript
+// TODO: Replace with proper user authentication after security review
+// FIXME: Memory leak in production - investigate connection pooling
+// HACK: Workaround for bug in library v2.1.0 - remove after upgrade
+// NOTE: This implementation assumes UTC timezone for all calculations
+// WARNING: This function modifies the original array instead of creating a copy
+// PERF: Consider caching this result if called frequently in hot path
+// SECURITY: Validate input to prevent SQL injection before using in query
+// BUG: Edge case failure when array is empty - needs investigation
+// REFACTOR: Extract this logic into separate utility function for reusability
+// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0
+```
+
+## Anti-Patterns to Avoid
+
+### Dead Code Comments
+```javascript
+// Bad: Don't comment out code
+// const oldFunction = () => { ... };
+const newFunction = () => { ... };
+```
+
+### Changelog Comments
+```javascript
+// Bad: Don't maintain history in comments
+// Modified by John on 2023-01-15
+// Fixed bug reported by Sarah on 2023-02-03
+function processData() {
+    // ... implementation
+}
+```
+
+### Divider Comments
+```javascript
+// Bad: Don't use decorative comments
+//=====================================
+// UTILITY FUNCTIONS
+//=====================================
+```
+
+## Quality Checklist
+
+Before committing, ensure your comments:
+- [ ] Explain WHY, not WHAT
+- [ ] Are grammatically correct and clear
+- [ ] Will remain accurate as code evolves
+- [ ] Add genuine value to code understanding
+- [ ] Are placed appropriately (above the code they describe)
+- [ ] Use proper spelling and professional language
+
+## Summary
+
+Remember: **The best comment is the one you don't need to write because the code is self-documenting.**

AGENTS.md

@@ -5,6 +5,22 @@ Your responses are precise, minimal, and architecturally sound. You are working
 
 ---
 
+### Context: The Telemt Project
+
+You are working on **Telemt**, a high-performance, production-grade Telegram MTProxy implementation written in Rust. It is explicitly designed to operate in highly hostile network environments and evade advanced network censorship.
+
+**Adversarial Threat Model:**
+The proxy operates under constant surveillance by DPI (Deep Packet Inspection) systems and active scanners (state firewalls, mobile operator fraud controls). These entities actively probe IPs, analyze protocol handshakes, and look for known proxy signatures to block or throttle traffic.
+
+**Core Architectural Pillars:**
+1. **TLS-Fronting (TLS-F) & TCP-Splitting (TCP-S):** To the outside world, Telemt looks like a standard TLS server. If a client presents a valid MTProxy key, the connection is handled internally. If a censor's scanner, web browser, or unauthorized crawler connects, Telemt seamlessly splices the TCP connection (L4) to a real, legitimate HTTPS fallback server (e.g., Nginx) without modifying the `ClientHello` or terminating the TLS handshake.
+2. **Middle-End (ME) Orchestration:** A highly concurrent, generation-based pool managing upstream connections to Telegram Datacenters (DCs). It utilizes an **Adaptive Floor** (dynamically scaling writer connections based on traffic), **Hardswaps** (zero-downtime pool reconfiguration), and **STUN/NAT** reflection mechanisms. 
+3. **Strict KDF Routing:** Cryptographic Key Derivation Functions (KDF) in this protocol strictly rely on the exact pairing of Source IP/Port and Destination IP/Port. Deviations or missing port logic will silently break the MTProto handshake.
+4. **Data Plane vs. Control Plane Isolation:** The Data Plane (readers, writers, payload relay, TCP splicing) must remain strictly non-blocking, zero-allocation in hot paths, and highly resilient to network backpressure. The Control Plane (API, metrics, pool generation swaps, config reloads) orchestrates the state asynchronously without stalling the Data Plane.
+
+Any modification you make must preserve Telemt's invisibility to censors, its strict memory-safety invariants, and its hot-path throughput.
+
+
 ### 0. Priority Resolution — Scope Control
 
 This section resolves conflicts between code quality enforcement and scope limitation.

CONTRIBUTING.md

@@ -1,3 +1,8 @@
+# Issues - Rules
+## What it is not
+- NOT Question and Answer
+- NOT Helpdesk
+
 # Pull Requests - Rules
 ## General
 - ONLY signed and verified commits

Cargo.lock

@@ -2025,6 +2025,12 @@ version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
 [[package]]
 name = "subtle"
 version = "2.6.1"
@@ -2087,7 +2093,7 @@ dependencies = [
 
 [[package]]
 name = "telemt"
-version = "3.1.3"
+version = "3.3.19"
 dependencies = [
  "aes",
  "anyhow",
@@ -2127,6 +2133,8 @@ dependencies = [
  "sha1",
  "sha2",
  "socket2 0.5.10",
+ "static_assertions",
+ "subtle",
  "thiserror 2.0.18",
  "tokio",
  "tokio-rustls",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.1.4"
+version = "3.3.20"
 edition = "2024"
 
 [dependencies]
@@ -22,6 +22,8 @@ hmac = "0.12"
 crc32fast = "1.4"
 crc32c = "0.6"
 zeroize = { version = "1.8", features = ["derive"] }
+subtle = "2.6"
+static_assertions = "1.1"
 
 # Network
 socket2 = { version = "0.5", features = ["all"] }
@@ -73,3 +75,6 @@ futures = "0.3"
 [[bench]]
 name = "crypto_bench"
 harness = false
+
+[profile.release]
+lto = "thin"

LICENSE

@@ -0,0 +1,165 @@
+###### TELEMT Public License 3 ######
+##### Copyright (c) 2026 Telemt #####
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this Software and associated documentation files (the "Software"),
+to use, reproduce, modify, prepare derivative works of, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, provided that all
+copyright notices, license terms, and conditions set forth in this License
+are preserved and complied with.
+
+### Official Translations
+
+The canonical version of this License is the English version.
+Official translations are provided for informational purposes only
+and for convenience, and do not have legal force. In case of any
+discrepancy, the English version of this License shall prevail.
+Available versions:
+- English in Markdown: docs/LICENSE/LICENSE.md
+- German: docs/LICENSE/LICENSE.de.md
+- Russian: docs/LICENSE/LICENSE.ru.md
+
+### License Versioning Policy
+
+This License is version 3 of the TELEMT Public License.
+Each version of the Software is licensed under the License that
+accompanies its corresponding source code distribution.
+
+Future versions of the Software may be distributed under a different
+version of the TELEMT Public License or under a different license,
+as determined by the Telemt maintainers.
+
+Any such change of license applies only to the versions of the
+Software distributed with the new license and SHALL NOT retroactively
+affect any previously released versions of the Software.
+
+Recipients of the Software are granted rights only under the License
+provided with the version of the Software they received.
+
+Redistributions of the Software, including Modified Versions, MUST
+preserve the copyright notices, license text, and conditions of this
+License for all portions of the Software derived from Telemt.
+
+Additional terms or licenses may be applied to modifications or
+additional code added by a redistributor, provided that such terms
+do not restrict or alter the rights granted under this License for
+the original Telemt Software.
+
+Nothing in this section limits the rights granted under this License
+for versions of the Software already released.
+
+### Definitions
+
+For the purposes of this License:
+- "Software" means the Telemt software, including source code, documentation,
+and any associated files distributed under this License.
+- "Contributor" means any person or entity that submits code, patches,
+documentation, or other contributions to the Software that are accepted
+into the Software by the maintainers.
+- "Contribution" means any work of authorship intentionally submitted
+to the Software for inclusion in the Software.
+- "Modified Version" means any version of the Software that has been
+changed, adapted, extended, or otherwise modified from the original
+Software.
+- "Maintainers" means the individuals or entities responsible for
+the official Telemt project and its releases.
+
+#### 1 Attribution
+
+Redistributions of the Software, in source or binary form, MUST RETAIN the
+above copyright notice, this license text, and any existing attribution
+notices.
+
+#### 2 Modification Notice
+
+If you modify the Software, you MUST clearly state that the Software has been
+modified and include a brief description of the changes made.
+
+Modified versions MUST NOT be presented as the original Telemt.
+
+#### 3 Trademark and Branding
+
+This license DOES NOT grant permission to use the name "Telemt", 
+the Telemt logo, or any Telemt trademarks or branding.
+
+Redistributed or modified versions of the Software MAY NOT use the Telemt
+name in a way that suggests endorsement or official origin without explicit
+permission from the Telemt maintainers.
+
+Use of the name "Telemt" to describe a modified version of the Software
+is permitted only if the modified version is clearly identified as a
+modified or unofficial version.
+
+Any distribution that could reasonably confuse users into believing that
+the software is an official Telemt release is prohibited.
+
+#### 4 Binary Distribution Transparency
+
+If you distribute compiled binaries of the Software,
+you are ENCOURAGED to provide access to the corresponding
+source code and build instructions where reasonably possible.
+
+This helps preserve transparency and allows recipients to verify the
+integrity and reproducibility of distributed builds.
+
+#### 5 Patent Grant and Defensive Termination Clause
+
+Each contributor grants you a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Software.
+
+This patent license applies only to those patent claims necessarily
+infringed by the contributor’s contribution alone or by combination of
+their contribution with the Software.
+
+If you initiate or participate in any patent litigation, including
+cross-claims or counterclaims, alleging that the Software or any
+contribution incorporated within the Software constitutes patent
+infringement, then **all rights granted to you under this license shall
+terminate immediately** as of the date such litigation is filed.
+
+Additionally, if you initiate legal action alleging that the
+Software itself infringes your patent or other intellectual
+property rights, then all rights granted to you under this
+license SHALL TERMINATE automatically.
+
+#### 6 Contributions
+
+Unless you explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Software shall be licensed under the terms
+of this License.
+
+By submitting a Contribution, you grant the Telemt maintainers and all
+recipients of the Software the rights described in this License with
+respect to that Contribution.
+
+#### 7 Network Use Attribution
+
+If the Software is used to provide a publicly accessible network service,
+the operator of such service SHOULD provide attribution to Telemt in at least
+one of the following locations:
+
+- service documentation
+- service description
+- an "About" or similar informational page
+- other user-visible materials reasonably associated with the service
+
+Such attribution MUST NOT imply endorsement by the Telemt project or its
+maintainers.
+
+#### 8 Disclaimer of Warranty and Severability Clause
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE
+
+IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE,
+SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT
+OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS
+SHALL REMAIN IN FULL FORCE AND EFFECT

LICENSING.md

@@ -1,17 +1,12 @@
 # LICENSING
 ## Licenses for Versions
-| Version | License       |
-|---------|---------------|
-| 1.0     | NO LICNESE    |
-| 1.1     | NO LICENSE    |
-| 1.2     | NO LICENSE    |
-| 2.0     | NO LICENSE    |
-| 3.0     | TELEMT UL 1   |
+| Version ≥ | Version ≤ | License       |
+|-----------|-----------|---------------|
+| 1.0       | 3.3.17    | NO LICNESE    |
+| 3.3.18    | 3.4.0     | TELEMT PL 3   |
 
 ### License Types
 - **NO LICENSE** = ***ALL RIGHT RESERVED***
-- **TELEMT UL1** - work in progress license for source code of `telemt`, which encourages:
-  - fair use, 
-  - contributions, 
-  - distribution, 
-  - but prohibits NOT mentioning the authors
+- **TELEMT PL** - special Telemt Public License based on Apache License 2 principles
+
+## [Telemt Public License 3](https://github.com/telemt/telemt/blob/main/LICENSE)

README.md

@@ -1,6 +1,13 @@
 # Telemt - MTProxy on Rust + Tokio
 
-**Telemt** is a fast, secure, and feature-rich server written in Rust: it fully implements the official Telegram proxy algo and adds many production-ready improvements such as connection pooling, replay protection, detailed statistics, masking from "prying" eyes
+***Löst Probleme, bevor andere überhaupt wissen, dass sie existieren*** / ***It solves problems before others even realize they exist***
+
+**Telemt** is a fast, secure, and feature-rich server written in Rust: it fully implements the official Telegram proxy algo and adds many production-ready improvements such as:
+- [ME Pool + Reader/Writer + Registry + Refill + Adaptive Floor + Trio-State + Generation Lifecycle](https://github.com/telemt/telemt/blob/main/docs/model/MODEL.en.md)
+- [Full-covered API w/ management](https://github.com/telemt/telemt/blob/main/docs/API.md)
+- Anti-Replay on Sliding Window
+- Prometheus-format Metrics
+- TLS-Fronting and TCP-Splicing for masking from "prying" eyes
 
 [**Telemt Chat in Telegram**](https://t.me/telemtrs)
 
@@ -12,18 +19,11 @@
 
 ### 🇷🇺 RU
 
-#### Релиз 3.0.15 — 25 февраля
+#### Релиз 3.3.15 Semistable
 
-25 февраля мы выпустили версию **3.0.15**
+[3.3.15](https://github.com/telemt/telemt/releases/tag/3.3.15) по итогам работы в продакшн признан одним из самых стабильных и рекомендуется к использованию, когда cutting-edge фичи некритичны!
 
-Мы предполагаем, что она станет завершающей версией поколения 3.0 и уже сейчас мы рассматриваем её как **LTS-кандидата** для версии **3.1.0**!
-
-После нескольких дней детального анализа особенностей работы Middle-End мы спроектировали и реализовали продуманный режим **ротации ME Writer**. Данный режим позволяет поддерживать стабильно высокую производительность в long-run сценариях без возникновения ошибок, связанных с некорректной конфигурацией прокси
-
-Будем рады вашему фидбеку и предложениям по улучшению — особенно в части **статистики** и **UX**
-
-Релиз:  
-[3.0.15](https://github.com/telemt/telemt/releases/tag/3.0.15)
+Будем рады вашему фидбеку и предложениям по улучшению — особенно в части **API**, **статистики**, **UX**
 
 ---
 
@@ -40,18 +40,11 @@
 
 ### 🇬🇧 EN
 
-#### Release 3.0.15 — February 25
+#### Release 3.3.15 Semistable
 
-On February 25, we released version **3.0.15**
+[3.3.15](https://github.com/telemt/telemt/releases/tag/3.3.15) is, based on the results of his work in production, recognized as one of the most stable and recommended for use when cutting-edge features are not so necessary!
 
-We expect this to become the final release of the 3.0 generation and at this point, we already see it as a strong **LTS candidate** for the upcoming **3.1.0** release!
-
-After several days of deep analysis of Middle-End behavior, we designed and implemented a well-engineered **ME Writer rotation mode**. This mode enables sustained high throughput in long-run scenarios while preventing proxy misconfiguration errors
-
-We are looking forward to your feedback and improvement proposals — especially regarding **statistics** and **UX**
-
-Release:  
-[3.0.15](https://github.com/telemt/telemt/releases/tag/3.0.15)
+We are looking forward to your feedback and improvement proposals — especially regarding **API**, **statistics**, **UX**
 
 ---
 
@@ -74,31 +67,6 @@ We welcome ideas, architectural feedback, and pull requests.
 
 ⚓ 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
 
-# GOTO
-- [Features](#features)
-- [Quick Start Guide](#quick-start-guide)
-- [How to use?](#how-to-use)
-  - [Systemd Method](#telemt-via-systemd)
-- [Configuration](#configuration)
-  - [Minimal Configuration](#minimal-configuration-for-first-start)
-  - [Advanced](#advanced)
-    - [Adtag](#adtag)
-    - [Listening and Announce IPs](#listening-and-announce-ips)
-    - [Upstream Manager](#upstream-manager)
-      - [IP](#bind-on-ip)
-      - [SOCKS](#socks45-as-upstream)
-- [FAQ](#faq)
-  - [Recognizability for DPI + crawler](#recognizability-for-dpi-and-crawler)
-  - [Telegram Calls](#telegram-calls-via-mtproxy)
-  - [DPI](#how-does-dpi-see-mtproxy-tls)
-  - [Whitelist on Network Level](#whitelist-on-ip)
-  - [Too many open files](#too-many-open-files)
-- [Build](#build)
-- [Docker](#docker)
-- [Why Rust?](#why-rust)
-
-## Features
-
 - Full support for all official MTProto proxy modes:
   - Classic
   - Secure - with `dd` prefix
@@ -109,158 +77,31 @@ We welcome ideas, architectural feedback, and pull requests.
 - Graceful shutdown on Ctrl+C
 - Extensive logging via `trace` and `debug` with `RUST_LOG` method
 
+# GOTO
+- [Quick Start Guide](#quick-start-guide)
+- [FAQ](#faq)
+  - [Recognizability for DPI and crawler](#recognizability-for-dpi-and-crawler)
+    - [Client WITH secret-key accesses the MTProxy resource:](#client-with-secret-key-accesses-the-mtproxy-resource)
+    - [Client WITHOUT secret-key gets transparent access to the specified resource:](#client-without-secret-key-gets-transparent-access-to-the-specified-resource)
+  - [Telegram Calls via MTProxy](#telegram-calls-via-mtproxy)
+  - [How does DPI see MTProxy TLS?](#how-does-dpi-see-mtproxy-tls)
+  - [Whitelist on IP](#whitelist-on-ip)
+  - [Too many open files](#too-many-open-files)
+- [Build](#build)
+- [Why Rust?](#why-rust)
+- [Issues](#issues)
+- [Roadmap](#roadmap)
+
+
 ## Quick Start Guide
-**This software is designed for Debian-based OS: in addition to Debian, these are Ubuntu, Mint, Kali, MX and many other Linux**
-1. Download release
-```bash
-wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
-```
-2. Move to Bin Folder
-```bash
-mv telemt /bin
-```
-4. Make Executable
-```bash
-chmod +x /bin/telemt
-```
-5. Go to [How to use?](#how-to-use) section for for further steps
-
-## How to use?
-### Telemt via Systemd
-**This instruction "assume" that you:**
-- logged in as root or executed `su -` / `sudo su`
-- you already have an assembled and executable `telemt` in /bin folder as a result of the [Quick Start Guide](#quick-start-guide) or [Build](#build)
-
-**0. Check port and generate secrets**
-
-The port you have selected for use should be MISSING from the list, when:
-```bash
-netstat -lnp
-```
-
-Generate 16 bytes/32 characters HEX with OpenSSL or another way:
-```bash
-openssl rand -hex 16
-```
-OR
-```bash
-xxd -l 16 -p /dev/urandom
-```
-OR
-```bash
-python3 -c 'import os; print(os.urandom(16).hex())'
-```
-
-**1. Place your config to /etc/telemt.toml**
-
-Open nano
-```bash
-nano /etc/telemt.toml
-```
-paste your config from [Configuration](#configuration) section
-
-then Ctrl+X -> Y -> Enter to save
-
-**2. Create service on /etc/systemd/system/telemt.service**
-
-Open nano
-```bash
-nano /etc/systemd/system/telemt.service
-```
-paste this Systemd Module
-```bash
-[Unit]
-Description=Telemt
-After=network.target
-
-[Service]
-Type=simple
-WorkingDirectory=/bin
-ExecStart=/bin/telemt /etc/telemt.toml
-Restart=on-failure
-LimitNOFILE=65536
-
-[Install]
-WantedBy=multi-user.target
-```
-then Ctrl+X -> Y -> Enter to save
-
-**3.**  In Shell type `systemctl start telemt` - it must start with zero exit-code
-
-**4.** In Shell type `systemctl status telemt` - there you can reach info about current MTProxy status
-
-**5.** In Shell type `systemctl enable telemt` - then telemt will start with system startup, after the network is up
-
-**6.** In Shell type `journalctl -u telemt -n -g "links" --no-pager -o cat | tac` - get the connection links
-
-## Configuration
-### Minimal Configuration for First Start
-```toml
-# === General Settings ===
-[general]
-# ad_tag = "00000000000000000000000000000000"
-
-[general.modes]
-classic = false
-secure = false
-tls = true
-
-# === Anti-Censorship & Masking ===
-[censorship]
-tls_domain = "petrovich.ru"
-
-[access.users]
-# format: "username" = "32_hex_chars_secret"
-hello = "00000000000000000000000000000000"
-
-```
-### Advanced
-#### Adtag (per-user)
-To use channel advertising and usage statistics from Telegram, get an Adtag from [@mtproxybot](https://t.me/mtproxybot). Set it per user in `[access.user_ad_tags]` (32 hex chars):
-```toml
-[access.user_ad_tags]
-username1 = "11111111111111111111111111111111"  # Replace with your tag from @mtproxybot
-username2 = "22222222222222222222222222222222"
-```
-#### Listening and Announce IPs
-To specify listening address and/or address in links, add to section `[[server.listeners]]` of config.toml:
-```toml
-[[server.listeners]]
-ip = "0.0.0.0"          # 0.0.0.0 = all IPs; your IP = specific listening
-announce_ip = "1.2.3.4" # IP in links; comment with # if not used
-```
-#### Upstream Manager
-To specify upstream, add to section `[[upstreams]]` of config.toml:
-##### Bind on IP
-```toml
-[[upstreams]]
-type = "direct"
-weight = 1
-enabled = true
-interface = "192.168.1.100" # Change to your outgoing IP
-```
-##### SOCKS4/5 as Upstream
-- Without Auth:
-```toml
-[[upstreams]]
-type = "socks5"            # Specify SOCKS4 or SOCKS5
-address = "1.2.3.4:1234"   # SOCKS-server Address
-weight = 1                 # Set Weight for Scenarios
-enabled = true
-```
-
-- With Auth:
-```toml
-[[upstreams]]
-type = "socks5"            # Specify SOCKS4 or SOCKS5
-address = "1.2.3.4:1234"   # SOCKS-server Address
-username = "user"          # Username for Auth on SOCKS-server
-password = "pass"          # Password for Auth on SOCKS-server
-weight = 1                 # Set Weight for Scenarios
-enabled = true
-```
+- [Quick Start Guide RU](docs/QUICK_START_GUIDE.ru.md)
+- [Quick Start Guide EN](docs/QUICK_START_GUIDE.en.md)
 
 ## FAQ
+
+- [FAQ RU](docs/FAQ.ru.md)
+- [FAQ EN](docs/FAQ.en.md)
+
 ### Recognizability for DPI and crawler
 Since version 1.1.0.0, we have debugged masking perfectly: for all clients without "presenting" a key, 
 we transparently direct traffic to the target host!
@@ -397,6 +238,11 @@ git clone https://github.com/telemt/telemt
 cd telemt
 # Starting Release Build
 cargo build --release
+
+# Low-RAM devices (1 GB, e.g. NanoPi Neo3 / Raspberry Pi Zero 2):
+# release profile uses lto = "thin" to reduce peak linker memory.
+# If your custom toolchain overrides profiles, avoid enabling fat LTO.
+
 # Move to /bin
 mv ./target/release/telemt /bin
 # Make executable
@@ -405,40 +251,11 @@ chmod +x /bin/telemt
 telemt config.toml
 ```
 
-## Docker
-**Quick start (Docker Compose)**
+### OpenBSD
+- Build and service setup guide: [OpenBSD Guide (EN)](docs/OPENBSD.en.md)
+- Example rc.d script: [contrib/openbsd/telemt.rcd](contrib/openbsd/telemt.rcd)
+- Status: OpenBSD sandbox hardening with `pledge(2)` and `unveil(2)` is not implemented yet.
 
-1. Edit `config.toml` in repo root (at least: port, users secrets, tls_domain)
-2. Start container:
-```bash
-docker compose up -d --build
-```
-3. Check logs:
-```bash
-docker compose logs -f telemt
-```
-4. Stop:
-```bash
-docker compose down
-```
-
-**Notes**
-- `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`
-
-**Run without Compose**
-```bash
-docker build -t telemt:local .
-docker run --name telemt --restart unless-stopped \
-  -p 443:443 \
-  -e RUST_LOG=info \
-  -v "$PWD/config.toml:/app/config.toml:ro" \
-  --read-only \
-  --cap-drop ALL --cap-add NET_BIND_SERVICE \
-  --ulimit nofile=65536:65536 \
-  telemt:local
-```
 
 ## Why Rust?
 - Long-running reliability and idempotent behavior

config.full.toml

@@ -1,697 +0,0 @@
-# ==============================================================================
-#
-#   TELEMT — Advanced Rust-based Telegram MTProto Proxy
-#   Full Configuration Reference
-#
-#   This file is both a working config and a complete documentation.
-#   Every parameter is explained. Read it top to bottom before deploying.
-#
-#   Quick Start:
-#     1. Set [server].port to your desired port (443 recommended)
-#     2. Generate a secret: openssl rand -hex 16
-#     3. Put it in [access.users] under a name you choose
-#     4. Set [censorship].tls_domain to a popular unblocked HTTPS site
-#     5. Set your public IP in [general].middle_proxy_nat_ip
-#        and [general.links].public_host
-#     6. Set announce IP in [[server.listeners]]
-#     7. Run Telemt. It prints a tg:// link. Send it to your users.
-#
-#   Modes of Operation:
-#     Direct Mode  (use_middle_proxy = false)
-#       Connects straight to Telegram DCs via TCP. Simple, fast, low overhead.
-#       No ad_tag support. No CDN DC support (203, etc).
-#
-#     Middle-Proxy Mode  (use_middle_proxy = true)
-#       Connects to Telegram Middle-End servers via RPC protocol.
-#       Required for ad_tag monetization and CDN support.
-#       Requires proxy_secret_path and a valid public IP.
-#
-# ==============================================================================
-
-
-# ==============================================================================
-# LEGACY TOP-LEVEL FIELDS
-# ==============================================================================
-
-# Deprecated. Use [general.links].show instead.
-# Accepts "*" for all users, or an array like ["alice", "bob"].
-show_link = ["0"]
-
-# Fallback Datacenter index (1-5) when a client requests an unknown DC ID.
-# DC 2 is Amsterdam (Europe), closest for most CIS users.
-# default_dc = 2
-
-
-# ==============================================================================
-# GENERAL SETTINGS
-# ==============================================================================
-
-[general]
-
-# ------------------------------------------------------------------------------
-# Core Protocol
-# ------------------------------------------------------------------------------
-
-# Coalesce the MTProto handshake and first data payload into a single TCP packet.
-# Significantly reduces connection latency. No reason to disable.
-fast_mode = true
-
-# How the proxy connects to Telegram servers.
-# false = Direct TCP to Telegram DCs (simple, low overhead)
-# true  = Middle-End RPC protocol (required for ad_tag and CDN DCs)
-use_middle_proxy = true
-
-# 32-char hex Ad-Tag from @MTProxybot for sponsored channel injection.
-# Only works when use_middle_proxy = true.
-# Obtain yours: message @MTProxybot on Telegram, register your proxy.
-# ad_tag = "00000000000000000000000000000000"
-
-# ------------------------------------------------------------------------------
-# Middle-End Authentication
-# ------------------------------------------------------------------------------
-
-# Path to the Telegram infrastructure AES key file.
-# Auto-downloaded from https://core.telegram.org/getProxySecret on first run.
-# This key authenticates your proxy with Middle-End servers.
-proxy_secret_path = "proxy-secret"
-
-# ------------------------------------------------------------------------------
-# Public IP Configuration (Critical for Middle-Proxy Mode)
-# ------------------------------------------------------------------------------
-
-# Your server's PUBLIC IPv4 address.
-# Middle-End servers need this for the cryptographic Key Derivation Function.
-# If your server has a direct public IP, set it here.
-# If behind NAT (AWS, Docker, etc.), this MUST be your external IP.
-# If omitted, Telemt uses STUN to auto-detect (see middle_proxy_nat_probe).
-# middle_proxy_nat_ip = "203.0.113.10"
-
-# Auto-detect public IP via STUN servers defined in [network].
-# Set to false if you hardcoded middle_proxy_nat_ip above.
-# Set to true if you want automatic detection.
-middle_proxy_nat_probe = true
-
-# ------------------------------------------------------------------------------
-# Middle-End Connection Pool
-# ------------------------------------------------------------------------------
-
-# Number of persistent multiplexed RPC connections to ME servers.
-# All client traffic is routed through these "fat pipes".
-# 8 handles thousands of concurrent users comfortably.
-middle_proxy_pool_size = 8
-
-# Legacy field. Connections kept initialized but idle as warm standby.
-middle_proxy_warm_standby = 16
-
-# ------------------------------------------------------------------------------
-# Middle-End Keepalive
-# Telegram ME servers aggressively kill idle TCP connections.
-# These settings send periodic RPC_PING frames to keep pipes alive.
-# ------------------------------------------------------------------------------
-
-me_keepalive_enabled = true
-
-# Base interval between pings in seconds.
-me_keepalive_interval_secs = 25
-
-# Random jitter added to interval to prevent all connections pinging simultaneously.
-me_keepalive_jitter_secs = 5
-
-# Randomize ping payload bytes to prevent DPI from fingerprinting ping patterns.
-me_keepalive_payload_random = true
-
-# ------------------------------------------------------------------------------
-# Client-Side Limits
-# ------------------------------------------------------------------------------
-
-# Max buffered ciphertext per client (bytes) when upstream is slow.
-# Acts as backpressure to prevent memory exhaustion. 256KB is safe.
-crypto_pending_buffer = 262144
-
-# Maximum single MTProto frame size from client. 16MB is protocol standard.
-max_client_frame = 16777216
-
-# ------------------------------------------------------------------------------
-# Crypto Desynchronization Logging
-# Desync errors usually mean DPI/GFW is tampering with connections.
-# ------------------------------------------------------------------------------
-
-# true  = full forensics (trace ID, IP hash, hex dumps) for EVERY desync event
-# false = deduplicated logging, one entry per time window (prevents log spam)
-# Set true if you are actively debugging DPI interference.
-desync_all_full = true
-
-# ------------------------------------------------------------------------------
-# Beobachten — Built-in Honeypot / Active Probe Tracker
-# Tracks IPs that fail handshakes or behave like TLS scanners.
-# Output file can be fed into fail2ban or iptables for auto-blocking.
-# ------------------------------------------------------------------------------
-
-beobachten = true
-
-# How long (minutes) to remember a suspicious IP before expiring it.
-beobachten_minutes = 30
-
-# How often (seconds) to flush tracker state to disk.
-beobachten_flush_secs = 15
-
-# File path for the tracker output.
-beobachten_file = "cache/beobachten.txt"
-
-# ------------------------------------------------------------------------------
-# Hardswap — Zero-Downtime ME Pool Rotation
-# When Telegram updates ME server IPs, Hardswap creates a completely new pool,
-# waits until it is fully ready, migrates traffic, then kills the old pool.
-# Users experience zero interruption.
-# ------------------------------------------------------------------------------
-
-hardswap = true
-
-# ------------------------------------------------------------------------------
-# ME Pool Warmup Staggering
-# When creating a new pool, connections are opened one by one with delays
-# to avoid a burst of SYN packets that could trigger ISP flood protection.
-# ------------------------------------------------------------------------------
-
-me_warmup_stagger_enabled = true
-
-# Delay between each connection creation (milliseconds).
-me_warmup_step_delay_ms = 500
-
-# Random jitter added to the delay (milliseconds).
-me_warmup_step_jitter_ms = 300
-
-# ------------------------------------------------------------------------------
-# ME Reconnect Backoff
-# If an ME server drops the connection, Telemt retries with this strategy.
-# ------------------------------------------------------------------------------
-
-# Max simultaneous reconnect attempts per DC.
-me_reconnect_max_concurrent_per_dc = 8
-
-# Exponential backoff base (milliseconds).
-me_reconnect_backoff_base_ms = 500
-
-# Backoff ceiling (milliseconds). Will never wait longer than this.
-me_reconnect_backoff_cap_ms = 30000
-
-# Number of instant retries before switching to exponential backoff.
-me_reconnect_fast_retry_count = 12
-
-# ------------------------------------------------------------------------------
-# NAT Mismatch Behavior
-# If STUN-detected IP differs from local interface IP (you are behind NAT).
-# false = abort ME mode (safe default)
-# true  = force ME mode anyway (use if you know your NAT setup is correct)
-# ------------------------------------------------------------------------------
-
-stun_iface_mismatch_ignore = false
-
-# ------------------------------------------------------------------------------
-# Logging
-# ------------------------------------------------------------------------------
-
-# File to log unknown DC requests (DC IDs outside standard 1-5).
-unknown_dc_log_path = "unknown-dc.txt"
-
-# Verbosity: "debug" | "verbose" | "normal" | "silent"
-log_level = "normal"
-
-# Disable ANSI color codes in log output (useful for file logging).
-disable_colors = false
-
-# ------------------------------------------------------------------------------
-# FakeTLS Record Sizing
-# Buffer small MTProto packets into larger TLS records to mimic real HTTPS.
-# Real HTTPS servers send records close to MTU size (~1400 bytes).
-# A stream of tiny TLS records is a strong DPI signal.
-# Set to 0 to disable. Set to 1400 for realistic HTTPS emulation.
-# ------------------------------------------------------------------------------
-
-fast_mode_min_tls_record = 1400
-
-# ------------------------------------------------------------------------------
-# Periodic Updates
-# ------------------------------------------------------------------------------
-
-# How often (seconds) to re-fetch ME server lists and proxy secrets
-# from core.telegram.org. Keeps your proxy in sync with Telegram infrastructure.
-update_every = 300
-
-# How often (seconds) to force a Hardswap even if the ME map is unchanged.
-# Shorter intervals mean shorter-lived TCP flows, harder for DPI to profile.
-me_reinit_every_secs = 600
-
-# ------------------------------------------------------------------------------
-# Hardswap Warmup Tuning
-# Fine-grained control over how the new pool is warmed up before traffic switch.
-# ------------------------------------------------------------------------------
-
-me_hardswap_warmup_delay_min_ms = 1000
-me_hardswap_warmup_delay_max_ms = 2000
-me_hardswap_warmup_extra_passes = 3
-me_hardswap_warmup_pass_backoff_base_ms = 500
-
-# ------------------------------------------------------------------------------
-# Config Update Debouncing
-# Telegram sometimes pushes transient/broken configs. Debouncing requires
-# N consecutive identical fetches before applying a change.
-# ------------------------------------------------------------------------------
-
-# ME server list must be identical for this many fetches before applying.
-me_config_stable_snapshots = 2
-
-# Minimum seconds between config applications.
-me_config_apply_cooldown_secs = 300
-
-# Proxy secret must be identical for this many fetches before applying.
-proxy_secret_stable_snapshots = 2
-
-# ------------------------------------------------------------------------------
-# Proxy Secret Rotation
-# ------------------------------------------------------------------------------
-
-# Apply newly downloaded secrets at runtime without restart.
-proxy_secret_rotate_runtime = true
-
-# Maximum acceptable secret length (bytes). Rejects abnormally large secrets.
-proxy_secret_len_max = 256
-
-# ------------------------------------------------------------------------------
-# Hardswap Drain Settings
-# Controls graceful shutdown of old ME connections during pool rotation.
-# ------------------------------------------------------------------------------
-
-# Seconds to keep old connections alive for in-flight data before force-closing.
-me_pool_drain_ttl_secs = 90
-
-# Minimum ratio of healthy connections in new pool before draining old pool.
-# 0.8 = at least 80% of new pool must be ready.
-me_pool_min_fresh_ratio = 0.8
-
-# Maximum seconds to wait for drain to complete before force-killing.
-me_reinit_drain_timeout_secs = 120
-
-# ------------------------------------------------------------------------------
-# NTP Clock Check
-# MTProto uses timestamps. Clock drift > 30 seconds breaks handshakes.
-# Telemt checks on startup and warns if out of sync.
-# ------------------------------------------------------------------------------
-
-ntp_check = true
-ntp_servers = ["pool.ntp.org"]
-
-# ------------------------------------------------------------------------------
-# Auto-Degradation
-# If ME servers become completely unreachable (ISP blocking),
-# automatically fall back to Direct Mode so users stay connected.
-# ------------------------------------------------------------------------------
-
-auto_degradation_enabled = true
-
-# Number of DC groups that must be unreachable before triggering fallback.
-degradation_min_unavailable_dc_groups = 2
-
-
-# ==============================================================================
-# ALLOWED CLIENT PROTOCOLS
-# Only enable what you need. In censored regions, TLS-only is safest.
-# ==============================================================================
-
-[general.modes]
-
-# Classic MTProto. Unobfuscated length prefixes. Trivially detected by DPI.
-# No reason to enable unless you have ancient clients.
-classic = false
-
-# Obfuscated MTProto with randomized padding. Better than classic, but
-# still detectable by statistical analysis of packet sizes.
-secure = false
-
-# FakeTLS (ee-secrets). Wraps MTProto in TLS 1.3 framing.
-# To DPI, it looks like a normal HTTPS connection.
-# This should be the ONLY enabled mode in censored environments.
-tls = true
-
-
-# ==============================================================================
-# STARTUP LINK GENERATION
-# Controls what tg:// invite links are printed to console on startup.
-# ==============================================================================
-
-[general.links]
-
-# Which users to generate links for.
-# "*" = all users, or an array like ["alice", "bob"].
-show = "*"
-
-# IP or domain to embed in the tg:// link.
-# If omitted, Telemt uses STUN to auto-detect.
-# Set this to your server's public IP or domain for reliable links.
-# public_host = "proxy.example.com"
-
-# Port to embed in the tg:// link.
-# If omitted, uses [server].port.
-# public_port = 443
-
-
-# ==============================================================================
-# NETWORK & IP RESOLUTION
-# ==============================================================================
-
-[network]
-
-# Enable IPv4 for outbound connections to Telegram.
-ipv4 = true
-
-# Enable IPv6 for outbound connections to Telegram.
-ipv6 = false
-
-# Prefer IPv4 (4) or IPv6 (6) when both are available.
-prefer = 4
-
-# Experimental: use both IPv4 and IPv6 ME servers simultaneously.
-# May improve reliability but doubles connection count.
-multipath = false
-
-# STUN servers for external IP discovery.
-# Used for Middle-Proxy KDF (if nat_probe=true) and link generation.
-stun_servers = [
-    "stun.l.google.com:5349",
-    "stun1.l.google.com:3478",
-    "stun.gmx.net:3478",
-    "stun.l.google.com:19302"
-]
-
-# If UDP STUN is blocked, attempt TCP-based STUN as fallback.
-stun_tcp_fallback = true
-
-# If all STUN fails, use HTTP APIs to discover public IP.
-http_ip_detect_urls = [
-    "https://ifconfig.me/ip",
-    "https://api.ipify.org"
-]
-
-# Cache discovered public IP to this file to survive restarts.
-cache_public_ip_path = "cache/public_ip.txt"
-
-
-# ==============================================================================
-# SERVER BINDING & METRICS
-# ==============================================================================
-
-[server]
-
-# TCP port to listen on.
-# 443 is recommended (looks like normal HTTPS traffic).
-port = 443
-
-# IPv4 bind address. "0.0.0.0" = all interfaces.
-listen_addr_ipv4 = "0.0.0.0"
-
-# IPv6 bind address. "::" = all interfaces.
-listen_addr_ipv6 = "::"
-
-# Unix socket listener (for reverse proxy setups with Nginx/HAProxy).
-# listen_unix_sock = "/var/run/telemt.sock"
-# listen_unix_sock_perm = "0660"
-
-# Enable PROXY protocol header parsing.
-# Set true ONLY if Telemt is behind HAProxy/Nginx that injects PROXY headers.
-# If enabled without a proxy in front, clients will fail to connect.
-proxy_protocol = false
-
-# Prometheus metrics HTTP endpoint port.
-# Uncomment to enable. Access at http://your-server:9090/metrics
-# metrics_port = 9090
-
-# IP ranges allowed to access the metrics endpoint.
-metrics_whitelist = [
-    "127.0.0.1/32",
-    "::1/128"
-]
-
-# ------------------------------------------------------------------------------
-# Listener Overrides
-# Define explicit listeners with specific bind IPs and announce IPs.
-# The announce IP is what gets embedded in tg:// links and sent to ME servers.
-# You MUST set announce to your server's public IP for ME mode to work.
-# ------------------------------------------------------------------------------
-
-# [[server.listeners]]
-# ip = "0.0.0.0"
-# announce = "203.0.113.10"
-# reuse_allow = false
-
-
-# ==============================================================================
-# TIMEOUTS (seconds unless noted)
-# ==============================================================================
-
-[timeouts]
-
-# Maximum time for client to complete FakeTLS + MTProto handshake.
-client_handshake = 15
-
-# Maximum time to establish TCP connection to upstream Telegram DC.
-tg_connect = 10
-
-# TCP keepalive interval for client connections.
-client_keepalive = 60
-
-# Maximum client inactivity before dropping the connection.
-client_ack = 300
-
-# Instant retry count for a single ME endpoint before giving up on it.
-me_one_retry = 3
-
-# Timeout (milliseconds) for a single ME endpoint connection attempt.
-me_one_timeout_ms = 1500
-
-
-# ==============================================================================
-# ANTI-CENSORSHIP / FAKETLS / MASKING
-# This is where Telemt becomes invisible to Deep Packet Inspection.
-# ==============================================================================
-
-[censorship]
-
-# ------------------------------------------------------------------------------
-# TLS Domain Fronting
-# The SNI (Server Name Indication) your proxy presents to connecting clients.
-# Must be a popular, unblocked HTTPS website in your target country.
-# DPI sees traffic to this domain. Choose carefully.
-# Good choices: major CDNs, banks, government sites, search engines.
-# Bad choices: obscure sites, already-blocked domains.
-# ------------------------------------------------------------------------------
-
-tls_domain = "www.google.com"
-
-# ------------------------------------------------------------------------------
-# Active Probe Masking
-# When someone connects but fails the MTProto handshake (wrong secret),
-# they might be an ISP active prober testing if this is a proxy.
-#
-# mask = false: drop the connection (prober knows something is here)
-# mask = true:  transparently proxy them to mask_host (prober sees a real website)
-#
-# With mask enabled, your server is indistinguishable from a real web server
-# to anyone who doesn't have the correct secret.
-# ------------------------------------------------------------------------------
-
-mask = true
-
-# The real web server to forward failed handshakes to.
-# If omitted, defaults to tls_domain.
-# mask_host = "www.google.com"
-
-# Port on the mask host to connect to.
-mask_port = 443
-
-# Inject PROXY protocol header when forwarding to mask host.
-# 0 = disabled, 1 = v1, 2 = v2. Leave disabled unless mask_host expects it.
-# mask_proxy_protocol = 0
-
-# ------------------------------------------------------------------------------
-# TLS Certificate Emulation
-# ------------------------------------------------------------------------------
-
-# Size (bytes) of the locally generated fake TLS certificate.
-# Only used when tls_emulation is disabled.
-fake_cert_len = 2048
-
-# KILLER FEATURE: Real-Time TLS Emulation.
-# Telemt connects to tls_domain, fetches its actual TLS 1.3 certificate chain,
-# and exactly replicates the byte sizes of ServerHello and Certificate records.
-# Defeats DPI that uses TLS record length heuristics to detect proxies.
-# Strongly recommended in censored environments.
-tls_emulation = true
-
-# Directory to cache fetched TLS certificates.
-tls_front_dir = "tlsfront"
-
-# ------------------------------------------------------------------------------
-# ServerHello Timing
-# Real web servers take 30-150ms to respond to ClientHello due to network
-# latency and crypto processing. A proxy responding in <1ms is suspicious.
-# These settings add realistic delay to mimic genuine server behavior.
-# ------------------------------------------------------------------------------
-
-# Minimum delay before sending ServerHello (milliseconds).
-server_hello_delay_min_ms = 50
-
-# Maximum delay before sending ServerHello (milliseconds).
-server_hello_delay_max_ms = 150
-
-# ------------------------------------------------------------------------------
-# TLS Session Tickets
-# Real TLS 1.3 servers send 1-2 NewSessionTicket messages after handshake.
-# A server that sends zero tickets is anomalous and may trigger DPI flags.
-# Set this to match your tls_domain's behavior (usually 2).
-# ------------------------------------------------------------------------------
-
-# tls_new_session_tickets = 0
-
-# ------------------------------------------------------------------------------
-# Full Certificate Frequency
-# When tls_emulation is enabled, this controls how often (per client IP)
-# to send the complete emulated certificate chain.
-#
-# > 0: Subsequent connections within TTL seconds get a smaller cached version.
-#       Saves bandwidth but creates a detectable size difference between
-#       first and repeat connections.
-#
-# = 0: Every connection gets the full certificate. More bandwidth but
-#       perfectly consistent behavior, no anomalies for DPI to detect.
-# ------------------------------------------------------------------------------
-
-tls_full_cert_ttl_secs = 0
-
-# ------------------------------------------------------------------------------
-# ALPN Enforcement
-# Ensure ServerHello responds with the exact ALPN protocol the client requested.
-# Mismatched ALPN (e.g., client asks h2, server says http/1.1) is a DPI red flag.
-# ------------------------------------------------------------------------------
-
-alpn_enforce = true
-
-
-# ==============================================================================
-# ACCESS CONTROL & USERS
-# ==============================================================================
-
-[access]
-
-# ------------------------------------------------------------------------------
-# Replay Attack Protection
-# DPI can record a legitimate user's handshake and replay it later to probe
-# whether the server is a proxy. Telemt remembers recent handshake nonces
-# and rejects duplicates.
-# ------------------------------------------------------------------------------
-
-# Number of nonce slots in the replay detection buffer.
-replay_check_len = 65536
-
-# How long (seconds) to remember nonces before expiring them.
-replay_window_secs = 1800
-
-# Allow clients with incorrect system clocks to connect.
-# false = reject clients with significant time skew (more secure)
-# true  = accept anyone regardless of clock (more permissive)
-ignore_time_skew = false
-
-# ------------------------------------------------------------------------------
-# User Secrets
-# Each user needs a unique 32-character hex string as their secret.
-# Generate with: openssl rand -hex 16
-#
-# This secret is embedded in the tg:// link. Anyone with it can connect.
-# Format: username = "hex_secret"
-# ------------------------------------------------------------------------------
-
-[access.users]
-# alice = "0123456789abcdef0123456789abcdef"
-# bob = "fedcba9876543210fedcba9876543210"
-
-# ------------------------------------------------------------------------------
-# Per-User Connection Limits
-# Limits concurrent TCP connections per user to prevent secret sharing.
-# Uncomment and set for each user as needed.
-# ------------------------------------------------------------------------------
-
-[access.user_max_tcp_conns]
-# alice = 100
-# bob = 50
-
-# ------------------------------------------------------------------------------
-# Per-User Expiration Dates
-# Automatically revoke access after the specified date (ISO 8601 format).
-# ------------------------------------------------------------------------------
-
-[access.user_expirations]
-# alice = "2025-12-31T23:59:59Z"
-# bob = "2026-06-15T00:00:00Z"
-
-# ------------------------------------------------------------------------------
-# Per-User Data Quotas
-# Maximum total bytes transferred per user. Connection refused after limit.
-# ------------------------------------------------------------------------------
-
-[access.user_data_quota]
-# alice = 107374182400
-# bob = 53687091200
-
-# ------------------------------------------------------------------------------
-# Per-User Unique IP Limits
-# Maximum number of different IP addresses that can use this secret
-# at the same time. Highly effective against secret leaking/sharing.
-# Set to 1 for single-device, 2-3 for phone+desktop, etc.
-# ------------------------------------------------------------------------------
-
-[access.user_max_unique_ips]
-# alice = 3
-# bob = 2
-
-
-# ==============================================================================
-# UPSTREAM ROUTING
-# Controls how Telemt connects to Telegram servers (or ME servers).
-# If omitted entirely, uses the OS default route.
-# ==============================================================================
-
-# ------------------------------------------------------------------------------
-# Direct upstream: use the server's own network interface.
-# You can optionally bind to a specific interface or local IP.
-# ------------------------------------------------------------------------------
-
-# [[upstreams]]
-# type = "direct"
-# interface = "eth0"
-# bind_addresses = ["192.0.2.10"]
-# weight = 1
-# enabled = true
-# scopes = "*"
-
-# ------------------------------------------------------------------------------
-# SOCKS5 upstream: route Telegram traffic through a SOCKS5 proxy.
-# Useful if your server's IP is blocked from reaching Telegram DCs.
-# ------------------------------------------------------------------------------
-
-# [[upstreams]]
-# type = "socks5"
-# address = "198.51.100.30:1080"
-# username = "proxy-user"
-# password = "proxy-pass"
-# weight = 1
-# enabled = true
-
-
-# ==============================================================================
-# DATACENTER OVERRIDES
-# Force specific DC IDs to route to specific IP:Port combinations.
-# DC 203 (CDN) is auto-injected by Telemt if not specified here.
-# ==============================================================================
-
-# [dc_overrides]
-# "201" = "149.154.175.50:443"
-# "202" = ["149.154.167.51:443", "149.154.175.100:443"]

config.toml

@@ -4,7 +4,7 @@
 
 # === General Settings ===
 [general]
-use_middle_proxy = false
+use_middle_proxy = true
 # Global ad_tag fallback when user has no per-user tag in [access.user_ad_tags]
 # ad_tag = "00000000000000000000000000000000"
 # Per-user ad_tag in [access.user_ad_tags] (32 hex from @MTProxybot)
@@ -34,6 +34,13 @@ port = 443
 # metrics_port = 9090
 # metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
 
+[server.api]
+enabled = true
+listen = "0.0.0.0:9091"
+whitelist = ["127.0.0.0/8"]
+minimal_runtime_enabled = false
+minimal_runtime_cache_ttl_ms = 1000
+
 # Listen on multiple interfaces/IPs - IPv4
 [[server.listeners]]
 ip = "0.0.0.0"

contrib/openbsd/telemt.rcd

@@ -0,0 +1,16 @@
+#!/bin/ksh
+# /etc/rc.d/telemt
+#
+# rc.d(8) script for Telemt MTProxy daemon.
+# Tokio runtime does not daemonize itself, so rc_bg=YES is used.
+
+daemon="/usr/local/bin/telemt"
+daemon_user="_telemt"
+daemon_flags="/etc/telemt/config.toml"
+
+. /etc/rc.d/rc.subr
+
+rc_bg=YES
+rc_reload=NO
+
+rc_cmd $1

contrib/systemd/system-user-telemt.conf

@@ -0,0 +1,3 @@
+u telemt - "telemt user" /var/lib/telemt -
+g telemt - -
+m telemt telemt

contrib/systemd/telemt.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=Telemt
+Wants=network-online.target
+After=multi-user.target network.target network-online.target
+
+[Service]
+Type=simple
+User=telemt
+Group=telemt
+WorkingDirectory=/var/lib/telemt
+ExecStart=/usr/bin/telemt /etc/telemt/telemt.toml
+Restart=on-failure
+RestartSec=10
+LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
+
+
+[Install]
+WantedBy=multi-user.target

contrib/systemd/tmpfiles-telemt.conf

@@ -0,0 +1 @@
+d /var/lib/telemt 700 telemt telemt

docker-compose.yml

@@ -6,7 +6,7 @@ services:
     restart: unless-stopped
     ports:
       - "443:443"
-      - "9090:9090"
+      - "127.0.0.1:9090:9090"
     # Allow caching 'proxy-secret' in read-only container
     working_dir: /run/telemt
     volumes:

docs/FAQ.en.md

@@ -0,0 +1,122 @@
+## How to set up "proxy sponsor" channel and statistics via @MTProxybot bot
+
+1. Go to @MTProxybot bot.
+2. Enter the command `/newproxy`
+3. Send the server IP and port. For example: 1.2.3.4:443
+4. Open the config `nano /etc/telemt.toml`.
+5. Copy and send the user secret from the [access.users] section to the bot.
+6. Copy the tag received from the bot. For example 1234567890abcdef1234567890abcdef.
+> [!WARNING]
+> The link provided by the bot will not work. Do not copy or use it!
+7. Uncomment the ad_tag parameter and enter the tag received from the bot.
+8. Uncomment/add the parameter `use_middle_proxy = true`.
+
+Config example:
+```toml
+[general]
+ad_tag = "1234567890abcdef1234567890abcdef"
+use_middle_proxy = true
+```
+9. Save the config. Ctrl+S -> Ctrl+X.
+10. Restart telemt `systemctl restart telemt`.
+11. In the bot, send the command /myproxies and select the added server.
+12. Click the "Set promotion" button.
+13. Send a **public link** to the channel. Private channels cannot be added!
+14. Wait approximately 1 hour for the information to update on Telegram servers.
+> [!WARNING]
+> You will not see the "proxy sponsor" if you are already subscribed to the channel.
+
+**You can also set up different channels for different users.**
+```toml
+[access.user_ad_tags]
+hello = "ad_tag"
+hello2 = "ad_tag2"
+```
+
+## How many people can use 1 link
+
+By default, 1 link can be used by any number of people.  
+You can limit the number of IPs using the proxy.
+```toml
+[access.user_max_unique_ips]
+hello = 1
+```
+This parameter limits how many unique IPs can use 1 link simultaneously. If one user disconnects, a second user can connect. Also, multiple users can sit behind the same IP.
+
+## How to create multiple different links
+
+1. Generate the required number of secrets `openssl rand -hex 16`
+2. Open the config `nano /etc/telemt.toml`
+3. Add new users.
+```toml
+[access.users]
+user1 = "00000000000000000000000000000001"
+user2 = "00000000000000000000000000000002"
+user3 = "00000000000000000000000000000003"
+```
+4. Save the config. Ctrl+S -> Ctrl+X. You don't need to restart telemt.
+5. Get the links via
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
+
+## How to view metrics
+
+1. Open the config `nano /etc/telemt.toml`
+2. Add the following parameters
+```toml
+[server]
+metrics_port = 9090
+metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
+```
+3. Save the config. Ctrl+S -> Ctrl+X.
+4. Metrics are available at SERVER_IP:9090/metrics.
+> [!WARNING]
+> "0.0.0.0/0" in metrics_whitelist opens access from any IP. Replace with your own IP. For example "1.2.3.4"
+
+## Additional parameters
+
+### Domain in link instead of IP
+To specify a domain in the links, add to the `[general.links]` section of the config file.
+```toml
+[general.links]
+public_host = "proxy.example.com"
+```
+
+### Server connection limit
+Limits the total number of open connections to the server:
+```toml
+[server]
+max_connections = 10000    # 0 - unlimited, 10000 - default
+```
+
+### Upstream Manager
+To specify an upstream, add to the `[[upstreams]]` section of the config.toml file:
+#### Binding to IP
+```toml
+[[upstreams]]
+type = "direct"
+weight = 1
+enabled = true
+interface = "192.168.1.100" # Change to your outgoing IP
+```
+#### SOCKS4/5 as Upstream
+- Without authentication:
+```toml
+[[upstreams]]
+type = "socks5"            # Specify SOCKS4 or SOCKS5
+address = "1.2.3.4:1234"   # SOCKS-server Address
+weight = 1                 # Set Weight for Scenarios
+enabled = true
+```
+
+- With authentication:
+```toml
+[[upstreams]]
+type = "socks5"            # Specify SOCKS4 or SOCKS5
+address = "1.2.3.4:1234"   # SOCKS-server Address
+username = "user"          # Username for Auth on SOCKS-server
+password = "pass"          # Password for Auth on SOCKS-server
+weight = 1                 # Set Weight for Scenarios
+enabled = true
+```

docs/FAQ.ru.md

@@ -1,4 +1,4 @@
-## Как настроить канал "спонсор прокси"
+## Как настроить канал "спонсор прокси" и статистику через бота @MTProxybot
 
 1. Зайти в бота @MTProxybot.
 2. Ввести команду `/newproxy`
@@ -6,6 +6,8 @@
 4. Открыть конфиг `nano /etc/telemt.toml`.
 5. Скопировать и отправить боту секрет пользователя из раздела [access.users].
 6. Скопировать полученный tag у бота. Например 1234567890abcdef1234567890abcdef.
+> [!WARNING]
+> Ссылка, которую выдает бот, не будет работать. Не копируйте и не используйте её!
 7. Раскомментировать параметр ad_tag и вписать tag, полученный у бота.
 8. Раскомментировать/добавить параметр use_middle_proxy = true.
 
@@ -24,6 +26,13 @@ use_middle_proxy = true
 > [!WARNING]
 > У вас не будет отображаться "спонсор прокси" если вы уже подписаны на канал.
 
+**Также вы можете настроить разные каналы для разных пользователей.**
+```toml
+[access.user_ad_tags]
+hello = "ad_tag"
+hello2 = "ad_tag2"
+```
+
 ## Сколько человек может пользоваться 1 ссылкой
 
 По умолчанию 1 ссылкой может пользоваться сколько угодно человек.  
@@ -46,7 +55,10 @@ user2 = "00000000000000000000000000000002"
 user3 = "00000000000000000000000000000003"
 ```
 4. Сохранить конфиг. Ctrl+S -> Ctrl+X. Перезапускать telemt не нужно.
-5. Получить ссылки через `journalctl -u telemt -n -g "links" --no-pager -o cat | tac`
+5. Получить ссылки через
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
 
 ## Как посмотреть метрики
 
@@ -62,3 +74,50 @@ metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
 > [!WARNING]
 > "0.0.0.0/0" в metrics_whitelist открывает доступ с любого IP. Замените на свой ip. Например "1.2.3.4"
 
+## Дополнительные параметры
+
+### Домен в ссылке вместо IP
+Чтобы указать домен в ссылках, добавьте в секцию `[general.links]` файла config.
+```toml
+[general.links]
+public_host = "proxy.example.com"
+```
+
+### Общий лимит подключений к серверу
+Ограничивает общее число открытых подключений к серверу:
+```toml
+[server]
+max_connections = 10000    # 0 - unlimited, 10000 - default
+```
+
+### Upstream Manager
+Чтобы указать апстрим, добавьте в секцию `[[upstreams]]` файла config.toml:
+#### Привязка к IP
+```toml
+[[upstreams]]
+type = "direct"
+weight = 1
+enabled = true
+interface = "192.168.1.100" # Change to your outgoing IP
+```
+#### SOCKS4/5 как Upstream
+- Без авторизации:
+```toml
+[[upstreams]]
+type = "socks5"            # Specify SOCKS4 or SOCKS5
+address = "1.2.3.4:1234"   # SOCKS-server Address
+weight = 1                 # Set Weight for Scenarios
+enabled = true
+```
+
+- С авторизацией:
+```toml
+[[upstreams]]
+type = "socks5"            # Specify SOCKS4 or SOCKS5
+address = "1.2.3.4:1234"   # SOCKS-server Address
+username = "user"          # Username for Auth on SOCKS-server
+password = "pass"          # Password for Auth on SOCKS-server
+weight = 1                 # Set Weight for Scenarios
+enabled = true
+```
+

docs/LICENSE/LICENSE.de.md

@@ -0,0 +1,92 @@
+# Öffentliche TELEMT-Lizenz 3
+
+***Alle Rechte vorbehalten (c) 2026 Telemt***
+
+Hiermit wird jeder Person, die eine Kopie dieser Software und der dazugehörigen Dokumentation (nachfolgend "Software") erhält, unentgeltlich die Erlaubnis erteilt, die Software ohne Einschränkungen zu nutzen, einschließlich des Rechts, die Software zu verwenden, zu vervielfältigen, zu ändern, abgeleitete Werke zu erstellen, zu verbinden, zu veröffentlichen, zu verbreiten, zu unterlizenzieren und/oder Kopien der Software zu verkaufen sowie diese Rechte auch denjenigen einzuräumen, denen die Software zur Verfügung gestellt wird, vorausgesetzt, dass sämtliche Urheberrechtshinweise sowie die Bedingungen und Bestimmungen dieser Lizenz eingehalten werden.
+
+### Begriffsbestimmungen
+
+Für die Zwecke dieser Lizenz gelten die folgenden Definitionen:
+
+**"Software" (Software)** — die Telemt-Software einschließlich Quellcode, Dokumentation und sämtlicher zugehöriger Dateien, die unter den Bedingungen dieser Lizenz verbreitet werden.
+
+**"Contributor" (Contributor)** — jede natürliche oder juristische Person, die Code, Patches, Dokumentation oder andere Materialien eingereicht hat, die von den Maintainers des Projekts angenommen und in die Software aufgenommen wurden.
+
+**"Beitrag" (Contribution)** — jedes urheberrechtlich geschützte Werk, das bewusst zur Aufnahme in die Software eingereicht wurde.
+
+**"Modifizierte Version" (Modified Version)** — jede Version der Software, die gegenüber der ursprünglichen Software geändert, angepasst, erweitert oder anderweitig modifiziert wurde.
+
+**"Maintainers" (Maintainers)** — natürliche oder juristische Personen, die für das offizielle Telemt-Projekt und dessen offizielle Veröffentlichungen verantwortlich sind.
+
+### 1 Urheberrechtshinweis (Attribution)
+
+Bei der Weitergabe der Software, sowohl in Form des Quellcodes als auch in binärer Form, MÜSSEN folgende Elemente erhalten bleiben:
+
+- der oben genannte Urheberrechtshinweis;
+- der vollständige Text dieser Lizenz;
+- sämtliche bestehenden Hinweise auf Urheberschaft.
+
+### 2 Hinweis auf Modifikationen
+
+Wenn Änderungen an der Software vorgenommen werden, MUSS die Person, die diese Änderungen vorgenommen hat, eindeutig darauf hinweisen, dass die Software modifiziert wurde, und eine kurze Beschreibung der vorgenommenen Änderungen beifügen.
+
+Modifizierte Versionen der Software DÜRFEN NICHT als die originale Version von Telemt dargestellt werden.
+
+### 3 Marken und Bezeichnungen
+
+Diese Lizenz GEWÄHRT KEINE Rechte zur Nutzung der Bezeichnung **"Telemt"**, des Telemt-Logos oder sonstiger Marken, Kennzeichen oder Branding-Elemente von Telemt.
+
+Weiterverbreitete oder modifizierte Versionen der Software DÜRFEN die Bezeichnung Telemt nicht in einer Weise verwenden, die bei Nutzern den Eindruck eines offiziellen Ursprungs oder einer Billigung durch das Telemt-Projekt erwecken könnte, sofern hierfür keine ausdrückliche Genehmigung der Maintainers vorliegt.
+
+Die Verwendung der Bezeichnung **Telemt** zur Beschreibung einer modifizierten Version der Software ist nur zulässig, wenn diese Version eindeutig als modifiziert oder inoffiziell gekennzeichnet ist.
+
+Jegliche Verbreitung, die Nutzer vernünftigerweise darüber täuschen könnte, dass es sich um eine offizielle Veröffentlichung von Telemt handelt, ist untersagt.
+
+### 4 Transparenz bei der Verbreitung von Binärversionen
+
+Im Falle der Verbreitung kompilierter Binärversionen der Software wird der Verbreiter HIERMIT ERMUTIGT (encouraged), soweit dies vernünftigerweise möglich ist, Zugang zum entsprechenden Quellcode sowie zu den Build-Anweisungen bereitzustellen.
+
+Diese Praxis trägt zur Transparenz bei und ermöglicht es Empfängern, die Integrität und Reproduzierbarkeit der verbreiteten Builds zu überprüfen.
+
+## 5 Gewährung einer Patentlizenz und Beendigung von Rechten
+
+Jeder Contributor gewährt den Empfängern der Software eine unbefristete, weltweite, nicht-exklusive, unentgeltliche, lizenzgebührenfreie und unwiderrufliche Patentlizenz für:
+
+- die Herstellung,
+- die Beauftragung der Herstellung,
+- die Nutzung,
+- das Anbieten zum Verkauf,
+- den Verkauf,
+- den Import,
+- sowie jede sonstige Verbreitung der Software.
+
+Diese Patentlizenz erstreckt sich ausschließlich auf solche Patentansprüche, die notwendigerweise durch den jeweiligen Beitrag des Contributors allein oder in Kombination mit der Software verletzt würden.
+
+Leitet eine Person ein Patentverfahren ein oder beteiligt sich daran, einschließlich Gegenklagen oder Kreuzklagen, mit der Behauptung, dass die Software oder ein darin enthaltener Beitrag ein Patent verletzt, **erlöschen sämtliche durch diese Lizenz gewährten Rechte für diese Person unmittelbar mit Einreichung der Klage**.
+
+Darüber hinaus erlöschen alle durch diese Lizenz gewährten Rechte **automatisch**, wenn eine Person ein gerichtliches Verfahren einleitet, in dem behauptet wird, dass die Software selbst ein Patent oder andere Rechte des geistigen Eigentums verletzt.
+
+### 6 Beteiligung und Beiträge zur Entwicklung
+
+Sofern ein Contributor nicht ausdrücklich etwas anderes erklärt, gilt jeder Beitrag, der bewusst zur Aufnahme in die Software eingereicht wird, als unter den Bedingungen dieser Lizenz lizenziert.
+
+Durch die Einreichung eines Beitrags gewährt der Contributor den Maintainers des Telemt-Projekts sowie allen Empfängern der Software die in dieser Lizenz beschriebenen Rechte in Bezug auf diesen Beitrag.
+
+### 7 Urheberhinweis bei Netzwerk- und Servicenutzung
+
+Wird die Software zur Bereitstellung eines öffentlich zugänglichen Netzwerkdienstes verwendet, MUSS der Betreiber dieses Dienstes einen Hinweis auf die Urheberschaft von Telemt an mindestens einer der folgenden Stellen anbringen:
+
+* in der Servicedokumentation;
+* in der Dienstbeschreibung;
+* auf einer Seite "Über" oder einer vergleichbaren Informationsseite;
+* in anderen für Nutzer zugänglichen Materialien, die in angemessenem Zusammenhang mit dem Dienst stehen.
+
+Ein solcher Hinweis DARF NICHT den Eindruck erwecken, dass der Dienst vom Telemt-Projekt oder dessen Maintainers unterstützt oder offiziell gebilligt wird.
+
+### 8 Haftungsausschluss und salvatorische Klausel
+
+DIE SOFTWARE WIRD "WIE BESEHEN" BEREITGESTELLT, OHNE JEGLICHE AUSDRÜCKLICHE ODER STILLSCHWEIGENDE GEWÄHRLEISTUNG, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF GEWÄHRLEISTUNGEN DER MARKTGÄNGIGKEIT, DER EIGNUNG FÜR EINEN BESTIMMTEN ZWECK UND DER NICHTVERLETZUNG VON RECHTEN.
+
+IN KEINEM FALL HAFTEN DIE AUTOREN ODER RECHTEINHABER FÜR IRGENDWELCHE ANSPRÜCHE, SCHÄDEN ODER SONSTIGE HAFTUNG, DIE AUS VERTRAG, UNERLAUBTER HANDLUNG ODER AUF ANDERE WEISE AUS DER SOFTWARE ODER DER NUTZUNG DER SOFTWARE ENTSTEHEN.
+
+SOLLTE EINE BESTIMMUNG DIESER LIZENZ ALS UNWIRKSAM ODER NICHT DURCHSETZBAR ANGESEHEN WERDEN, IST DIESE BESTIMMUNG SO AUSZULEGEN, DASS SIE DEM URSPRÜNGLICHEN WILLEN DER PARTEIEN MÖGLICHST NAHEKOMMT; DIE ÜBRIGEN BESTIMMUNGEN BLEIBEN DAVON UNBERÜHRT UND IN VOLLER WIRKUNG.

docs/LICENSE/LICENSE.en.md

@@ -0,0 +1,143 @@
+###### TELEMT Public License 3 ######
+##### Copyright (c) 2026 Telemt #####
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this Software and associated documentation files (the "Software"),
+to use, reproduce, modify, prepare derivative works of, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, provided that all
+copyright notices, license terms, and conditions set forth in this License
+are preserved and complied with.
+
+### Official Translations
+
+The canonical version of this License is the English version.
+
+Official translations are provided for informational purposes only
+and for convenience, and do not have legal force. In case of any
+discrepancy, the English version of this License shall prevail.
+
+Available versions:
+- English in Markdown: docs/LICENSE/LICENSE.md
+- German: docs/LICENSE/LICENSE.de.md
+- Russian: docs/LICENSE/LICENSE.ru.md
+
+### Definitions
+
+For the purposes of this License:
+
+"Software" means the Telemt software, including source code, documentation,
+and any associated files distributed under this License.
+
+"Contributor" means any person or entity that submits code, patches,
+documentation, or other contributions to the Software that are accepted
+into the Software by the maintainers.
+
+"Contribution" means any work of authorship intentionally submitted
+to the Software for inclusion in the Software.
+
+"Modified Version" means any version of the Software that has been
+changed, adapted, extended, or otherwise modified from the original
+Software.
+
+"Maintainers" means the individuals or entities responsible for
+the official Telemt project and its releases.
+
+#### 1 Attribution
+
+Redistributions of the Software, in source or binary form, MUST RETAIN the
+above copyright notice, this license text, and any existing attribution
+notices.
+
+#### 2 Modification Notice
+
+If you modify the Software, you MUST clearly state that the Software has been
+modified and include a brief description of the changes made.
+
+Modified versions MUST NOT be presented as the original Telemt.
+
+#### 3 Trademark and Branding
+
+This license DOES NOT grant permission to use the name "Telemt", 
+the Telemt logo, or any Telemt trademarks or branding.
+
+Redistributed or modified versions of the Software MAY NOT use the Telemt
+name in a way that suggests endorsement or official origin without explicit
+permission from the Telemt maintainers.
+
+Use of the name "Telemt" to describe a modified version of the Software
+is permitted only if the modified version is clearly identified as a
+modified or unofficial version.
+
+Any distribution that could reasonably confuse users into believing that
+the software is an official Telemt release is prohibited.
+
+#### 4 Binary Distribution Transparency
+
+If you distribute compiled binaries of the Software,
+you are ENCOURAGED to provide access to the corresponding
+source code and build instructions where reasonably possible.
+
+This helps preserve transparency and allows recipients to verify the
+integrity and reproducibility of distributed builds.
+
+#### 5 Patent Grant and Defensive Termination Clause
+
+Each contributor grants you a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Software.
+
+This patent license applies only to those patent claims necessarily
+infringed by the contributor’s contribution alone or by combination of
+their contribution with the Software.
+
+If you initiate or participate in any patent litigation, including
+cross-claims or counterclaims, alleging that the Software or any
+contribution incorporated within the Software constitutes patent
+infringement, then **all rights granted to you under this license shall
+terminate immediately** as of the date such litigation is filed.
+
+Additionally, if you initiate legal action alleging that the
+Software itself infringes your patent or other intellectual
+property rights, then all rights granted to you under this
+license SHALL TERMINATE automatically.
+
+#### 6 Contributions
+
+Unless you explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Software shall be licensed under the terms
+of this License.
+
+By submitting a Contribution, you grant the Telemt maintainers and all
+recipients of the Software the rights described in this License with
+respect to that Contribution.
+
+#### 7 Network Use Attribution
+
+If the Software is used to provide a publicly accessible network service,
+the operator of such service MUST provide attribution to Telemt in at least
+one of the following locations:
+
+- service documentation
+- service description
+- an "About" or similar informational page
+- other user-visible materials reasonably associated with the service
+
+Such attribution MUST NOT imply endorsement by the Telemt project or its
+maintainers.
+
+#### 8 Disclaimer of Warranty and Severability Clause
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE
+
+IF ANY PROVISION OF THIS LICENSE IS HELD TO BE INVALID OR UNENFORCEABLE,
+SUCH PROVISION SHALL BE INTERPRETED TO REFLECT THE ORIGINAL INTENT
+OF THE PARTIES AS CLOSELY AS POSSIBLE, AND THE REMAINING PROVISIONS
+SHALL REMAIN IN FULL FORCE AND EFFECT

docs/LICENSE/LICENSE.ru.md

@@ -0,0 +1,90 @@
+# Публичная лицензия TELEMT 3
+
+***Все права защищёны (c) 2026 Telemt***
+
+Настоящим любому лицу, получившему копию данного программного обеспечения и сопутствующей документации (далее — "Программное обеспечение"), безвозмездно предоставляется разрешение использовать Программное обеспечение без ограничений, включая право использовать, воспроизводить, изменять, создавать производные произведения, объединять, публиковать, распространять, сублицензировать и (или) продавать копии Программного обеспечения, а также предоставлять такие права лицам, которым предоставляется Программное обеспечение, при условии соблюдения всех уведомлений об авторских правах, условий и положений настоящей Лицензии.
+
+### Определения
+
+Для целей настоящей Лицензии применяются следующие определения:
+
+**"Программное обеспечение" (Software)** — программное обеспечение Telemt, включая исходный код, документацию и любые связанные файлы, распространяемые на условиях настоящей Лицензии.
+
+**"Контрибьютор" (Contributor)** — любое физическое или юридическое лицо, направившее код, исправления (патчи), документацию или иные материалы, которые были приняты мейнтейнерами проекта и включены в состав Программного обеспечения.
+
+**"Вклад" (Contribution)** — любое произведение авторского права, намеренно представленное для включения в состав Программного обеспечения.
+
+**"Модифицированная версия" (Modified Version)** — любая версия Программного обеспечения, которая была изменена, адаптирована, расширена или иным образом модифицирована по сравнению с исходным Программным обеспечением.
+
+**"Мейнтейнеры" (Maintainers)** — физические или юридические лица, ответственные за официальный проект Telemt и его официальные релизы.
+
+### 1 Указание авторства
+
+При распространении Программного обеспечения, как в форме исходного кода, так и в бинарной форме, ДОЛЖНЫ СОХРАНЯТЬСЯ:
+
+- указанное выше уведомление об авторских правах;
+- текст настоящей Лицензии;
+- любые существующие уведомления об авторстве.
+
+### 2 Уведомление о модификации
+
+В случае внесения изменений в Программное обеспечение лицо, осуществившее такие изменения, ОБЯЗАНО явно указать, что Программное обеспечение было модифицировано, а также включить краткое описание внесённых изменений.
+
+Модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ представляться как оригинальная версия Telemt.
+
+### 3 Товарные знаки и обозначения
+
+Настоящая Лицензия НЕ ПРЕДОСТАВЛЯЕТ права использовать наименование **"Telemt"**, логотип Telemt, а также любые товарные знаки, фирменные обозначения или элементы бренда Telemt.
+
+Распространяемые или модифицированные версии Программного обеспечения НЕ ДОЛЖНЫ использовать наименование Telemt таким образом, который может создавать у пользователей впечатление официального происхождения либо одобрения со стороны проекта Telemt без явного разрешения мейнтейнеров проекта.
+
+Использование наименования **Telemt** для описания модифицированной версии Программного обеспечения допускается только при условии, что такая версия ясно обозначена как модифицированная или неофициальная.
+
+Запрещается любое распространение, которое может разумно вводить пользователей в заблуждение относительно того, что программное обеспечение является официальным релизом Telemt.
+
+### 4 Прозрачность распространения бинарных версий
+
+В случае распространения скомпилированных бинарных версий Программного обеспечения распространитель НАСТОЯЩИМ ПОБУЖДАЕТСЯ предоставлять доступ к соответствующему исходному коду и инструкциям по сборке, если это разумно возможно.
+
+Такая практика способствует прозрачности распространения и позволяет получателям проверять целостность и воспроизводимость распространяемых сборок.
+
+### 5 Предоставление патентной лицензии и прекращение прав
+
+Каждый контрибьютор предоставляет получателям Программного обеспечения бессрочную, всемирную, неисключительную, безвозмездную, не требующую выплаты роялти и безотзывную патентную лицензию на:
+
+- изготовление,
+- поручение изготовления,
+- использование,
+- предложение к продаже,
+- продажу,
+- импорт,
+- и иное распространение Программного обеспечения.
+
+Такая патентная лицензия распространяется исключительно на те патентные требования, которые неизбежно нарушаются соответствующим вкладом контрибьютора как таковым либо его сочетанием с Программным обеспечением.
+
+Если лицо инициирует либо участвует в каком-либо судебном разбирательстве по патентному спору, включая встречные или перекрёстные иски, утверждая, что Программное обеспечение либо любой вклад, включённый в него, нарушает патент, **все права, предоставленные такому лицу настоящей Лицензией, немедленно прекращаются** с даты подачи соответствующего иска.
+
+Кроме того, если лицо инициирует судебное разбирательство, утверждая, что само Программное обеспечение нарушает его патентные либо иные права интеллектуальной собственности, все права, предоставленные настоящей Лицензией, **автоматически прекращаются**.
+
+### 6 Участие и вклад в разработку
+
+Если контрибьютор явно не указал иное, любой Вклад, намеренно представленный для включения в Программное обеспечение, считается лицензированным на условиях настоящей Лицензии.
+Путём предоставления Вклада контрибьютор предоставляет мейнтейнером проекта Telemt и всем получателям Программного обеспечения права, предусмотренные настоящей Лицензией, в отношении такого Вклада.
+
+### 7 Указание авторства при сетевом и сервисном использовании
+
+В случае использования Программного обеспечения для предоставления публично доступного сетевого сервиса оператор такого сервиса ОБЯЗАН обеспечить указание авторства Telemt как минимум в одном из следующих мест:
+- документация сервиса;
+- описание сервиса;
+- страница "О программе" или аналогичная информационная страница;
+- иные материалы, доступные пользователям и разумно связанные с данным сервисом.
+
+Такое указание авторства НЕ ДОЛЖНО создавать впечатление одобрения или официальной поддержки со стороны проекта Telemt либо его мейнтейнеров.
+
+### 8 Отказ от гарантий и делимость положений
+
+ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ КОММЕРЧЕСКОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ.
+
+НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ТРЕБОВАНИЯМ, УБЫТКАМ ИЛИ ИНОЙ ОТВЕТСТВЕННОСТИ, ВОЗНИКАЮЩЕЙ В РЕЗУЛЬТАТЕ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ ОБРАЗОМ, СВЯЗАННЫМ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ЕГО ИСПОЛЬЗОВАНИЕМ.
+
+В СЛУЧАЕ ЕСЛИ КАКОЕ-ЛИБО ПОЛОЖЕНИЕ НАСТОЯЩЕЙ ЛИЦЕНЗИИ ПРИЗНАЁТСЯ НЕДЕЙСТВИТЕЛЬНЫМ ИЛИ НЕПРИМЕНИМЫМ, ТАКОЕ ПОЛОЖЕНИЕ ПОДЛЕЖИТ ТОЛКОВАНИЮ МАКСИМАЛЬНО БЛИЗКО К ИСХОДНОМУ НАМЕРЕНИЮ СТОРОН, ПРИ ЭТОМ ОСТАЛЬНЫЕ ПОЛОЖЕНИЯ СОХРАНЯЮТ ПОЛНУЮ ЮРИДИЧЕСКУЮ СИЛУ.

docs/OPENBSD.en.md

@@ -0,0 +1,132 @@
+# Telemt on OpenBSD (Build, Run, and rc.d)
+
+This guide covers a practical OpenBSD deployment flow for Telemt:
+- build from source,
+- install binary and config,
+- run as an rc.d daemon,
+- verify basic runtime behavior.
+
+## 1. Prerequisites
+
+Install required packages:
+
+```sh
+doas pkg_add rust git
+```
+
+Notes:
+- Telemt release installer (`install.sh`) is Linux-only.
+- On OpenBSD, use source build with `cargo`.
+
+## 2. Build from source
+
+```sh
+git clone https://github.com/telemt/telemt
+cd telemt
+cargo build --release
+./target/release/telemt --version
+```
+
+For low-RAM systems, this repository already uses `lto = "thin"` in release profile.
+
+## 3. Install binary and config
+
+```sh
+doas install -d -m 0755 /usr/local/bin
+doas install -m 0755 ./target/release/telemt /usr/local/bin/telemt
+
+doas install -d -m 0750 /etc/telemt
+doas install -m 0640 ./config.toml /etc/telemt/config.toml
+```
+
+## 4. Create runtime user
+
+```sh
+doas useradd -L daemon -s /sbin/nologin -d /var/empty _telemt
+```
+
+If `_telemt` already exists, continue.
+
+## 5. Install rc.d service
+
+Install the provided script:
+
+```sh
+doas install -m 0555 ./contrib/openbsd/telemt.rcd /etc/rc.d/telemt
+```
+
+Enable and start:
+
+```sh
+doas rcctl enable telemt
+# Optional: send daemon output to syslog
+#doas rcctl set telemt logger daemon.info
+
+doas rcctl start telemt
+```
+
+Service controls:
+
+```sh
+doas rcctl check telemt
+doas rcctl restart telemt
+doas rcctl stop telemt
+```
+
+## 6. Resource limits (recommended)
+
+OpenBSD rc.d can apply limits via login class. Add class `telemt` and assign it to `_telemt`.
+
+Example class entry:
+
+```text
+telemt:\
+    :openfiles-cur=8192:openfiles-max=16384:\
+    :datasize-cur=768M:datasize-max=1024M:\
+    :coredumpsize=0:\
+    :tc=daemon:
+```
+
+These values are conservative defaults for small and medium deployments.
+Increase `openfiles-*` only if logs show descriptor exhaustion under load.
+
+Then rebuild database and assign class:
+
+```sh
+doas cap_mkdb /etc/login.conf
+#doas usermod -L telemt _telemt
+```
+
+Uncomment `usermod` if you want this class bound to the Telemt user.
+
+## 7. Functional smoke test
+
+1. Validate service state:
+
+```sh
+doas rcctl check telemt
+```
+
+2. Check listener is present (replace 443 if needed):
+
+```sh
+netstat -n -f inet -p tcp | grep LISTEN | grep '\.443'
+```
+
+3. Verify process user:
+
+```sh
+ps -o user,pid,command -ax | grep telemt | grep -v grep
+```
+
+4. If startup fails, debug in foreground:
+
+```sh
+RUST_LOG=debug /usr/local/bin/telemt /etc/telemt/config.toml
+```
+
+## 8. OpenBSD-specific caveats
+
+- OpenBSD does not support per-socket keepalive retries/interval tuning in the same way as Linux.
+- Telemt source already uses target-aware cfg gates for keepalive setup.
+- Use rc.d/rcctl, not systemd.

docs/QUICK_START_GUIDE.en.md

@@ -48,11 +48,16 @@ Save the obtained result somewhere. You will need it later!
 
 ---
 
-**1. Place your config to /etc/telemt.toml**
+**1. Place your config to /etc/telemt/telemt.toml**
+
+Create config directory:
+```bash
+mkdir /etc/telemt
+```
 
 Open nano
 ```bash
-nano /etc/telemt.toml
+nano /etc/telemt/telemt.toml
 ```
 paste your config
 
@@ -60,12 +65,22 @@ paste your config
 # === General Settings ===
 [general]
 # ad_tag = "00000000000000000000000000000000"
+use_middle_proxy = false
 
 [general.modes]
 classic = false
 secure = false
 tls = true
 
+[server]
+port = 443
+
+[server.api]
+enabled = true
+# listen = "127.0.0.1:9091"
+# whitelist = ["127.0.0.1/32"]
+# read_only = true
+
 # === Anti-Censorship & Masking ===
 [censorship]
 tls_domain = "petrovich.ru"
@@ -74,6 +89,7 @@ tls_domain = "petrovich.ru"
 # format: "username" = "32_hex_chars_secret"
 hello = "00000000000000000000000000000000"
 ```
+
 then Ctrl+S -> Ctrl+X to save
 
 > [!WARNING]
@@ -82,7 +98,14 @@ then Ctrl+S -> Ctrl+X to save
 
 ---
 
-**2. Create service on /etc/systemd/system/telemt.service**
+**2. Create telemt user**
+
+```bash
+useradd -d /opt/telemt -m -r -U telemt
+chown -R telemt:telemt /etc/telemt
+```
+
+**3. Create service on /etc/systemd/system/telemt.service**
 
 Open nano
 ```bash
@@ -93,28 +116,43 @@ paste this Systemd Module
 ```bash
 [Unit]
 Description=Telemt
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=/bin
-ExecStart=/bin/telemt /etc/telemt.toml
+User=telemt
+Group=telemt
+WorkingDirectory=/opt/telemt
+ExecStart=/bin/telemt /etc/telemt/telemt.toml
 Restart=on-failure
 LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
 
 [Install]
 WantedBy=multi-user.target
 ```
 then Ctrl+S -> Ctrl+X to save
 
+reload systemd units
+```bash
+systemctl daemon-reload
+```
 
-**3.** To start it, enter the command `systemctl start telemt`
+**4.** To start it, enter the command `systemctl start telemt`
 
-**4.** To get status information, enter `systemctl status telemt`
+**5.** To get status information, enter `systemctl status telemt`
 
-**5.** For automatic startup at system boot, enter `systemctl enable telemt`
+**6.** For automatic startup at system boot, enter `systemctl enable telemt`
 
-**6.** To get the links, enter `journalctl -u telemt -n -g "links" --no-pager -o cat | tac`
+**7.** To get the link(s), enter
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
+
+> Any number of people can use one link.
 
 ---
 

docs/QUICK_START_GUIDE.ru.md

@@ -48,11 +48,16 @@ python3 -c 'import os; print(os.urandom(16).hex())'
 
 ---
 
-**1. Поместите свою конфигурацию в файл /etc/telemt.toml**
+**1. Поместите свою конфигурацию в файл /etc/telemt/telemt.toml**
+
+Создаём директорию для конфига:
+```bash
+mkdir /etc/telemt
+```
 
 Открываем nano
 ```bash
-nano /etc/telemt.toml
+nano /etc/telemt/telemt.toml
 ```
 Вставьте свою конфигурацию
 
@@ -60,12 +65,22 @@ nano /etc/telemt.toml
 # === General Settings ===
 [general]
 # ad_tag = "00000000000000000000000000000000"
+use_middle_proxy = false
 
 [general.modes]
 classic = false
 secure = false
 tls = true
 
+[server]
+port = 443
+
+[server.api]
+enabled = true
+# listen = "127.0.0.1:9091"
+# whitelist = ["127.0.0.1/32"]
+# read_only = true
+
 # === Anti-Censorship & Masking ===
 [censorship]
 tls_domain = "petrovich.ru"
@@ -74,6 +89,7 @@ tls_domain = "petrovich.ru"
 # format: "username" = "32_hex_chars_secret"
 hello = "00000000000000000000000000000000"
 ```
+
 Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
 
 > [!WARNING]
@@ -82,7 +98,14 @@ hello = "00000000000000000000000000000000"
 
 ---
 
-**2. Создайте службу в /etc/systemd/system/telemt.service**
+**2. Создайте пользователя для telemt**
+
+```bash
+useradd -d /opt/telemt -m -r -U telemt
+chown -R telemt:telemt /etc/telemt
+```
+
+**3. Создайте службу в /etc/systemd/system/telemt.service**
 
 Открываем nano
 ```bash
@@ -93,28 +116,45 @@ nano /etc/systemd/system/telemt.service
 ```bash
 [Unit]
 Description=Telemt
-After=network.target
+After=network-online.target
+Wants=network-online.target
 
 [Service]
 Type=simple
-WorkingDirectory=/bin
-ExecStart=/bin/telemt /etc/telemt.toml
+User=telemt
+Group=telemt
+WorkingDirectory=/opt/telemt
+ExecStart=/bin/telemt /etc/telemt/telemt.toml
 Restart=on-failure
 LimitNOFILE=65536
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+NoNewPrivileges=true
 
 [Install]
 WantedBy=multi-user.target
 ```
 Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
 
+перезагрузите конфигурацию systemd
+```bash
+systemctl daemon-reload
+```
 
-**3.** Для запуска введите команду `systemctl start telemt`
+**4.** Для запуска введите команду `systemctl start telemt`
 
-**4.** Для получения информации о статусе введите `systemctl status telemt`
+**5.** Для получения информации о статусе введите `systemctl status telemt`
 
-**5.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
+**6.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
 
-**6.** Для получения ссылки введите `journalctl -u telemt -n -g "links" --no-pager -o cat | tac`
+**7.** Для получения ссылки/ссылок введите 
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
+> Одной ссылкой может пользоваться сколько угодно человек.
+
+> [!WARNING]
+> Рабочую ссылку может выдать только команда из 7 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
 
 ---
 

docs/fronting-splitting/TLS-F-TCP-S.ru.md

@@ -0,0 +1,274 @@
+# TLS-F и TCP-S в Telemt
+
+## Общая архитектура
+
+**Telemt** - это прежде всего реализация **MTProxy**, через которую проходит payload Telegram
+
+Подсистема **TLS-Fronting / TCP-Splitting** служит **маскировочным транспортным слоем**, задача которого - сделать MTProxy-соединение внешне похожим на обычное TLS-подключение к легитимному сайту
+
+Таким образом:
+
+- **MTProxy** - основной функциональный слой Telemt для обработки Telegram-трафика
+- **TLS-Fronting / TCP-Splitting** - подсистема маскировки транспорта
+
+С точки зрения сети Telemt ведёт себя как **TLS-сервер**, но фактически:
+
+- валидные MTProxy-клиенты остаются внутри контура Telemt
+- любые другие TLS-клиенты проксируются на обычный HTTPS-сервер-заглушку
+
+# Базовый сценарий / Best-practice
+
+Предположим, у вас есть домен:
+
+```
+umweltschutz.de
+```
+
+### 1 DNS
+
+Вы создаёте A-запись:
+
+```
+umweltschutz.de -> A-запись 198.18.88.88
+```
+
+где `198.18.88.88` - IP вашего сервера с telemt
+
+### 2 TLS-домен
+
+В конфигурации Telemt:
+
+```
+tls_domain = umweltschutz.de
+```
+
+Этот домен используется клиентом как SNI в ClientHello
+
+### 3 Сервер-заглушка
+
+Вы поднимаете обычный HTTPS-сервер, например **nginx**, с сертификатом для этого домена.
+
+Он может работать:
+
+- на том же сервере
+- на другом сервере
+- на другом порту
+
+В конфигурации Telemt:
+
+```
+mask_host = 127.0.0.1
+mask_port = 8443
+```
+
+где `127.0.0.1` - IP сервера-заглушки, а 8443 - порт, который он слушает
+
+Этот сервер нужен **для обработки любых non-MTProxy запросов**
+
+### 4 Работа Telemt
+
+После запуска Telemt действует следующим образом:
+
+1) принимает входящее TCP-соединение
+2) анализирует TLS-ClientHello
+3) пытается определить, является ли соединение валидным **MTProxy FakeTLS**
+
+Далее работают два варианта логики:
+
+---
+
+# Сценарий 1 - MTProxy клиент с валидным ключом
+
+Если клиент предъявил **валидный MTProxy-ключ**:
+
+- соединение **остаётся внутри Telemt**
+- TLS используется только как **транспортная маскировка**
+- далее запускается обычная логика **MTProxy**
+
+Для внешнего наблюдателя это выглядит как:
+
+```
+TLS connection -> umweltschutz.de
+```
+
+Хотя внутри передаётся **MTProto-трафик Telegram**
+
+# Сценарий 2 - обычный TLS-клиент - crawler / scanner / browser
+
+Если Telemt не обнаруживает валидный MTProxy-ключ:
+
+соединение **переключается в режим TCP-Splitting / TCP-Splicing**.
+
+В этом режиме Telemt:
+
+1. открывает новое TCP-соединение к
+
+```
+mask_host:mask_port
+```
+
+2. начинает **проксировать TCP-трафик**
+
+Важно:
+
+* клиентский TLS-запрос **НЕ модифицируется**
+* **ClientHello передаётся "как есть", без изменений**
+* **SNI остаётся неизменным**
+* Telemt **не завершает TLS-рукопожатие**, а только перенаправляет его на более низком уровне сетевого стека - L4
+
+Таким образом upstream-сервер получает **оригинальное TLS-соединение клиента**:
+
+- если это nginx-заглушка, он просто отдаёт обычный сайт
+- для внешнего наблюдателя это выглядит как обычный HTTPS-сервер
+
+# TCP-S / TCP-Splitting / TCP-Splicing
+
+Ключевые свойства механизма:
+
+**Telemt работает как TCP-переключатель:**
+
+1) принимает соединение
+2️) определяет тип клиента
+3) либо:
+
+- обрабатывает MTProxy внутри
+- либо проксирует TCP-поток
+
+При проксировании:
+
+- Telemt **разрешает `mask_host` в IP**
+- устанавливает TCP-соединение
+- начинает **bidirectional TCP relay**
+
+При этом:
+
+- TLS-рукопожатие происходит **между клиентом и `mask_host`**
+- Telemt выступает только **на уровне L4 - как TCP-релей**, такой же как HAProxy в TCP-режиме
+
+# Использование чужого домена
+
+Можно использовать и внешний сайт.
+
+Например:
+
+```
+tls_domain = github.com
+mask_host = github.com
+mask_port = 443
+```
+
+или
+
+```
+mask_host = 140.82.121.4
+```
+
+В этом случае:
+
+- цензор видит **TLS-подключение к github.com**
+- обычные клиенты/краулер действительно получают **настоящий GitHub**
+
+Telemt просто **проксирует TCP-соединение на GitHub**
+
+# Что видит анализатор трафика?
+
+Для DPI это выглядит так:
+
+```
+client -> TLS -> github.com
+```
+
+или
+
+```
+client -> TLS -> umweltschutz.de
+```
+
+TLS-handshake выглядит валидным, SNI соответствует домену, сертификат корректный - от целевого `mask_host:mask_port`
+
+# Что видит сканер / краулер?
+
+Если сканер попытается подключиться:
+
+```
+openssl s_client -connect 198.18.88.88:443 -servername umweltschutz.de
+```
+
+он получит **обычный HTTPS-сайт-заглушку**
+
+Потому что:
+
+- он не предъявил MTProxy-ключ
+- Telemt отправил соединение на `mask_host:mask_port`, на котором находится nginx 
+
+# Какую проблему решает TLS-Fronting / TCP-Splitting?
+
+Эта архитектура решает сразу несколько проблем обхода цензуры.
+
+## 1 Закрытие плоскости MTProxy от активного сканирования
+
+Многие цензоры:
+
+- сканируют IP-адреса
+- проверяют известные сигнатуры прокси
+
+Telemt отвечает на такие проверки **обычным HTTPS-сайтом**, поэтому прокси невозможно обнаружить простым сканированием
+
+---
+
+## 2 Маскировка трафика под легитимный TLS
+
+Для DPI-систем соединение выглядит как:
+
+```
+обычный TLS-трафик к популярному домену
+```
+
+Это делает блокировку значительно сложнее и непредсказуемее
+
+---
+
+## 3 Устойчивость к протокольному анализу
+
+MTProxy трафик проходит **внутри TLS-like-потока**, поэтому:
+
+- не видны характерные сигнатуры MTProto
+- соединение выглядит как обычный HTTPS
+
+---
+
+## 4 Правдоподобное поведение сервера
+
+Даже если краулер:
+
+- подключится сам
+- выполнит TLS-handshake
+- попытается получить HTTP-ответ
+
+он увидит **реальный сайт**, а не telemt
+
+Это устраняет один из главных признаков для антифрод-краулеров мобильных операторов
+
+# Схема
+
+```text
+			Client
+			  │
+			  │ TCP
+			  │
+			  V
+			Telemt
+			  │
+			  ├── valid MTProxy key
+			  │        │
+			  │        V
+			  │     MTProxy logic
+			  │
+			  └── обычный TLS клиент
+			  │
+			  V
+		 TCP-Splitting
+			  │
+			  V
+	  mask_host:mask_port
+```

docs/model/MODEL.en.md

@@ -0,0 +1,285 @@
+# Telemt Runtime Model
+
+## Scope
+This document defines runtime concepts used by the Middle-End (ME) transport pipeline and the orchestration logic around it.
+
+It focuses on:
+- `ME Pool / Reader / Writer / Refill / Registry`
+- `Adaptive Floor`
+- `Trio-State`
+- `Generation Lifecycle`
+
+## Core Entities
+
+### ME Pool
+`ME Pool` is the runtime orchestrator for all Middle-End writers.
+
+Responsibilities:
+- Holds writer inventory by DC/family/endpoint.
+- Maintains routing primitives and writer selection policy.
+- Tracks generation state (`active`, `warm`, `draining` context).
+- Applies runtime policies (floor mode, refill, reconnect, reinit, fallback behavior).
+- Exposes readiness gates used by admission logic (for conditional accept/cast behavior).
+
+Non-goals:
+- It does not own client protocol decoding.
+- It does not own per-client business policy (quotas/limits).
+
+### ME Writer
+`ME Writer` is a long-lived ME RPC tunnel bound to one concrete ME endpoint (`ip:port`), with:
+- Outbound command channel (send path).
+- Associated reader loop (inbound path).
+- Health/degraded flags.
+- Contour/state and generation metadata.
+
+A writer is the actual data plane carrier for client sessions once bound.
+
+### ME Reader
+`ME Reader` is the inbound parser/dispatcher for one writer:
+- Reads/decrypts ME RPC frames.
+- Validates sequence/checksum.
+- Routes payloads to client-connection channels via `Registry`.
+- Emits close/ack/data events and updates telemetry.
+
+Design intent:
+- Reader must stay non-blocking as much as possible.
+- Backpressure on a single client route must not stall the whole writer stream.
+
+### Refill
+`Refill` is the recovery mechanism that restores writer coverage when capacity drops:
+- Per-endpoint restore (same endpoint first).
+- Per-DC restore to satisfy required floor.
+- Optional outage-mode/shadow behavior for fragile single-endpoint DCs.
+
+Refill works asynchronously and should not block hot routing paths.
+
+### Registry
+`Registry` is the routing index between ME and client sessions:
+- `conn_id -> client response channel`
+- `conn_id <-> writer_id` binding map
+- writer activity snapshots and idle tracking
+
+Main invariants:
+- A `conn_id` routes to at most one active response channel.
+- Writer loss triggers safe unbind/cleanup and close propagation.
+- Registry state is the source of truth for active ME-bound session mapping.
+
+## Adaptive Floor
+
+### What it is
+`Adaptive Floor` is a runtime policy that changes target writer count per DC based on observed activity, instead of always holding static peak floor.
+
+### Why it exists
+Goals:
+- Reduce idle writer churn under low traffic.
+- Keep enough warm capacity to avoid client-visible stalls on burst recovery.
+- Limit needless reconnect storms on unstable endpoints.
+
+### Behavioral model
+- Under activity: floor converges toward configured static requirement.
+- Under prolonged idle: floor can shrink to a safe minimum.
+- Recovery/grace windows prevent aggressive oscillation.
+
+### Safety constraints
+- Never violate minimal survivability floor for a DC group.
+- Refill must still restore quickly on demand.
+- Floor adaptation must not force-drop already bound healthy sessions.
+
+## Trio-State
+
+`Trio-State` is writer contouring:
+- `Warm`
+- `Active`
+- `Draining`
+
+### State semantics
+- `Warm`: connected and validated, not primary for new binds.
+- `Active`: preferred for new binds and normal traffic.
+- `Draining`: no new regular binds; existing sessions continue until graceful retirement rules apply.
+
+### Transition intent
+- `Warm -> Active`: when coverage/readiness conditions are satisfied.
+- `Active -> Draining`: on generation swap, endpoint replacement, or controlled retirement.
+- `Draining -> removed`: after drain TTL/force-close policy (or when naturally empty).
+
+This separation reduces SPOF and keeps cutovers predictable.
+
+## Generation Lifecycle
+
+Generation isolates pool epochs during reinit/reconfiguration.
+
+### Lifecycle phases
+1. `Bootstrap`: initial writers are established.
+2. `Warmup`: next generation writers are created and validated.
+3. `Activation`: generation promoted to active when coverage gate passes.
+4. `Drain`: previous generation becomes draining, existing sessions are allowed to finish.
+5. `Retire`: old generation writers are removed after graceful rules.
+
+### Operational guarantees
+- No partial generation activation without minimum coverage.
+- Existing healthy client sessions should not be dropped just because a new generation appears.
+- Draining generation exists to absorb in-flight traffic during swap.
+
+### Readiness and admission
+Pool readiness is not equivalent to “all endpoints fully saturated”.
+Typical gating strategy:
+- Open admission when per-DC minimal alive coverage exists.
+- Continue background saturation for multi-endpoint DCs.
+
+This keeps startup latency low while preserving eventual full capacity.
+
+## Interactions Between Concepts
+
+- `Generation` defines pool epochs.
+- `Trio-State` defines per-writer role inside/around those epochs.
+- `Adaptive Floor` defines how much capacity should be maintained right now.
+- `Refill` is the actuator that closes the gap between desired and current capacity.
+- `Registry` keeps per-session routing correctness while all of the above changes over time.
+
+## Architectural Approach
+
+### Layered Design
+The runtime is intentionally split into two planes:
+- `Control Plane`: decides desired topology and policy (`floor`, `generation swap`, `refill`, `fallback`).
+- `Data Plane`: executes packet/session transport (`reader`, `writer`, routing, acks, close propagation).
+
+Architectural rule:
+- Control Plane may change writer inventory and policy.
+- Data Plane must remain stable and low-latency while those changes happen.
+
+### Ownership Model
+Ownership is centered around explicit state domains:
+- `MePool` owns writer lifecycle and policy state.
+- `Registry` owns per-connection routing bindings.
+- `Writer task` owns outbound ME socket send progression.
+- `Reader task` owns inbound ME socket parsing and event dispatch.
+
+This prevents accidental cross-layer mutation and keeps invariants local.
+
+### Control Plane Responsibilities
+Control Plane is event-driven and policy-driven:
+- Startup initialization and readiness gates.
+- Runtime reinit (periodic or config-triggered).
+- Coverage checks per DC/family/endpoint group.
+- Floor enforcement (static/adaptive).
+- Refill scheduling and retry orchestration.
+- Generation transition (`warm -> active`, previous `active -> draining`).
+
+Control Plane must prioritize determinism over short-term aggressiveness.
+
+### Data Plane Responsibilities
+Data Plane is throughput-first and allocation-sensitive:
+- Session bind to writer.
+- Per-frame parsing/validation and dispatch.
+- Ack and close signal propagation.
+- Route drop behavior under missing connection or closed channel.
+- Minimal critical logging in hot path.
+
+Data Plane should avoid waiting on operations that are not strictly required for frame correctness.
+
+## Concurrency and Synchronization
+
+### Concurrency Principles
+- Per-writer isolation: each writer has independent send/read task loops.
+- Per-connection isolation: client channel state is scoped by `conn_id`.
+- Asynchronous recovery: refill/reconnect runs outside the packet hot path.
+
+### Synchronization Strategy
+- Shared maps use fine-grained, short-lived locking.
+- Read-mostly paths avoid broad write-lock windows.
+- Backpressure decisions are localized at route/channel boundary.
+
+Design target:
+- A slow consumer should degrade only itself (or its route), not global writer progress.
+
+### Cancellation and Shutdown
+Writer and reader loops are cancellation-aware:
+- explicit cancel token / close command support;
+- safe unbind and cleanup via registry;
+- deterministic order: stop admission -> drain/close -> release resources.
+
+## Consistency Model
+
+### Session Consistency
+For one `conn_id`:
+- exactly one active route target at a time;
+- close and unbind must be idempotent;
+- writer loss must not leave dangling bindings.
+
+### Generation Consistency
+Generational consistency guarantees:
+- New generation is not promoted before minimum coverage gate.
+- Previous generation remains available in `draining` state during handover.
+- Forced retirement is policy-bound (`drain ttl`, optional force-close), not immediate.
+
+### Policy Consistency
+Policy changes (`adaptive/static floor`, fallback mode, retries) should apply without violating established active-session routing invariants.
+
+## Backpressure and Flow Control
+
+### Route-Level Backpressure
+Route channels are bounded by design.
+When pressure increases:
+- short burst absorption is allowed;
+- prolonged congestion triggers controlled drop semantics;
+- drop accounting is explicit via metrics/counters.
+
+### Reader Non-Blocking Priority
+Inbound ME reader path should never be serialized behind one congested client route.
+Practical implication:
+- prefer non-blocking route attempt in the parser loop;
+- move heavy recovery to async side paths.
+
+## Failure Domain Strategy
+
+### Endpoint-Level Failure
+Failure of one endpoint should trigger endpoint-scoped recovery first:
+- same endpoint reconnect;
+- endpoint replacement within same DC group if applicable.
+
+### DC-Level Degradation
+If a DC group cannot satisfy floor:
+- keep service via remaining coverage if policy allows;
+- continue asynchronous refill saturation in background.
+
+### Whole-Pool Readiness Loss
+If no sufficient ME coverage exists:
+- admission gate can hold new accepts (conditional policy);
+- existing sessions should continue when their path remains healthy.
+
+## Performance Architecture Notes
+
+### Hotpath Discipline
+Allowed in hotpath:
+- fixed-size parsing and cheap validation;
+- bounded channel operations;
+- precomputed or low-allocation access patterns.
+
+Avoid in hotpath:
+- repeated expensive decoding;
+- broad locks with awaits inside critical sections;
+- verbose high-frequency logging.
+
+### Throughput Stability Over Peak Spikes
+Architecture prefers stable throughput and predictable latency over short peak gains that increase churn or long-tail reconnect times.
+
+## Evolution and Extension Rules
+
+To evolve this model safely:
+- Add new policy knobs in Control Plane first.
+- Keep Data Plane contracts stable (`conn_id`, route semantics, close semantics).
+- Validate generation and registry invariants before enabling by default.
+- Introduce new retry/recovery strategies behind explicit config.
+
+## Failure and Recovery Notes
+
+- Single-endpoint DC failure is a normal degraded mode case; policy should prioritize fast reconnect and optional shadow/probing strategies.
+- Idle close by peer should be treated as expected when upstream enforces idle timeout.
+- Reconnect backoff must protect against synchronized churn while still allowing fast first retries.
+- Fallback (`ME -> direct DC`) is a policy switch, not a transport bug by itself.
+
+## Terminology Summary
+- `Coverage`: enough live writers to satisfy per-DC acceptance policy.
+- `Floor`: target minimum writer count policy.
+- `Churn`: frequent writer reconnect/remove cycles.
+- `Hotpath`: per-packet/per-connection data path where extra waits/allocations are expensive.

docs/model/MODEL.ru.md

@@ -0,0 +1,285 @@
+# Runtime-модель Telemt
+
+## Область описания
+Документ фиксирует ключевые runtime-понятия пайплайна Middle-End (ME) и оркестрации вокруг него.
+
+Фокус:
+- `ME Pool / Reader / Writer / Refill / Registry`
+- `Adaptive Floor`
+- `Trio-State`
+- `Generation Lifecycle`
+
+## Базовые сущности
+
+### ME Pool
+`ME Pool` — центральный оркестратор всех Middle-End writer-ов.
+
+Зона ответственности:
+- хранит инвентарь writer-ов по DC/family/endpoint;
+- управляет выбором writer-а и маршрутизацией;
+- ведёт состояние поколений (`active`, `warm`, `draining` контекст);
+- применяет runtime-политики (floor, refill, reconnect, reinit, fallback);
+- отдаёт сигналы готовности для admission-логики (conditional accept/cast).
+
+Что не делает:
+- не декодирует клиентский протокол;
+- не реализует бизнес-политику пользователя (квоты/лимиты).
+
+### ME Writer
+`ME Writer` — долгоживущий ME RPC-канал к конкретному endpoint (`ip:port`), у которого есть:
+- канал команд на отправку;
+- связанный reader loop для входящего потока;
+- флаги состояния/деградации;
+- метаданные contour/state и generation.
+
+Writer — это фактический data-plane носитель клиентских сессий после бинда.
+
+### ME Reader
+`ME Reader` — входной parser/dispatcher одного writer-а:
+- читает и расшифровывает ME RPC-фреймы;
+- проверяет sequence/checksum;
+- маршрутизирует payload в client-каналы через `Registry`;
+- обрабатывает close/ack/data и обновляет телеметрию.
+
+Инженерный принцип:
+- Reader должен оставаться неблокирующим.
+- Backpressure одной клиентской сессии не должен останавливать весь поток writer-а.
+
+### Refill
+`Refill` — механизм восстановления покрытия writer-ов при просадке:
+- восстановление на том же endpoint в первую очередь;
+- восстановление по DC до требуемого floor;
+- опциональные outage/shadow-режимы для хрупких single-endpoint DC.
+
+Refill работает асинхронно и не должен блокировать hotpath.
+
+### Registry
+`Registry` — маршрутизационный индекс между ME и клиентскими сессиями:
+- `conn_id -> канал ответа клиенту`;
+- map биндов `conn_id <-> writer_id`;
+- снимки активности writer-ов и idle-трекинг.
+
+Ключевые инварианты:
+- один `conn_id` маршрутизируется максимум в один активный канал ответа;
+- потеря writer-а приводит к безопасному unbind/cleanup и отправке close;
+- именно `Registry` является источником истины по активным ME-биндам.
+
+## Adaptive Floor
+
+### Что это
+`Adaptive Floor` — runtime-политика, которая динамически меняет целевое число writer-ов на DC в зависимости от активности, а не держит всегда фиксированный статический floor.
+
+### Зачем
+Цели:
+- уменьшить churn на idle-трафике;
+- сохранить достаточную прогретую ёмкость для быстрых всплесков;
+- снизить лишние reconnect-штормы на нестабильных endpoint.
+
+### Модель поведения
+- при активности floor стремится к статическому требованию;
+- при длительном idle floor может снижаться до безопасного минимума;
+- grace/recovery окна не дают системе "флапать" слишком резко.
+
+### Ограничения безопасности
+- нельзя нарушать минимальный floor выживаемости DC-группы;
+- refill обязан быстро нарастить покрытие по запросу;
+- адаптация не должна принудительно ронять уже привязанные healthy-сессии.
+
+## Trio-State
+
+`Trio-State` — контурная роль writer-а:
+- `Warm`
+- `Active`
+- `Draining`
+
+### Семантика состояний
+- `Warm`: writer подключён и валиден, но не основной для новых биндов.
+- `Active`: приоритетный для новых биндов и обычного трафика.
+- `Draining`: новые обычные бинды не назначаются; текущие сессии живут до правил graceful-вывода.
+
+### Логика переходов
+- `Warm -> Active`: когда достигнуты условия покрытия/готовности.
+- `Active -> Draining`: при swap поколения, замене endpoint или контролируемом выводе.
+- `Draining -> removed`: после drain TTL/force-close политики (или естественного опустошения).
+
+Такое разделение снижает SPOF-риски и делает cutover предсказуемым.
+
+## Generation Lifecycle
+
+Generation изолирует эпохи пула при reinit/reconfiguration.
+
+### Фазы жизненного цикла
+1. `Bootstrap`: поднимается начальный набор writer-ов.
+2. `Warmup`: создаётся и валидируется новое поколение.
+3. `Activation`: новое поколение становится active после прохождения coverage-gate.
+4. `Drain`: предыдущее поколение переводится в draining, текущим сессиям дают завершиться.
+5. `Retire`: старое поколение удаляется по graceful-правилам.
+
+### Операционные гарантии
+- нельзя активировать поколение частично без минимального покрытия;
+- healthy-клиенты не должны теряться только из-за появления нового поколения;
+- draining-поколение служит буфером для in-flight трафика во время swap.
+
+### Готовность и приём клиентов
+Готовность пула не равна "все endpoint полностью насыщены".
+Типичная стратегия:
+- открыть admission при минимально достаточном alive-покрытии по DC;
+- параллельно продолжать saturation для multi-endpoint DC.
+
+Это уменьшает startup latency и сохраняет выход на полную ёмкость.
+
+## Как понятия связаны между собой
+
+- `Generation` задаёт эпохи пула.
+- `Trio-State` задаёт роль каждого writer-а внутри/между эпохами.
+- `Adaptive Floor` задаёт, сколько ёмкости нужно сейчас.
+- `Refill` — исполнитель, который закрывает разницу между desired и current capacity.
+- `Registry` гарантирует корректную маршрутизацию сессий, пока всё выше меняется.
+
+## Архитектурный подход
+
+### Слоистая модель
+Runtime специально разделён на две плоскости:
+- `Control Plane`: принимает решения о целевой топологии и политиках (`floor`, `generation swap`, `refill`, `fallback`).
+- `Data Plane`: исполняет транспорт сессий и пакетов (`reader`, `writer`, маршрутизация, ack, close).
+
+Ключевое правило:
+- Control Plane может менять состав writer-ов и policy.
+- Data Plane должен оставаться стабильным и низколатентным в момент этих изменений.
+
+### Модель владения состоянием
+Владение разделено по доменам:
+- `MePool` владеет жизненным циклом writer-ов и policy-state.
+- `Registry` владеет routing-биндами клиентских сессий.
+- `Writer task` владеет исходящей прогрессией ME-сокета.
+- `Reader task` владеет входящим парсингом и dispatch-событиями.
+
+Это ограничивает побочные мутации и локализует инварианты.
+
+### Обязанности Control Plane
+Control Plane работает событийно и policy-ориентированно:
+- стартовая инициализация и readiness-gate;
+- runtime reinit (периодический и/или по изменению конфигурации);
+- проверки покрытия по DC/family/endpoint group;
+- применение floor-политики (static/adaptive);
+- планирование refill и orchestration retry;
+- переходы поколений (`warm -> active`, прежний `active -> draining`).
+
+Для него важнее детерминизм, чем агрессивная краткосрочная реакция.
+
+### Обязанности Data Plane
+Data Plane ориентирован на пропускную способность и предсказуемую задержку:
+- bind клиентской сессии к writer-у;
+- per-frame parsing/validation/dispatch;
+- распространение ack/close;
+- корректная реакция на missing conn/closed channel;
+- минимальный лог-шум в hotpath.
+
+Data Plane не должен ждать операций, не критичных для корректности текущего фрейма.
+
+## Конкурентность и синхронизация
+
+### Принципы конкурентности
+- Изоляция по writer-у: у каждого writer-а независимые send/read loop.
+- Изоляция по сессии: состояние канала локально для `conn_id`.
+- Асинхронное восстановление: refill/reconnect выполняются вне пакетного hotpath.
+
+### Стратегия синхронизации
+- Для shared map используются короткие и узкие lock-секции.
+- Read-heavy пути избегают длительных write-lock окон.
+- Решения по backpressure локализованы на границе route/channel.
+
+Цель:
+- медленный consumer должен деградировать локально, не останавливая глобальный прогресс writer-а.
+
+### Cancellation и shutdown
+Reader/Writer loop должны быть cancellation-aware:
+- явные cancel token / close command;
+- безопасный unbind/cleanup через registry;
+- детерминированный порядок: stop admission -> drain/close -> release resources.
+
+## Модель согласованности
+
+### Согласованность сессии
+Для одного `conn_id`:
+- одновременно ровно один активный route-target;
+- close/unbind операции идемпотентны;
+- потеря writer-а не оставляет dangling-бинды.
+
+### Согласованность поколения
+Гарантии generation:
+- новое поколение не активируется до прохождения минимального coverage-gate;
+- предыдущее поколение остаётся в `draining` на время handover;
+- принудительный вывод writer-ов ограничен policy (`drain ttl`, optional force-close), а не мгновенный.
+
+### Согласованность политик
+Изменение policy (`adaptive/static floor`, fallback mode, retries) не должно ломать инварианты маршрутизации уже активных сессий.
+
+## Backpressure и управление потоком
+
+### Route-level backpressure
+Route-каналы намеренно bounded.
+При росте нагрузки:
+- кратковременный burst поглощается;
+- длительная перегрузка переходит в контролируемую drop-семантику;
+- все drop-сценарии должны быть прозрачно видны в метриках.
+
+### Приоритет неблокирующего Reader
+Входящий ME-reader path не должен сериализоваться из-за одной перегруженной клиентской сессии.
+Практически это означает:
+- использовать неблокирующую попытку route в parser loop;
+- выносить тяжёлое восстановление в асинхронные side-path.
+
+## Стратегия доменов отказа
+
+### Отказ отдельного endpoint
+Сначала применяется endpoint-local recovery:
+- reconnect в тот же endpoint;
+- затем замена endpoint внутри той же DC-группы (если доступно).
+
+### Деградация уровня DC
+Если DC-группа не набирает floor:
+- сервис сохраняется на остаточном покрытии (если policy разрешает);
+- saturation refill продолжается асинхронно в фоне.
+
+### Потеря готовности всего пула
+Если достаточного ME-покрытия нет:
+- admission gate может временно закрыть приём новых подключений (conditional policy);
+- уже активные сессии продолжают работать, пока их маршрут остаётся healthy.
+
+## Архитектурные заметки по производительности
+
+### Дисциплина hotpath
+Допустимо в hotpath:
+- фиксированный и дешёвый parsing/validation;
+- bounded channel operations;
+- precomputed/low-allocation доступ к данным.
+
+Нежелательно в hotpath:
+- повторные дорогие decode;
+- широкие lock-секции с `await` внутри;
+- высокочастотный подробный logging.
+
+### Стабильность важнее пиков
+Архитектура приоритетно выбирает стабильную пропускную способность и предсказуемую latency, а не краткосрочные пики ценой churn и long-tail reconnect.
+
+## Правила эволюции модели
+
+Чтобы расширять модель безопасно:
+- новые policy knobs сначала внедрять в Control Plane;
+- контракты Data Plane (`conn_id`, route/close семантика) держать стабильными;
+- перед дефолтным включением проверять generation/registry инварианты;
+- новые recovery/retry стратегии вводить через явный config-флаг.
+
+## Нюансы отказов и восстановления
+
+- падение single-endpoint DC — штатный деградированный сценарий; приоритет: быстрый reconnect и, при необходимости, shadow/probing;
+- idle-close со стороны peer должен считаться нормальным событием при upstream idle-timeout;
+- backoff reconnect-логики должен ограничивать синхронный churn, но сохранять быстрые первые попытки;
+- fallback (`ME -> direct DC`) — это переключаемая policy-ветка, а не автоматический признак бага транспорта.
+
+## Краткий словарь
+- `Coverage`: достаточное число живых writer-ов для политики приёма по DC.
+- `Floor`: целевая минимальная ёмкость writer-ов.
+- `Churn`: частые циклы reconnect/remove writer-ов.
+- `Hotpath`: пер-пакетный/пер-коннектный путь, где любые лишние ожидания и аллокации особенно дороги.

install.sh

@@ -1,73 +1,115 @@
-sudo bash -c '
-set -e
+#!/bin/sh
+set -eu
 
-# --- Проверка на существующую установку ---
-if systemctl list-unit-files | grep -q telemt.service; then
-    # --- РЕЖИМ ОБНОВЛЕНИЯ ---
-    echo "--- Обнаружена существующая установка Telemt. Запускаю обновление... ---"
+REPO="${REPO:-telemt/telemt}"
+BIN_NAME="${BIN_NAME:-telemt}"
+VERSION="${1:-${VERSION:-latest}}"
+INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}"
 
-    echo "[*] Остановка службы telemt..."
-    systemctl stop telemt || true # Игнорируем ошибку, если служба уже остановлена
+say() {
+    printf '%s\n' "$*"
+}
 
-    echo "[1/2] Скачивание последней версии Telemt..."
-    wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
+die() {
+    printf 'Error: %s\n' "$*" >&2
+    exit 1
+}
 
-    echo "[1/2] Замена исполняемого файла в /usr/local/bin..."
-    mv telemt /usr/local/bin/telemt
-    chmod +x /usr/local/bin/telemt
+need_cmd() {
+    command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"
+}
 
-    echo "[2/2] Запуск службы..."
-    systemctl start telemt
+detect_os() {
+    os="$(uname -s)"
+    case "$os" in
+        Linux) printf 'linux\n' ;;
+        OpenBSD) printf 'openbsd\n' ;;
+        *) printf '%s\n' "$os" ;;
+    esac
+}
 
-    echo "--- Обновление Telemt успешно завершено! ---"
-    echo
-    echo "Для проверки статуса службы выполните:"
-    echo "   systemctl status telemt"
+detect_arch() {
+    arch="$(uname -m)"
+    case "$arch" in
+        x86_64|amd64) printf 'x86_64\n' ;;
+        aarch64|arm64) printf 'aarch64\n' ;;
+        *) die "unsupported architecture: $arch" ;;
+    esac
+}
 
-else
-    # --- РЕЖИМ НОВОЙ УСТАНОВКИ ---
-    echo "--- Начало автоматической установки Telemt ---"
+detect_libc() {
+    case "$(ldd --version 2>&1 || true)" in
+        *musl*) printf 'musl\n' ;;
+        *) printf 'gnu\n' ;;
+    esac
+}
 
-    # Шаг 1: Скачивание и установка бинарного файла
-    echo "[1/5] Скачивание последней версии Telemt..."
-    wget -qO- "https://github.com/telemt/telemt/releases/latest/download/telemt-$(uname -m)-linux-$(ldd --version 2>&1 | grep -iq musl && echo musl || echo gnu).tar.gz" | tar -xz
+fetch_to_stdout() {
+    url="$1"
+    if command -v curl >/dev/null 2>&1; then
+        curl -fsSL "$url"
+    elif command -v wget >/dev/null 2>&1; then
+        wget -qO- "$url"
+    else
+        die "neither curl nor wget is installed"
+    fi
+}
 
-    echo "[1/5] Перемещение исполняемого файла в /usr/local/bin и установка прав..."
-    mv telemt /usr/local/bin/telemt
-    chmod +x /usr/local/bin/telemt
+install_binary() {
+    src="$1"
+    dst="$2"
 
-    # Шаг 2: Генерация секрета
-    echo "[2/5] Генерация секретного ключа..."
-    SECRET=$(openssl rand -hex 16)
+    if [ -w "$INSTALL_DIR" ] || { [ ! -e "$INSTALL_DIR" ] && [ -w "$(dirname "$INSTALL_DIR")" ]; }; then
+        mkdir -p "$INSTALL_DIR"
+        install -m 0755 "$src" "$dst"
+    elif command -v sudo >/dev/null 2>&1; then
+        sudo mkdir -p "$INSTALL_DIR"
+        sudo install -m 0755 "$src" "$dst"
+    else
+        die "cannot write to $INSTALL_DIR and sudo is not available"
+    fi
+}
 
-    # Шаг 3: Создание файла конфигурации
-    echo "[3/5] Создание файла конфигурации /etc/telemt.toml..."
-    printf "# === General Settings ===\n[general]\n[general.modes]\nclassic = false\nsecure = false\ntls = true\n\n# === Anti-Censorship & Masking ===\n[censorship]\n# !!! ВАЖНО: Замените на ваш домен или домен, который вы хотите использовать для маскировки !!!\ntls_domain = \"petrovich.ru\"\n\n[access.users]\nhello = \"%s\"\n" "$SECRET" > /etc/telemt.toml
+need_cmd uname
+need_cmd tar
+need_cmd mktemp
+need_cmd grep
+need_cmd install
 
-    # Шаг 4: Создание службы Systemd
-    echo "[4/5] Создание службы systemd..."
-    printf "[Unit]\nDescription=Telemt Proxy\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/telemt /etc/telemt.toml\nRestart=on-failure\nRestartSec=5\nLimitNOFILE=65536\n\n[Install]\nWantedBy=multi-user.target\n" > /etc/systemd/system/telemt.service
+ARCH="$(detect_arch)"
+OS="$(detect_os)"
 
-    # Шаг 5: Запуск службы
-    echo "[5/5] Перезагрузка systemd, запуск и включение службы telemt..."
-    systemctl daemon-reload
-    systemctl start telemt
-    systemctl enable telemt
-
-    echo "--- Установка и запуск Telemt успешно завершены! ---"
-    echo
-    echo "ВАЖНАЯ ИНФОРМАЦИЯ:"
-    echo "==================="
-    echo "1. Вам НЕОБХОДИМО отредактировать файл /etc/telemt.toml и заменить '\''petrovich.ru'\'' на другой домен"
-    echo "   с помощью команды:"
-    echo "   nano /etc/telemt.toml"
-    echo "   После редактирования файла перезапустите службу командой:"
-    echo "   sudo systemctl restart telemt"
-    echo
-    echo "2. Для проверки статуса службы выполните команду:"
-    echo "   systemctl status telemt"
-    echo
-    echo "3. Для получения ссылок на подключение выполните команду:"
-    echo "   journalctl -u telemt -n -g '\''links'\'' --no-pager -o cat | tac"
+if [ "$OS" != "linux" ]; then
+    case "$OS" in
+        openbsd)
+            die "install.sh installs only Linux release artifacts. On OpenBSD, build from source (see docs/OPENBSD.en.md)."
+            ;;
+        *)
+            die "unsupported operating system for install.sh: $OS"
+            ;;
+    esac
 fi
-'
+
+LIBC="$(detect_libc)"
+
+case "$VERSION" in
+    latest)
+        URL="https://github.com/$REPO/releases/latest/download/${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
+        ;;
+    *)
+        URL="https://github.com/$REPO/releases/download/${VERSION}/${BIN_NAME}-${ARCH}-linux-${LIBC}.tar.gz"
+        ;;
+esac
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT INT TERM
+
+say "Installing $BIN_NAME ($VERSION) for $ARCH-linux-$LIBC..."
+fetch_to_stdout "$URL" | tar -xzf - -C "$TMPDIR"
+
+[ -f "$TMPDIR/$BIN_NAME" ] || die "archive did not contain $BIN_NAME"
+
+install_binary "$TMPDIR/$BIN_NAME" "$INSTALL_DIR/$BIN_NAME"
+
+say "Installed: $INSTALL_DIR/$BIN_NAME"
+"$INSTALL_DIR/$BIN_NAME" --version 2>/dev/null || true

src/api/config_store.rs

@@ -0,0 +1,269 @@
+use std::collections::BTreeMap;
+use std::io::Write;
+use std::path::{Path, PathBuf};
+
+use chrono::{DateTime, Utc};
+use hyper::header::IF_MATCH;
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+use crate::config::ProxyConfig;
+
+use super::model::ApiFailure;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(super) enum AccessSection {
+    Users,
+    UserAdTags,
+    UserMaxTcpConns,
+    UserExpirations,
+    UserDataQuota,
+    UserMaxUniqueIps,
+}
+
+impl AccessSection {
+    fn table_name(self) -> &'static str {
+        match self {
+            Self::Users => "access.users",
+            Self::UserAdTags => "access.user_ad_tags",
+            Self::UserMaxTcpConns => "access.user_max_tcp_conns",
+            Self::UserExpirations => "access.user_expirations",
+            Self::UserDataQuota => "access.user_data_quota",
+            Self::UserMaxUniqueIps => "access.user_max_unique_ips",
+        }
+    }
+}
+
+pub(super) fn parse_if_match(headers: &hyper::HeaderMap) -> Option<String> {
+    headers
+        .get(IF_MATCH)
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(|value| value.trim_matches('"').to_string())
+}
+
+pub(super) async fn ensure_expected_revision(
+    config_path: &Path,
+    expected_revision: Option<&str>,
+) -> Result<(), ApiFailure> {
+    let Some(expected) = expected_revision else {
+        return Ok(());
+    };
+    let current = current_revision(config_path).await?;
+    if current != expected {
+        return Err(ApiFailure::new(
+            hyper::StatusCode::CONFLICT,
+            "revision_conflict",
+            "Config revision mismatch",
+        ));
+    }
+    Ok(())
+}
+
+pub(super) async fn current_revision(config_path: &Path) -> Result<String, ApiFailure> {
+    let content = tokio::fs::read_to_string(config_path)
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to read config: {}", e)))?;
+    Ok(compute_revision(&content))
+}
+
+pub(super) fn compute_revision(content: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(content.as_bytes());
+    hex::encode(hasher.finalize())
+}
+
+pub(super) async fn load_config_from_disk(config_path: &Path) -> Result<ProxyConfig, ApiFailure> {
+    let config_path = config_path.to_path_buf();
+    tokio::task::spawn_blocking(move || ProxyConfig::load(config_path))
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to join config loader: {}", e)))?
+        .map_err(|e| ApiFailure::internal(format!("failed to load config: {}", e)))
+}
+
+pub(super) async fn save_config_to_disk(
+    config_path: &Path,
+    cfg: &ProxyConfig,
+) -> Result<String, ApiFailure> {
+    let serialized = toml::to_string_pretty(cfg)
+        .map_err(|e| ApiFailure::internal(format!("failed to serialize config: {}", e)))?;
+    write_atomic(config_path.to_path_buf(), serialized.clone()).await?;
+    Ok(compute_revision(&serialized))
+}
+
+pub(super) async fn save_access_sections_to_disk(
+    config_path: &Path,
+    cfg: &ProxyConfig,
+    sections: &[AccessSection],
+) -> Result<String, ApiFailure> {
+    let mut content = tokio::fs::read_to_string(config_path)
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to read config: {}", e)))?;
+
+    let mut applied = Vec::new();
+    for section in sections {
+        if applied.contains(section) {
+            continue;
+        }
+        let rendered = render_access_section(cfg, *section)?;
+        content = upsert_toml_table(&content, section.table_name(), &rendered);
+        applied.push(*section);
+    }
+
+    write_atomic(config_path.to_path_buf(), content.clone()).await?;
+    Ok(compute_revision(&content))
+}
+
+fn render_access_section(cfg: &ProxyConfig, section: AccessSection) -> Result<String, ApiFailure> {
+    let body = match section {
+        AccessSection::Users => {
+            let rows: BTreeMap<String, String> = cfg
+                .access
+                .users
+                .iter()
+                .map(|(key, value)| (key.clone(), value.clone()))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserAdTags => {
+            let rows: BTreeMap<String, String> = cfg
+                .access
+                .user_ad_tags
+                .iter()
+                .map(|(key, value)| (key.clone(), value.clone()))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserMaxTcpConns => {
+            let rows: BTreeMap<String, usize> = cfg
+                .access
+                .user_max_tcp_conns
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserExpirations => {
+            let rows: BTreeMap<String, DateTime<Utc>> = cfg
+                .access
+                .user_expirations
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserDataQuota => {
+            let rows: BTreeMap<String, u64> = cfg
+                .access
+                .user_data_quota
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+        AccessSection::UserMaxUniqueIps => {
+            let rows: BTreeMap<String, usize> = cfg
+                .access
+                .user_max_unique_ips
+                .iter()
+                .map(|(key, value)| (key.clone(), *value))
+                .collect();
+            serialize_table_body(&rows)?
+        }
+    };
+
+    let mut out = format!("[{}]\n", section.table_name());
+    if !body.is_empty() {
+        out.push_str(&body);
+    }
+    if !out.ends_with('\n') {
+        out.push('\n');
+    }
+    Ok(out)
+}
+
+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 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());
+        out.push_str(&source[..start]);
+        out.push_str(replacement);
+        out.push_str(&source[end..]);
+        return out;
+    }
+
+    let mut out = source.to_string();
+    if !out.is_empty() && !out.ends_with('\n') {
+        out.push('\n');
+    }
+    if !out.is_empty() {
+        out.push('\n');
+    }
+    out.push_str(replacement);
+    out
+}
+
+fn find_toml_table_bounds(source: &str, table_name: &str) -> Option<(usize, usize)> {
+    let target = format!("[{}]", table_name);
+    let mut offset = 0usize;
+    let mut start = None;
+
+    for line in source.split_inclusive('\n') {
+        let trimmed = line.trim();
+        if let Some(start_offset) = start {
+            if trimmed.starts_with('[') {
+                return Some((start_offset, offset));
+            }
+        } else if trimmed == target {
+            start = Some(offset);
+        }
+        offset = offset.saturating_add(line.len());
+    }
+
+    start.map(|start_offset| (start_offset, source.len()))
+}
+
+async fn write_atomic(path: PathBuf, contents: String) -> Result<(), ApiFailure> {
+    tokio::task::spawn_blocking(move || write_atomic_sync(&path, &contents))
+        .await
+        .map_err(|e| ApiFailure::internal(format!("failed to join writer: {}", e)))?
+        .map_err(|e| ApiFailure::internal(format!("failed to write config: {}", e)))
+}
+
+fn write_atomic_sync(path: &Path, contents: &str) -> std::io::Result<()> {
+    let parent = path.parent().unwrap_or_else(|| Path::new("."));
+    std::fs::create_dir_all(parent)?;
+
+    let tmp_name = format!(
+        ".{}.tmp-{}",
+        path.file_name()
+            .and_then(|s| s.to_str())
+            .unwrap_or("config.toml"),
+        rand::random::<u64>()
+    );
+    let tmp_path = parent.join(tmp_name);
+
+    let write_result = (|| {
+        let mut file = std::fs::OpenOptions::new()
+            .create_new(true)
+            .write(true)
+            .open(&tmp_path)?;
+        file.write_all(contents.as_bytes())?;
+        file.sync_all()?;
+        std::fs::rename(&tmp_path, path)?;
+        if let Ok(dir) = std::fs::File::open(parent) {
+            let _ = dir.sync_all();
+        }
+        Ok(())
+    })();
+
+    if write_result.is_err() {
+        let _ = std::fs::remove_file(&tmp_path);
+    }
+    write_result
+}

src/api/events.rs

@@ -0,0 +1,90 @@
+use std::collections::VecDeque;
+use std::sync::Mutex;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::Serialize;
+
+#[derive(Clone, Serialize)]
+pub(super) struct ApiEventRecord {
+    pub(super) seq: u64,
+    pub(super) ts_epoch_secs: u64,
+    pub(super) event_type: String,
+    pub(super) context: String,
+}
+
+#[derive(Clone, Serialize)]
+pub(super) struct ApiEventSnapshot {
+    pub(super) capacity: usize,
+    pub(super) dropped_total: u64,
+    pub(super) events: Vec<ApiEventRecord>,
+}
+
+struct ApiEventsInner {
+    capacity: usize,
+    dropped_total: u64,
+    next_seq: u64,
+    events: VecDeque<ApiEventRecord>,
+}
+
+/// Bounded ring-buffer for control-plane API/runtime events.
+pub(crate) struct ApiEventStore {
+    inner: Mutex<ApiEventsInner>,
+}
+
+impl ApiEventStore {
+    pub(super) fn new(capacity: usize) -> Self {
+        let bounded = capacity.max(16);
+        Self {
+            inner: Mutex::new(ApiEventsInner {
+                capacity: bounded,
+                dropped_total: 0,
+                next_seq: 1,
+                events: VecDeque::with_capacity(bounded),
+            }),
+        }
+    }
+
+    pub(super) fn record(&self, event_type: &str, context: impl Into<String>) {
+        let now_epoch_secs = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs();
+        let mut context = context.into();
+        if context.len() > 256 {
+            context.truncate(256);
+        }
+
+        let mut guard = self.inner.lock().expect("api event store mutex poisoned");
+        if guard.events.len() == guard.capacity {
+            guard.events.pop_front();
+            guard.dropped_total = guard.dropped_total.saturating_add(1);
+        }
+        let seq = guard.next_seq;
+        guard.next_seq = guard.next_seq.saturating_add(1);
+        guard.events.push_back(ApiEventRecord {
+            seq,
+            ts_epoch_secs: now_epoch_secs,
+            event_type: event_type.to_string(),
+            context,
+        });
+    }
+
+    pub(super) fn snapshot(&self, limit: usize) -> ApiEventSnapshot {
+        let guard = self.inner.lock().expect("api event store mutex poisoned");
+        let bounded_limit = limit.clamp(1, guard.capacity.max(1));
+        let mut items: Vec<ApiEventRecord> = guard
+            .events
+            .iter()
+            .rev()
+            .take(bounded_limit)
+            .cloned()
+            .collect();
+        items.reverse();
+
+        ApiEventSnapshot {
+            capacity: guard.capacity,
+            dropped_total: guard.dropped_total,
+            events: items,
+        }
+    }
+}

src/api/http_utils.rs

@@ -0,0 +1,91 @@
+use http_body_util::{BodyExt, Full};
+use hyper::StatusCode;
+use hyper::body::{Bytes, Incoming};
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+
+use super::model::{ApiFailure, ErrorBody, ErrorResponse, SuccessResponse};
+
+pub(super) fn success_response<T: Serialize>(
+    status: StatusCode,
+    data: T,
+    revision: String,
+) -> hyper::Response<Full<Bytes>> {
+    let payload = SuccessResponse {
+        ok: true,
+        data,
+        revision,
+    };
+    let body = serde_json::to_vec(&payload).unwrap_or_else(|_| b"{\"ok\":false}".to_vec());
+    hyper::Response::builder()
+        .status(status)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(Full::new(Bytes::from(body)))
+        .unwrap()
+}
+
+pub(super) fn error_response(
+    request_id: u64,
+    failure: ApiFailure,
+) -> hyper::Response<Full<Bytes>> {
+    let payload = ErrorResponse {
+        ok: false,
+        error: ErrorBody {
+            code: failure.code,
+            message: failure.message,
+        },
+        request_id,
+    };
+    let body = serde_json::to_vec(&payload).unwrap_or_else(|_| {
+        format!(
+            "{{\"ok\":false,\"error\":{{\"code\":\"internal_error\",\"message\":\"serialization failed\"}},\"request_id\":{}}}",
+            request_id
+        )
+        .into_bytes()
+    });
+    hyper::Response::builder()
+        .status(failure.status)
+        .header("content-type", "application/json; charset=utf-8")
+        .body(Full::new(Bytes::from(body)))
+        .unwrap()
+}
+
+pub(super) async fn read_json<T: DeserializeOwned>(
+    body: Incoming,
+    limit: usize,
+) -> Result<T, ApiFailure> {
+    let bytes = read_body_with_limit(body, limit).await?;
+    serde_json::from_slice(&bytes).map_err(|_| ApiFailure::bad_request("Invalid JSON body"))
+}
+
+pub(super) async fn read_optional_json<T: DeserializeOwned>(
+    body: Incoming,
+    limit: usize,
+) -> Result<Option<T>, ApiFailure> {
+    let bytes = read_body_with_limit(body, limit).await?;
+    if bytes.is_empty() {
+        return Ok(None);
+    }
+    serde_json::from_slice(&bytes)
+        .map(Some)
+        .map_err(|_| ApiFailure::bad_request("Invalid JSON body"))
+}
+
+async fn read_body_with_limit(body: Incoming, limit: usize) -> Result<Vec<u8>, ApiFailure> {
+    let mut collected = Vec::new();
+    let mut body = body;
+    while let Some(frame_result) = body.frame().await {
+        let frame = frame_result.map_err(|_| ApiFailure::bad_request("Invalid request body"))?;
+        if let Some(chunk) = frame.data_ref() {
+            if collected.len().saturating_add(chunk.len()) > limit {
+                return Err(ApiFailure::new(
+                    StatusCode::PAYLOAD_TOO_LARGE,
+                    "payload_too_large",
+                    format!("Body exceeds {} bytes", limit),
+                ));
+            }
+            collected.extend_from_slice(chunk);
+        }
+    }
+    Ok(collected)
+}

src/api/mod.rs

@@ -0,0 +1,554 @@
+use std::convert::Infallible;
+use std::net::{IpAddr, SocketAddr};
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+
+use http_body_util::Full;
+use hyper::body::{Bytes, Incoming};
+use hyper::header::AUTHORIZATION;
+use hyper::server::conn::http1;
+use hyper::service::service_fn;
+use hyper::{Method, Request, Response, StatusCode};
+use tokio::net::TcpListener;
+use tokio::sync::{Mutex, RwLock, watch};
+use tracing::{debug, info, warn};
+
+use crate::config::ProxyConfig;
+use crate::ip_tracker::UserIpTracker;
+use crate::proxy::route_mode::RouteRuntimeController;
+use crate::startup::StartupTracker;
+use crate::stats::Stats;
+use crate::transport::middle_proxy::MePool;
+use crate::transport::UpstreamManager;
+
+mod config_store;
+mod events;
+mod http_utils;
+mod model;
+mod runtime_edge;
+mod runtime_init;
+mod runtime_min;
+mod runtime_selftest;
+mod runtime_stats;
+mod runtime_watch;
+mod runtime_zero;
+mod users;
+
+use config_store::{current_revision, parse_if_match};
+use http_utils::{error_response, read_json, read_optional_json, success_response};
+use events::ApiEventStore;
+use model::{
+    ApiFailure, CreateUserRequest, HealthData, PatchUserRequest, RotateSecretRequest, SummaryData,
+};
+use runtime_edge::{
+    EdgeConnectionsCacheEntry, build_runtime_connections_summary_data,
+    build_runtime_events_recent_data,
+};
+use runtime_init::build_runtime_initialization_data;
+use runtime_min::{
+    build_runtime_me_pool_state_data, build_runtime_me_quality_data, build_runtime_nat_stun_data,
+    build_runtime_upstream_quality_data, build_security_whitelist_data,
+};
+use runtime_selftest::build_runtime_me_selftest_data;
+use runtime_stats::{
+    MinimalCacheEntry, build_dcs_data, build_me_writers_data, build_minimal_all_data,
+    build_upstreams_data, build_zero_all_data,
+};
+use runtime_zero::{
+    build_limits_effective_data, build_runtime_gates_data, build_security_posture_data,
+    build_system_info_data,
+};
+use runtime_watch::spawn_runtime_watchers;
+use users::{create_user, delete_user, patch_user, rotate_secret, users_from_config};
+
+pub(super) struct ApiRuntimeState {
+    pub(super) process_started_at_epoch_secs: u64,
+    pub(super) config_reload_count: AtomicU64,
+    pub(super) last_config_reload_epoch_secs: AtomicU64,
+    pub(super) admission_open: AtomicBool,
+}
+
+#[derive(Clone)]
+pub(super) struct ApiShared {
+    pub(super) stats: Arc<Stats>,
+    pub(super) ip_tracker: Arc<UserIpTracker>,
+    pub(super) me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+    pub(super) upstream_manager: Arc<UpstreamManager>,
+    pub(super) config_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>>>,
+    pub(super) runtime_edge_connections_cache: Arc<Mutex<Option<EdgeConnectionsCacheEntry>>>,
+    pub(super) runtime_edge_recompute_lock: Arc<Mutex<()>>,
+    pub(super) runtime_events: Arc<ApiEventStore>,
+    pub(super) request_id: Arc<AtomicU64>,
+    pub(super) runtime_state: Arc<ApiRuntimeState>,
+    pub(super) startup_tracker: Arc<StartupTracker>,
+    pub(super) route_runtime: Arc<RouteRuntimeController>,
+}
+
+impl ApiShared {
+    fn next_request_id(&self) -> u64 {
+        self.request_id.fetch_add(1, Ordering::Relaxed)
+    }
+
+    fn detected_link_ips(&self) -> (Option<IpAddr>, Option<IpAddr>) {
+        *self.detected_ips_rx.borrow()
+    }
+}
+
+pub async fn serve(
+    listen: SocketAddr,
+    stats: Arc<Stats>,
+    ip_tracker: Arc<UserIpTracker>,
+    me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    upstream_manager: Arc<UpstreamManager>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    admission_rx: watch::Receiver<bool>,
+    config_path: PathBuf,
+    detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
+    process_started_at_epoch_secs: u64,
+    startup_tracker: Arc<StartupTracker>,
+) {
+    let listener = match TcpListener::bind(listen).await {
+        Ok(listener) => listener,
+        Err(error) => {
+            warn!(
+                error = %error,
+                listen = %listen,
+                "Failed to bind API listener"
+            );
+            return;
+        }
+    };
+
+    info!("API endpoint: http://{}/v1/*", listen);
+
+    let runtime_state = Arc::new(ApiRuntimeState {
+        process_started_at_epoch_secs,
+        config_reload_count: AtomicU64::new(0),
+        last_config_reload_epoch_secs: AtomicU64::new(0),
+        admission_open: AtomicBool::new(*admission_rx.borrow()),
+    });
+
+    let shared = Arc::new(ApiShared {
+        stats,
+        ip_tracker,
+        me_pool,
+        upstream_manager,
+        config_path,
+        detected_ips_rx,
+        mutation_lock: Arc::new(Mutex::new(())),
+        minimal_cache: Arc::new(Mutex::new(None)),
+        runtime_edge_connections_cache: Arc::new(Mutex::new(None)),
+        runtime_edge_recompute_lock: Arc::new(Mutex::new(())),
+        runtime_events: Arc::new(ApiEventStore::new(
+            config_rx.borrow().server.api.runtime_edge_events_capacity,
+        )),
+        request_id: Arc::new(AtomicU64::new(1)),
+        runtime_state: runtime_state.clone(),
+        startup_tracker,
+        route_runtime,
+    });
+
+    spawn_runtime_watchers(
+        config_rx.clone(),
+        admission_rx.clone(),
+        runtime_state.clone(),
+        shared.runtime_events.clone(),
+    );
+
+    loop {
+        let (stream, peer) = match listener.accept().await {
+            Ok(v) => v,
+            Err(error) => {
+                warn!(error = %error, "API accept error");
+                continue;
+            }
+        };
+
+        let shared_conn = shared.clone();
+        let config_rx_conn = config_rx.clone();
+        tokio::spawn(async move {
+            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
+            {
+                debug!(error = %error, "API connection error");
+            }
+        });
+    }
+}
+
+async fn handle(
+    req: Request<Incoming>,
+    peer: SocketAddr,
+    shared: Arc<ApiShared>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+) -> Result<Response<Full<Bytes>>, Infallible> {
+    let request_id = shared.next_request_id();
+    let cfg = config_rx.borrow().clone();
+    let api_cfg = &cfg.server.api;
+
+    if !api_cfg.enabled {
+        return Ok(error_response(
+            request_id,
+            ApiFailure::new(
+                StatusCode::SERVICE_UNAVAILABLE,
+                "api_disabled",
+                "API is disabled",
+            ),
+        ));
+    }
+
+    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"),
+        ));
+    }
+
+    if !api_cfg.auth_header.is_empty() {
+        let auth_ok = req
+            .headers()
+            .get(AUTHORIZATION)
+            .and_then(|v| v.to_str().ok())
+            .map(|v| v == api_cfg.auth_header)
+            .unwrap_or(false);
+        if !auth_ok {
+            return Ok(error_response(
+                request_id,
+                ApiFailure::new(
+                    StatusCode::UNAUTHORIZED,
+                    "unauthorized",
+                    "Missing or invalid Authorization header",
+                ),
+            ));
+        }
+    }
+
+    let method = req.method().clone();
+    let path = req.uri().path().to_string();
+    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()) {
+            ("GET", "/v1/health") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = HealthData {
+                    status: "ok",
+                    read_only: api_cfg.read_only,
+                };
+                Ok(success_response(StatusCode::OK, 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);
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/gates") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_gates_data(shared.as_ref(), cfg.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/initialization") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_initialization_data(shared.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/limits/effective") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_limits_effective_data(cfg.as_ref());
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/security/posture") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_security_posture_data(cfg.as_ref());
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/security/whitelist") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_security_whitelist_data(cfg.as_ref());
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/stats/summary") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = SummaryData {
+                    uptime_seconds: shared.stats.uptime_secs(),
+                    connections_total: shared.stats.get_connects_all(),
+                    connections_bad_total: shared.stats.get_connects_bad(),
+                    handshake_timeouts_total: shared.stats.get_handshake_timeouts(),
+                    configured_users: cfg.access.users.len(),
+                };
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/stats/zero/all") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_zero_all_data(&shared.stats, cfg.access.users.len());
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/stats/upstreams") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_upstreams_data(shared.as_ref(), api_cfg);
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/stats/minimal/all") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_minimal_all_data(shared.as_ref(), api_cfg).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/stats/me-writers") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_me_writers_data(shared.as_ref(), api_cfg).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/stats/dcs") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_dcs_data(shared.as_ref(), api_cfg).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/me_pool_state") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_me_pool_state_data(shared.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/me_quality") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_me_quality_data(shared.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/upstream_quality") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_upstream_quality_data(shared.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/nat_stun") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_nat_stun_data(shared.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/me-selftest") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_me_selftest_data(shared.as_ref(), cfg.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/connections/summary") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_connections_summary_data(shared.as_ref(), cfg.as_ref()).await;
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/runtime/events/recent") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let data = build_runtime_events_recent_data(
+                    shared.as_ref(),
+                    cfg.as_ref(),
+                    query.as_deref(),
+                );
+                Ok(success_response(StatusCode::OK, data, revision))
+            }
+            ("GET", "/v1/stats/users") | ("GET", "/v1/users") => {
+                let revision = current_revision(&shared.config_path).await?;
+                let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+                let users = users_from_config(
+                    &cfg,
+                    &shared.stats,
+                    &shared.ip_tracker,
+                    detected_ip_v4,
+                    detected_ip_v6,
+                )
+                .await;
+                Ok(success_response(StatusCode::OK, users, revision))
+            }
+            ("POST", "/v1/users") => {
+                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_json::<CreateUserRequest>(req.into_body(), body_limit).await?;
+                let result = create_user(body, expected_revision, &shared).await;
+                let (data, revision) = match result {
+                    Ok(ok) => ok,
+                    Err(error) => {
+                        shared.runtime_events.record("api.user.create.failed", error.code);
+                        return Err(error);
+                    }
+                };
+                shared
+                    .runtime_events
+                    .record("api.user.create.ok", format!("username={}", data.user.username));
+                Ok(success_response(StatusCode::CREATED, data, revision))
+            }
+            _ => {
+                if let Some(user) = path.strip_prefix("/v1/users/")
+                    && !user.is_empty()
+                    && !user.contains('/')
+                {
+                    if method == Method::GET {
+                        let revision = current_revision(&shared.config_path).await?;
+                        let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+                        let users = users_from_config(
+                            &cfg,
+                            &shared.stats,
+                            &shared.ip_tracker,
+                            detected_ip_v4,
+                            detected_ip_v6,
+                        )
+                        .await;
+                        if let Some(user_info) = users.into_iter().find(|entry| entry.username == user)
+                        {
+                            return Ok(success_response(StatusCode::OK, user_info, revision));
+                        }
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "User not found"),
+                        ));
+                    }
+                    if method == Method::PATCH {
+                        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_json::<PatchUserRequest>(req.into_body(), body_limit).await?;
+                        let result = patch_user(user, body, expected_revision, &shared).await;
+                        let (data, revision) = match result {
+                            Ok(ok) => ok,
+                            Err(error) => {
+                                shared.runtime_events.record(
+                                    "api.user.patch.failed",
+                                    format!("username={} code={}", user, error.code),
+                                );
+                                return Err(error);
+                            }
+                        };
+                        shared
+                            .runtime_events
+                            .record("api.user.patch.ok", format!("username={}", data.username));
+                        return Ok(success_response(StatusCode::OK, data, revision));
+                    }
+                    if method == Method::DELETE {
+                        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 result = delete_user(user, expected_revision, &shared).await;
+                        let (deleted_user, revision) = match result {
+                            Ok(ok) => ok,
+                            Err(error) => {
+                                shared.runtime_events.record(
+                                    "api.user.delete.failed",
+                                    format!("username={} code={}", user, error.code),
+                                );
+                                return Err(error);
+                            }
+                        };
+                        shared.runtime_events.record(
+                            "api.user.delete.ok",
+                            format!("username={}", deleted_user),
+                        );
+                        return Ok(success_response(StatusCode::OK, deleted_user, 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 (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);
+                            }
+                        };
+                        shared.runtime_events.record(
+                            "api.user.rotate_secret.ok",
+                            format!("username={}", base_user),
+                        );
+                        return Ok(success_response(StatusCode::OK, data, revision));
+                    }
+                    if method == Method::POST {
+                        return Ok(error_response(
+                            request_id,
+                            ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "Route not found"),
+                        ));
+                    }
+                    return Ok(error_response(
+                        request_id,
+                        ApiFailure::new(
+                            StatusCode::METHOD_NOT_ALLOWED,
+                            "method_not_allowed",
+                            "Unsupported HTTP method for this route",
+                        ),
+                    ));
+                }
+                Ok(error_response(
+                    request_id,
+                    ApiFailure::new(StatusCode::NOT_FOUND, "not_found", "Route not found"),
+                ))
+            }
+        }
+    }
+    .await;
+
+    match result {
+        Ok(resp) => Ok(resp),
+        Err(error) => Ok(error_response(request_id, error)),
+    }
+}

src/api/model.rs

@@ -0,0 +1,487 @@
+use std::net::IpAddr;
+
+use chrono::{DateTime, Utc};
+use hyper::StatusCode;
+use rand::Rng;
+use serde::{Deserialize, Serialize};
+
+const MAX_USERNAME_LEN: usize = 64;
+
+#[derive(Debug)]
+pub(super) struct ApiFailure {
+    pub(super) status: StatusCode,
+    pub(super) code: &'static str,
+    pub(super) message: String,
+}
+
+impl ApiFailure {
+    pub(super) fn new(status: StatusCode, code: &'static str, message: impl Into<String>) -> Self {
+        Self {
+            status,
+            code,
+            message: message.into(),
+        }
+    }
+
+    pub(super) fn internal(message: impl Into<String>) -> Self {
+        Self::new(StatusCode::INTERNAL_SERVER_ERROR, "internal_error", message)
+    }
+
+    pub(super) fn bad_request(message: impl Into<String>) -> Self {
+        Self::new(StatusCode::BAD_REQUEST, "bad_request", message)
+    }
+}
+
+#[derive(Serialize)]
+pub(super) struct ErrorBody {
+    pub(super) code: &'static str,
+    pub(super) message: String,
+}
+
+#[derive(Serialize)]
+pub(super) struct ErrorResponse {
+    pub(super) ok: bool,
+    pub(super) error: ErrorBody,
+    pub(super) request_id: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct SuccessResponse<T> {
+    pub(super) ok: bool,
+    pub(super) data: T,
+    pub(super) revision: String,
+}
+
+#[derive(Serialize)]
+pub(super) struct HealthData {
+    pub(super) status: &'static str,
+    pub(super) read_only: bool,
+}
+
+#[derive(Serialize)]
+pub(super) struct SummaryData {
+    pub(super) uptime_seconds: f64,
+    pub(super) connections_total: u64,
+    pub(super) connections_bad_total: u64,
+    pub(super) handshake_timeouts_total: u64,
+    pub(super) configured_users: usize,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ZeroCodeCount {
+    pub(super) code: i32,
+    pub(super) total: u64,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ZeroCoreData {
+    pub(super) uptime_seconds: f64,
+    pub(super) connections_total: u64,
+    pub(super) connections_bad_total: u64,
+    pub(super) handshake_timeouts_total: u64,
+    pub(super) configured_users: usize,
+    pub(super) telemetry_core_enabled: bool,
+    pub(super) telemetry_user_enabled: bool,
+    pub(super) telemetry_me_level: String,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ZeroUpstreamData {
+    pub(super) connect_attempt_total: u64,
+    pub(super) connect_success_total: u64,
+    pub(super) connect_fail_total: u64,
+    pub(super) connect_failfast_hard_error_total: u64,
+    pub(super) connect_attempts_bucket_1: u64,
+    pub(super) connect_attempts_bucket_2: u64,
+    pub(super) connect_attempts_bucket_3_4: u64,
+    pub(super) connect_attempts_bucket_gt_4: u64,
+    pub(super) connect_duration_success_bucket_le_100ms: u64,
+    pub(super) connect_duration_success_bucket_101_500ms: u64,
+    pub(super) connect_duration_success_bucket_501_1000ms: u64,
+    pub(super) connect_duration_success_bucket_gt_1000ms: u64,
+    pub(super) connect_duration_fail_bucket_le_100ms: u64,
+    pub(super) connect_duration_fail_bucket_101_500ms: u64,
+    pub(super) connect_duration_fail_bucket_501_1000ms: u64,
+    pub(super) connect_duration_fail_bucket_gt_1000ms: u64,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct UpstreamDcStatus {
+    pub(super) dc: i16,
+    pub(super) latency_ema_ms: Option<f64>,
+    pub(super) ip_preference: &'static str,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct UpstreamStatus {
+    pub(super) upstream_id: usize,
+    pub(super) route_kind: &'static str,
+    pub(super) address: String,
+    pub(super) weight: u16,
+    pub(super) scopes: String,
+    pub(super) healthy: bool,
+    pub(super) fails: u32,
+    pub(super) last_check_age_secs: u64,
+    pub(super) effective_latency_ms: Option<f64>,
+    pub(super) dc: Vec<UpstreamDcStatus>,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct UpstreamSummaryData {
+    pub(super) configured_total: usize,
+    pub(super) healthy_total: usize,
+    pub(super) unhealthy_total: usize,
+    pub(super) direct_total: usize,
+    pub(super) socks4_total: usize,
+    pub(super) socks5_total: usize,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct UpstreamsData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    pub(super) zero: ZeroUpstreamData,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) summary: Option<UpstreamSummaryData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) upstreams: Option<Vec<UpstreamStatus>>,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ZeroMiddleProxyData {
+    pub(super) keepalive_sent_total: u64,
+    pub(super) keepalive_failed_total: u64,
+    pub(super) keepalive_pong_total: u64,
+    pub(super) keepalive_timeout_total: u64,
+    pub(super) rpc_proxy_req_signal_sent_total: u64,
+    pub(super) rpc_proxy_req_signal_failed_total: u64,
+    pub(super) rpc_proxy_req_signal_skipped_no_meta_total: u64,
+    pub(super) rpc_proxy_req_signal_response_total: u64,
+    pub(super) rpc_proxy_req_signal_close_sent_total: u64,
+    pub(super) reconnect_attempt_total: u64,
+    pub(super) reconnect_success_total: u64,
+    pub(super) handshake_reject_total: u64,
+    pub(super) handshake_error_codes: Vec<ZeroCodeCount>,
+    pub(super) reader_eof_total: u64,
+    pub(super) idle_close_by_peer_total: u64,
+    pub(super) route_drop_no_conn_total: u64,
+    pub(super) route_drop_channel_closed_total: u64,
+    pub(super) route_drop_queue_full_total: u64,
+    pub(super) route_drop_queue_full_base_total: u64,
+    pub(super) route_drop_queue_full_high_total: u64,
+    pub(super) socks_kdf_strict_reject_total: u64,
+    pub(super) socks_kdf_compat_fallback_total: u64,
+    pub(super) endpoint_quarantine_total: u64,
+    pub(super) kdf_drift_total: u64,
+    pub(super) kdf_port_only_drift_total: u64,
+    pub(super) hardswap_pending_reuse_total: u64,
+    pub(super) hardswap_pending_ttl_expired_total: u64,
+    pub(super) single_endpoint_outage_enter_total: u64,
+    pub(super) single_endpoint_outage_exit_total: u64,
+    pub(super) single_endpoint_outage_reconnect_attempt_total: u64,
+    pub(super) single_endpoint_outage_reconnect_success_total: u64,
+    pub(super) single_endpoint_quarantine_bypass_total: u64,
+    pub(super) single_endpoint_shadow_rotate_total: u64,
+    pub(super) single_endpoint_shadow_rotate_skipped_quarantine_total: u64,
+    pub(super) floor_mode_switch_total: u64,
+    pub(super) floor_mode_switch_static_to_adaptive_total: u64,
+    pub(super) floor_mode_switch_adaptive_to_static_total: u64,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ZeroPoolData {
+    pub(super) pool_swap_total: u64,
+    pub(super) pool_drain_active: u64,
+    pub(super) pool_force_close_total: u64,
+    pub(super) pool_stale_pick_total: u64,
+    pub(super) writer_removed_total: u64,
+    pub(super) writer_removed_unexpected_total: u64,
+    pub(super) refill_triggered_total: u64,
+    pub(super) refill_skipped_inflight_total: u64,
+    pub(super) refill_failed_total: u64,
+    pub(super) writer_restored_same_endpoint_total: u64,
+    pub(super) writer_restored_fallback_total: u64,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ZeroDesyncData {
+    pub(super) secure_padding_invalid_total: u64,
+    pub(super) desync_total: u64,
+    pub(super) desync_full_logged_total: u64,
+    pub(super) desync_suppressed_total: u64,
+    pub(super) desync_frames_bucket_0: u64,
+    pub(super) desync_frames_bucket_1_2: u64,
+    pub(super) desync_frames_bucket_3_10: u64,
+    pub(super) desync_frames_bucket_gt_10: u64,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct ZeroAllData {
+    pub(super) generated_at_epoch_secs: u64,
+    pub(super) core: ZeroCoreData,
+    pub(super) upstream: ZeroUpstreamData,
+    pub(super) middle_proxy: ZeroMiddleProxyData,
+    pub(super) pool: ZeroPoolData,
+    pub(super) desync: ZeroDesyncData,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MeWritersSummary {
+    pub(super) configured_dc_groups: usize,
+    pub(super) configured_endpoints: usize,
+    pub(super) available_endpoints: usize,
+    pub(super) available_pct: f64,
+    pub(super) required_writers: usize,
+    pub(super) alive_writers: usize,
+    pub(super) coverage_pct: f64,
+    pub(super) fresh_alive_writers: usize,
+    pub(super) fresh_coverage_pct: f64,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MeWriterStatus {
+    pub(super) writer_id: u64,
+    pub(super) dc: Option<i16>,
+    pub(super) endpoint: String,
+    pub(super) generation: u64,
+    pub(super) state: &'static str,
+    pub(super) draining: bool,
+    pub(super) degraded: bool,
+    pub(super) bound_clients: usize,
+    pub(super) idle_for_secs: Option<u64>,
+    pub(super) rtt_ema_ms: Option<f64>,
+    pub(super) matches_active_generation: bool,
+    pub(super) in_desired_map: bool,
+    pub(super) allow_drain_fallback: bool,
+    pub(super) drain_started_at_epoch_secs: Option<u64>,
+    pub(super) drain_deadline_epoch_secs: Option<u64>,
+    pub(super) drain_over_ttl: bool,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MeWritersData {
+    pub(super) middle_proxy_enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    pub(super) summary: MeWritersSummary,
+    pub(super) writers: Vec<MeWriterStatus>,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct DcStatus {
+    pub(super) dc: i16,
+    pub(super) endpoints: Vec<String>,
+    pub(super) endpoint_writers: Vec<DcEndpointWriters>,
+    pub(super) available_endpoints: usize,
+    pub(super) available_pct: f64,
+    pub(super) required_writers: usize,
+    pub(super) floor_min: usize,
+    pub(super) floor_target: usize,
+    pub(super) floor_max: usize,
+    pub(super) floor_capped: bool,
+    pub(super) alive_writers: usize,
+    pub(super) coverage_pct: f64,
+    pub(super) fresh_alive_writers: usize,
+    pub(super) fresh_coverage_pct: f64,
+    pub(super) rtt_ms: Option<f64>,
+    pub(super) load: usize,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct DcEndpointWriters {
+    pub(super) endpoint: String,
+    pub(super) active_writers: usize,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct DcStatusData {
+    pub(super) middle_proxy_enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    pub(super) dcs: Vec<DcStatus>,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MinimalQuarantineData {
+    pub(super) endpoint: String,
+    pub(super) remaining_ms: u64,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MinimalDcPathData {
+    pub(super) dc: i16,
+    pub(super) ip_preference: Option<&'static str>,
+    pub(super) selected_addr_v4: Option<String>,
+    pub(super) selected_addr_v6: Option<String>,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MinimalMeRuntimeData {
+    pub(super) active_generation: u64,
+    pub(super) warm_generation: u64,
+    pub(super) pending_hardswap_generation: u64,
+    pub(super) pending_hardswap_age_secs: Option<u64>,
+    pub(super) hardswap_enabled: bool,
+    pub(super) floor_mode: &'static str,
+    pub(super) adaptive_floor_idle_secs: u64,
+    pub(super) adaptive_floor_min_writers_single_endpoint: u8,
+    pub(super) adaptive_floor_min_writers_multi_endpoint: u8,
+    pub(super) adaptive_floor_recover_grace_secs: u64,
+    pub(super) adaptive_floor_writers_per_core_total: u16,
+    pub(super) adaptive_floor_cpu_cores_override: u16,
+    pub(super) adaptive_floor_max_extra_writers_single_per_core: u16,
+    pub(super) adaptive_floor_max_extra_writers_multi_per_core: u16,
+    pub(super) adaptive_floor_max_active_writers_per_core: u16,
+    pub(super) adaptive_floor_max_warm_writers_per_core: u16,
+    pub(super) adaptive_floor_max_active_writers_global: u32,
+    pub(super) adaptive_floor_max_warm_writers_global: u32,
+    pub(super) adaptive_floor_cpu_cores_detected: u32,
+    pub(super) adaptive_floor_cpu_cores_effective: u32,
+    pub(super) adaptive_floor_global_cap_raw: u64,
+    pub(super) adaptive_floor_global_cap_effective: u64,
+    pub(super) adaptive_floor_target_writers_total: u64,
+    pub(super) adaptive_floor_active_cap_configured: u64,
+    pub(super) adaptive_floor_active_cap_effective: u64,
+    pub(super) adaptive_floor_warm_cap_configured: u64,
+    pub(super) adaptive_floor_warm_cap_effective: u64,
+    pub(super) adaptive_floor_active_writers_current: u64,
+    pub(super) adaptive_floor_warm_writers_current: u64,
+    pub(super) me_keepalive_enabled: bool,
+    pub(super) me_keepalive_interval_secs: u64,
+    pub(super) me_keepalive_jitter_secs: u64,
+    pub(super) me_keepalive_payload_random: bool,
+    pub(super) rpc_proxy_req_every_secs: u64,
+    pub(super) me_reconnect_max_concurrent_per_dc: u32,
+    pub(super) me_reconnect_backoff_base_ms: u64,
+    pub(super) me_reconnect_backoff_cap_ms: u64,
+    pub(super) me_reconnect_fast_retry_count: u32,
+    pub(super) me_pool_drain_ttl_secs: u64,
+    pub(super) me_pool_force_close_secs: u64,
+    pub(super) me_pool_min_fresh_ratio: f32,
+    pub(super) me_bind_stale_mode: &'static str,
+    pub(super) me_bind_stale_ttl_secs: u64,
+    pub(super) me_single_endpoint_shadow_writers: u8,
+    pub(super) me_single_endpoint_outage_mode_enabled: bool,
+    pub(super) me_single_endpoint_outage_disable_quarantine: bool,
+    pub(super) me_single_endpoint_outage_backoff_min_ms: u64,
+    pub(super) me_single_endpoint_outage_backoff_max_ms: u64,
+    pub(super) me_single_endpoint_shadow_rotate_every_secs: u64,
+    pub(super) me_deterministic_writer_sort: bool,
+    pub(super) me_writer_pick_mode: &'static str,
+    pub(super) me_writer_pick_sample_size: u8,
+    pub(super) me_socks_kdf_policy: &'static str,
+    pub(super) quarantined_endpoints_total: usize,
+    pub(super) quarantined_endpoints: Vec<MinimalQuarantineData>,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MinimalAllPayload {
+    pub(super) me_writers: MeWritersData,
+    pub(super) dcs: DcStatusData,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) me_runtime: Option<MinimalMeRuntimeData>,
+    pub(super) network_path: Vec<MinimalDcPathData>,
+}
+
+#[derive(Serialize, Clone)]
+pub(super) struct MinimalAllData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<MinimalAllPayload>,
+}
+
+#[derive(Serialize)]
+pub(super) struct UserLinks {
+    pub(super) classic: Vec<String>,
+    pub(super) secure: Vec<String>,
+    pub(super) tls: Vec<String>,
+}
+
+#[derive(Serialize)]
+pub(super) struct UserInfo {
+    pub(super) username: 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>,
+    pub(super) current_connections: u64,
+    pub(super) active_unique_ips: usize,
+    pub(super) active_unique_ips_list: Vec<IpAddr>,
+    pub(super) recent_unique_ips: usize,
+    pub(super) recent_unique_ips_list: Vec<IpAddr>,
+    pub(super) total_octets: u64,
+    pub(super) links: UserLinks,
+}
+
+#[derive(Serialize)]
+pub(super) struct CreateUserResponse {
+    pub(super) user: UserInfo,
+    pub(super) secret: String,
+}
+
+#[derive(Deserialize)]
+pub(super) struct CreateUserRequest {
+    pub(super) username: String,
+    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>,
+}
+
+#[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>,
+}
+
+#[derive(Default, Deserialize)]
+pub(super) struct RotateSecretRequest {
+    pub(super) secret: Option<String>,
+}
+
+pub(super) fn parse_optional_expiration(
+    value: Option<&str>,
+) -> Result<Option<DateTime<Utc>>, ApiFailure> {
+    let Some(raw) = value else {
+        return Ok(None);
+    };
+    let parsed = DateTime::parse_from_rfc3339(raw)
+        .map_err(|_| ApiFailure::bad_request("expiration_rfc3339 must be valid RFC3339"))?;
+    Ok(Some(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())
+}
+
+pub(super) fn is_valid_ad_tag(tag: &str) -> bool {
+    tag.len() == 32 && tag.chars().all(|c| c.is_ascii_hexdigit())
+}
+
+pub(super) fn is_valid_username(user: &str) -> bool {
+    !user.is_empty()
+        && user.len() <= MAX_USERNAME_LEN
+        && user
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '_' | '-' | '.'))
+}
+
+pub(super) fn random_user_secret() -> String {
+    let mut bytes = [0u8; 16];
+    rand::rng().fill(&mut bytes);
+    hex::encode(bytes)
+}

src/api/runtime_edge.rs

@@ -0,0 +1,294 @@
+use std::cmp::Reverse;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use serde::Serialize;
+
+use crate::config::ProxyConfig;
+
+use super::ApiShared;
+use super::events::ApiEventRecord;
+
+const FEATURE_DISABLED_REASON: &str = "feature_disabled";
+const SOURCE_UNAVAILABLE_REASON: &str = "source_unavailable";
+const EVENTS_DEFAULT_LIMIT: usize = 50;
+const EVENTS_MAX_LIMIT: usize = 1000;
+
+#[derive(Clone, Serialize)]
+pub(super) struct RuntimeEdgeConnectionUserData {
+    pub(super) username: String,
+    pub(super) current_connections: u64,
+    pub(super) total_octets: u64,
+}
+
+#[derive(Clone, Serialize)]
+pub(super) struct RuntimeEdgeConnectionTotalsData {
+    pub(super) current_connections: u64,
+    pub(super) current_connections_me: u64,
+    pub(super) current_connections_direct: u64,
+    pub(super) active_users: usize,
+}
+
+#[derive(Clone, Serialize)]
+pub(super) struct RuntimeEdgeConnectionTopData {
+    pub(super) limit: usize,
+    pub(super) by_connections: Vec<RuntimeEdgeConnectionUserData>,
+    pub(super) by_throughput: Vec<RuntimeEdgeConnectionUserData>,
+}
+
+#[derive(Clone, Serialize)]
+pub(super) struct RuntimeEdgeConnectionCacheData {
+    pub(super) ttl_ms: u64,
+    pub(super) served_from_cache: bool,
+    pub(super) stale_cache_used: bool,
+}
+
+#[derive(Clone, Serialize)]
+pub(super) struct RuntimeEdgeConnectionTelemetryData {
+    pub(super) user_enabled: bool,
+    pub(super) throughput_is_cumulative: bool,
+}
+
+#[derive(Clone, Serialize)]
+pub(super) struct RuntimeEdgeConnectionsSummaryPayload {
+    pub(super) cache: RuntimeEdgeConnectionCacheData,
+    pub(super) totals: RuntimeEdgeConnectionTotalsData,
+    pub(super) top: RuntimeEdgeConnectionTopData,
+    pub(super) telemetry: RuntimeEdgeConnectionTelemetryData,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeEdgeConnectionsSummaryData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeEdgeConnectionsSummaryPayload>,
+}
+
+#[derive(Clone)]
+pub(crate) struct EdgeConnectionsCacheEntry {
+    pub(super) expires_at: Instant,
+    pub(super) payload: RuntimeEdgeConnectionsSummaryPayload,
+    pub(super) generated_at_epoch_secs: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeEdgeEventsPayload {
+    pub(super) capacity: usize,
+    pub(super) dropped_total: u64,
+    pub(super) events: Vec<ApiEventRecord>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeEdgeEventsData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeEdgeEventsPayload>,
+}
+
+pub(super) async fn build_runtime_connections_summary_data(
+    shared: &ApiShared,
+    cfg: &ProxyConfig,
+) -> RuntimeEdgeConnectionsSummaryData {
+    let now_epoch_secs = now_epoch_secs();
+    let api_cfg = &cfg.server.api;
+    if !api_cfg.runtime_edge_enabled {
+        return RuntimeEdgeConnectionsSummaryData {
+            enabled: false,
+            reason: Some(FEATURE_DISABLED_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    }
+
+    let (generated_at_epoch_secs, payload) = match get_connections_payload_cached(
+        shared,
+        api_cfg.runtime_edge_cache_ttl_ms,
+        api_cfg.runtime_edge_top_n,
+    )
+    .await
+    {
+        Some(v) => v,
+        None => {
+            return RuntimeEdgeConnectionsSummaryData {
+                enabled: true,
+                reason: Some(SOURCE_UNAVAILABLE_REASON),
+                generated_at_epoch_secs: now_epoch_secs,
+                data: None,
+            };
+        }
+    };
+
+    RuntimeEdgeConnectionsSummaryData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs,
+        data: Some(payload),
+    }
+}
+
+pub(super) fn build_runtime_events_recent_data(
+    shared: &ApiShared,
+    cfg: &ProxyConfig,
+    query: Option<&str>,
+) -> RuntimeEdgeEventsData {
+    let now_epoch_secs = now_epoch_secs();
+    let api_cfg = &cfg.server.api;
+    if !api_cfg.runtime_edge_enabled {
+        return RuntimeEdgeEventsData {
+            enabled: false,
+            reason: Some(FEATURE_DISABLED_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    }
+
+    let limit = parse_recent_events_limit(query, EVENTS_DEFAULT_LIMIT, EVENTS_MAX_LIMIT);
+    let snapshot = shared.runtime_events.snapshot(limit);
+
+    RuntimeEdgeEventsData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: now_epoch_secs,
+        data: Some(RuntimeEdgeEventsPayload {
+            capacity: snapshot.capacity,
+            dropped_total: snapshot.dropped_total,
+            events: snapshot.events,
+        }),
+    }
+}
+
+async fn get_connections_payload_cached(
+    shared: &ApiShared,
+    cache_ttl_ms: u64,
+    top_n: usize,
+) -> Option<(u64, RuntimeEdgeConnectionsSummaryPayload)> {
+    if cache_ttl_ms > 0 {
+        let now = Instant::now();
+        let cached = shared.runtime_edge_connections_cache.lock().await.clone();
+        if let Some(entry) = cached
+            && now < entry.expires_at
+        {
+            let mut payload = entry.payload;
+            payload.cache.served_from_cache = true;
+            payload.cache.stale_cache_used = false;
+            return Some((entry.generated_at_epoch_secs, payload));
+        }
+    }
+
+    let Ok(_guard) = shared.runtime_edge_recompute_lock.try_lock() else {
+        let cached = shared.runtime_edge_connections_cache.lock().await.clone();
+        if let Some(entry) = cached {
+            let mut payload = entry.payload;
+            payload.cache.served_from_cache = true;
+            payload.cache.stale_cache_used = true;
+            return Some((entry.generated_at_epoch_secs, payload));
+        }
+        return None;
+    };
+
+    let generated_at_epoch_secs = now_epoch_secs();
+    let payload = recompute_connections_payload(shared, cache_ttl_ms, top_n).await;
+
+    if cache_ttl_ms > 0 {
+        let entry = EdgeConnectionsCacheEntry {
+            expires_at: Instant::now() + Duration::from_millis(cache_ttl_ms),
+            payload: payload.clone(),
+            generated_at_epoch_secs,
+        };
+        *shared.runtime_edge_connections_cache.lock().await = Some(entry);
+    }
+
+    Some((generated_at_epoch_secs, payload))
+}
+
+async fn recompute_connections_payload(
+    shared: &ApiShared,
+    cache_ttl_ms: u64,
+    top_n: usize,
+) -> RuntimeEdgeConnectionsSummaryPayload {
+    let mut rows = Vec::<RuntimeEdgeConnectionUserData>::new();
+    let mut active_users = 0usize;
+    for entry in shared.stats.iter_user_stats() {
+        let user_stats = entry.value();
+        let current_connections = user_stats
+            .curr_connects
+            .load(std::sync::atomic::Ordering::Relaxed);
+        let total_octets = user_stats
+            .octets_from_client
+            .load(std::sync::atomic::Ordering::Relaxed)
+            .saturating_add(
+                user_stats
+                    .octets_to_client
+                    .load(std::sync::atomic::Ordering::Relaxed),
+            );
+        if current_connections > 0 {
+            active_users = active_users.saturating_add(1);
+        }
+        rows.push(RuntimeEdgeConnectionUserData {
+            username: entry.key().clone(),
+            current_connections,
+            total_octets,
+        });
+    }
+
+    let limit = top_n.max(1);
+    let mut by_connections = rows.clone();
+    by_connections.sort_by_key(|row| (Reverse(row.current_connections), row.username.clone()));
+    by_connections.truncate(limit);
+
+    let mut by_throughput = rows;
+    by_throughput.sort_by_key(|row| (Reverse(row.total_octets), row.username.clone()));
+    by_throughput.truncate(limit);
+
+    let telemetry = shared.stats.telemetry_policy();
+    RuntimeEdgeConnectionsSummaryPayload {
+        cache: RuntimeEdgeConnectionCacheData {
+            ttl_ms: cache_ttl_ms,
+            served_from_cache: false,
+            stale_cache_used: false,
+        },
+        totals: RuntimeEdgeConnectionTotalsData {
+            current_connections: shared.stats.get_current_connections_total(),
+            current_connections_me: shared.stats.get_current_connections_me(),
+            current_connections_direct: shared.stats.get_current_connections_direct(),
+            active_users,
+        },
+        top: RuntimeEdgeConnectionTopData {
+            limit,
+            by_connections,
+            by_throughput,
+        },
+        telemetry: RuntimeEdgeConnectionTelemetryData {
+            user_enabled: telemetry.user_enabled,
+            throughput_is_cumulative: true,
+        },
+    }
+}
+
+fn parse_recent_events_limit(query: Option<&str>, default_limit: usize, max_limit: usize) -> usize {
+    let Some(query) = query else {
+        return default_limit;
+    };
+    for pair in query.split('&') {
+        let mut split = pair.splitn(2, '=');
+        if split.next() == Some("limit")
+            && let Some(raw) = split.next()
+            && let Ok(parsed) = raw.parse::<usize>()
+        {
+            return parsed.clamp(1, max_limit);
+        }
+    }
+    default_limit
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_init.rs

@@ -0,0 +1,186 @@
+use serde::Serialize;
+
+use crate::startup::{
+    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,
+    StartupComponentStatus, StartupMeStatus, compute_progress_pct,
+};
+
+use super::ApiShared;
+
+#[derive(Serialize)]
+pub(super) struct RuntimeInitializationComponentData {
+    pub(super) id: &'static str,
+    pub(super) title: &'static str,
+    pub(super) status: &'static str,
+    pub(super) started_at_epoch_ms: Option<u64>,
+    pub(super) finished_at_epoch_ms: Option<u64>,
+    pub(super) duration_ms: Option<u64>,
+    pub(super) attempts: u32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) details: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeInitializationMeData {
+    pub(super) status: &'static str,
+    pub(super) current_stage: String,
+    pub(super) progress_pct: f64,
+    pub(super) init_attempt: u32,
+    pub(super) retry_limit: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_error: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeInitializationData {
+    pub(super) status: &'static str,
+    pub(super) degraded: bool,
+    pub(super) current_stage: String,
+    pub(super) progress_pct: f64,
+    pub(super) started_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) ready_at_epoch_secs: Option<u64>,
+    pub(super) total_elapsed_ms: u64,
+    pub(super) transport_mode: String,
+    pub(super) me: RuntimeInitializationMeData,
+    pub(super) components: Vec<RuntimeInitializationComponentData>,
+}
+
+#[derive(Clone)]
+pub(super) struct RuntimeStartupSummaryData {
+    pub(super) status: &'static str,
+    pub(super) stage: String,
+    pub(super) progress_pct: f64,
+}
+
+pub(super) async fn build_runtime_startup_summary(shared: &ApiShared) -> RuntimeStartupSummaryData {
+    let snapshot = shared.startup_tracker.snapshot().await;
+    let me_pool_progress = current_me_pool_stage_progress(shared).await;
+    let progress_pct = compute_progress_pct(&snapshot, me_pool_progress);
+    RuntimeStartupSummaryData {
+        status: snapshot.status.as_str(),
+        stage: snapshot.current_stage,
+        progress_pct,
+    }
+}
+
+pub(super) async fn build_runtime_initialization_data(
+    shared: &ApiShared,
+) -> RuntimeInitializationData {
+    let snapshot = shared.startup_tracker.snapshot().await;
+    let me_pool_progress = current_me_pool_stage_progress(shared).await;
+    let progress_pct = compute_progress_pct(&snapshot, me_pool_progress);
+    let me_progress_pct = compute_me_progress_pct(&snapshot, me_pool_progress);
+
+    RuntimeInitializationData {
+        status: snapshot.status.as_str(),
+        degraded: snapshot.degraded,
+        current_stage: snapshot.current_stage,
+        progress_pct,
+        started_at_epoch_secs: snapshot.started_at_epoch_secs,
+        ready_at_epoch_secs: snapshot.ready_at_epoch_secs,
+        total_elapsed_ms: snapshot.total_elapsed_ms,
+        transport_mode: snapshot.transport_mode,
+        me: RuntimeInitializationMeData {
+            status: snapshot.me.status.as_str(),
+            current_stage: snapshot.me.current_stage,
+            progress_pct: me_progress_pct,
+            init_attempt: snapshot.me.init_attempt,
+            retry_limit: snapshot.me.retry_limit,
+            last_error: snapshot.me.last_error,
+        },
+        components: snapshot
+            .components
+            .into_iter()
+            .map(|component| RuntimeInitializationComponentData {
+                id: component.id,
+                title: component.title,
+                status: component.status.as_str(),
+                started_at_epoch_ms: component.started_at_epoch_ms,
+                finished_at_epoch_ms: component.finished_at_epoch_ms,
+                duration_ms: component.duration_ms,
+                attempts: component.attempts,
+                details: component.details,
+            })
+            .collect(),
+    }
+}
+
+fn compute_me_progress_pct(
+    snapshot: &crate::startup::StartupSnapshot,
+    me_pool_progress: Option<f64>,
+) -> f64 {
+    match snapshot.me.status {
+        StartupMeStatus::Pending => 0.0,
+        StartupMeStatus::Ready | StartupMeStatus::Failed | StartupMeStatus::Skipped => 100.0,
+        StartupMeStatus::Initializing => {
+            let mut total_weight = 0.0f64;
+            let mut completed_weight = 0.0f64;
+            for component in &snapshot.components {
+                if !is_me_component(component.id) {
+                    continue;
+                }
+                total_weight += component.weight;
+                let unit_progress = match component.status {
+                    StartupComponentStatus::Pending => 0.0,
+                    StartupComponentStatus::Running => {
+                        if component.id == COMPONENT_ME_POOL_INIT_STAGE1 {
+                            me_pool_progress.unwrap_or(0.0).clamp(0.0, 1.0)
+                        } else {
+                            0.0
+                        }
+                    }
+                    StartupComponentStatus::Ready
+                    | StartupComponentStatus::Failed
+                    | StartupComponentStatus::Skipped => 1.0,
+                };
+                completed_weight += component.weight * unit_progress;
+            }
+            if total_weight <= f64::EPSILON {
+                0.0
+            } else {
+                ((completed_weight / total_weight) * 100.0).clamp(0.0, 100.0)
+            }
+        }
+    }
+}
+
+fn is_me_component(component_id: &str) -> bool {
+    matches!(
+        component_id,
+        COMPONENT_ME_SECRET_FETCH
+            | COMPONENT_ME_PROXY_CONFIG_V4
+            | COMPONENT_ME_PROXY_CONFIG_V6
+            | COMPONENT_ME_POOL_CONSTRUCT
+            | COMPONENT_ME_POOL_INIT_STAGE1
+            | COMPONENT_ME_CONNECTIVITY_PING
+    )
+}
+
+async fn current_me_pool_stage_progress(shared: &ApiShared) -> Option<f64> {
+    let snapshot = shared.startup_tracker.snapshot().await;
+    if snapshot.me.status != StartupMeStatus::Initializing {
+        return None;
+    }
+
+    let pool = shared.me_pool.read().await.clone()?;
+    let status = pool.api_status_snapshot().await;
+    let configured_dc_groups = status.configured_dc_groups;
+    let covered_dc_groups = status
+        .dcs
+        .iter()
+        .filter(|dc| dc.alive_writers > 0)
+        .count();
+
+    let dc_coverage = ratio_01(covered_dc_groups, configured_dc_groups);
+    let writer_coverage = ratio_01(status.alive_writers, status.required_writers);
+    Some((0.7 * dc_coverage + 0.3 * writer_coverage).clamp(0.0, 1.0))
+}
+
+fn ratio_01(part: usize, total: usize) -> f64 {
+    if total == 0 {
+        return 0.0;
+    }
+    ((part as f64) / (total as f64)).clamp(0.0, 1.0)
+}

src/api/runtime_min.rs

@@ -0,0 +1,534 @@
+use std::collections::BTreeSet;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::Serialize;
+
+use crate::config::ProxyConfig;
+
+use super::ApiShared;
+
+const SOURCE_UNAVAILABLE_REASON: &str = "source_unavailable";
+
+#[derive(Serialize)]
+pub(super) struct SecurityWhitelistData {
+    pub(super) generated_at_epoch_secs: u64,
+    pub(super) enabled: bool,
+    pub(super) entries_total: usize,
+    pub(super) entries: Vec<String>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateGenerationData {
+    pub(super) active_generation: u64,
+    pub(super) warm_generation: u64,
+    pub(super) pending_hardswap_generation: u64,
+    pub(super) pending_hardswap_age_secs: Option<u64>,
+    pub(super) draining_generations: Vec<u64>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateHardswapData {
+    pub(super) enabled: bool,
+    pub(super) pending: bool,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateWriterContourData {
+    pub(super) warm: usize,
+    pub(super) active: usize,
+    pub(super) draining: usize,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateWriterHealthData {
+    pub(super) healthy: usize,
+    pub(super) degraded: usize,
+    pub(super) draining: usize,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateWriterData {
+    pub(super) total: usize,
+    pub(super) alive_non_draining: usize,
+    pub(super) draining: usize,
+    pub(super) degraded: usize,
+    pub(super) contour: RuntimeMePoolStateWriterContourData,
+    pub(super) health: RuntimeMePoolStateWriterHealthData,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateRefillDcData {
+    pub(super) dc: i16,
+    pub(super) family: &'static str,
+    pub(super) inflight: usize,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateRefillData {
+    pub(super) inflight_endpoints_total: usize,
+    pub(super) inflight_dc_total: usize,
+    pub(super) by_dc: Vec<RuntimeMePoolStateRefillDcData>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStatePayload {
+    pub(super) generations: RuntimeMePoolStateGenerationData,
+    pub(super) hardswap: RuntimeMePoolStateHardswapData,
+    pub(super) writers: RuntimeMePoolStateWriterData,
+    pub(super) refill: RuntimeMePoolStateRefillData,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMePoolStateData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeMePoolStatePayload>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeQualityCountersData {
+    pub(super) idle_close_by_peer_total: u64,
+    pub(super) reader_eof_total: u64,
+    pub(super) kdf_drift_total: u64,
+    pub(super) kdf_port_only_drift_total: u64,
+    pub(super) reconnect_attempt_total: u64,
+    pub(super) reconnect_success_total: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeQualityRouteDropData {
+    pub(super) no_conn_total: u64,
+    pub(super) channel_closed_total: u64,
+    pub(super) queue_full_total: u64,
+    pub(super) queue_full_base_total: u64,
+    pub(super) queue_full_high_total: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeQualityDcRttData {
+    pub(super) dc: i16,
+    pub(super) rtt_ema_ms: Option<f64>,
+    pub(super) alive_writers: usize,
+    pub(super) required_writers: usize,
+    pub(super) coverage_pct: f64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeQualityPayload {
+    pub(super) counters: RuntimeMeQualityCountersData,
+    pub(super) route_drops: RuntimeMeQualityRouteDropData,
+    pub(super) dc_rtt: Vec<RuntimeMeQualityDcRttData>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeQualityData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeMeQualityPayload>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeUpstreamQualityPolicyData {
+    pub(super) connect_retry_attempts: u32,
+    pub(super) connect_retry_backoff_ms: u64,
+    pub(super) connect_budget_ms: u64,
+    pub(super) unhealthy_fail_threshold: u32,
+    pub(super) connect_failfast_hard_errors: bool,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeUpstreamQualityCountersData {
+    pub(super) connect_attempt_total: u64,
+    pub(super) connect_success_total: u64,
+    pub(super) connect_fail_total: u64,
+    pub(super) connect_failfast_hard_error_total: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeUpstreamQualitySummaryData {
+    pub(super) configured_total: usize,
+    pub(super) healthy_total: usize,
+    pub(super) unhealthy_total: usize,
+    pub(super) direct_total: usize,
+    pub(super) socks4_total: usize,
+    pub(super) socks5_total: usize,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeUpstreamQualityDcData {
+    pub(super) dc: i16,
+    pub(super) latency_ema_ms: Option<f64>,
+    pub(super) ip_preference: &'static str,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeUpstreamQualityUpstreamData {
+    pub(super) upstream_id: usize,
+    pub(super) route_kind: &'static str,
+    pub(super) address: String,
+    pub(super) weight: u16,
+    pub(super) scopes: String,
+    pub(super) healthy: bool,
+    pub(super) fails: u32,
+    pub(super) last_check_age_secs: u64,
+    pub(super) effective_latency_ms: Option<f64>,
+    pub(super) dc: Vec<RuntimeUpstreamQualityDcData>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeUpstreamQualityData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    pub(super) policy: RuntimeUpstreamQualityPolicyData,
+    pub(super) counters: RuntimeUpstreamQualityCountersData,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) summary: Option<RuntimeUpstreamQualitySummaryData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) upstreams: Option<Vec<RuntimeUpstreamQualityUpstreamData>>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeNatStunReflectionData {
+    pub(super) addr: String,
+    pub(super) age_secs: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeNatStunFlagsData {
+    pub(super) nat_probe_enabled: bool,
+    pub(super) nat_probe_disabled_runtime: bool,
+    pub(super) nat_probe_attempts: u8,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeNatStunServersData {
+    pub(super) configured: Vec<String>,
+    pub(super) live: Vec<String>,
+    pub(super) live_total: usize,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeNatStunReflectionBlockData {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) v4: Option<RuntimeNatStunReflectionData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) v6: Option<RuntimeNatStunReflectionData>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeNatStunPayload {
+    pub(super) flags: RuntimeNatStunFlagsData,
+    pub(super) servers: RuntimeNatStunServersData,
+    pub(super) reflection: RuntimeNatStunReflectionBlockData,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) stun_backoff_remaining_ms: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeNatStunData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeNatStunPayload>,
+}
+
+pub(super) fn build_security_whitelist_data(cfg: &ProxyConfig) -> SecurityWhitelistData {
+    let entries = cfg
+        .server
+        .api
+        .whitelist
+        .iter()
+        .map(ToString::to_string)
+        .collect::<Vec<_>>();
+    SecurityWhitelistData {
+        generated_at_epoch_secs: now_epoch_secs(),
+        enabled: !entries.is_empty(),
+        entries_total: entries.len(),
+        entries,
+    }
+}
+
+pub(super) async fn build_runtime_me_pool_state_data(shared: &ApiShared) -> RuntimeMePoolStateData {
+    let now_epoch_secs = now_epoch_secs();
+    let Some(pool) = shared.me_pool.read().await.clone() else {
+        return RuntimeMePoolStateData {
+            enabled: false,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    };
+
+    let status = pool.api_status_snapshot().await;
+    let runtime = pool.api_runtime_snapshot().await;
+    let refill = pool.api_refill_snapshot().await;
+
+    let mut draining_generations = BTreeSet::<u64>::new();
+    let mut contour_warm = 0usize;
+    let mut contour_active = 0usize;
+    let mut contour_draining = 0usize;
+    let mut draining = 0usize;
+    let mut degraded = 0usize;
+    let mut healthy = 0usize;
+
+    for writer in &status.writers {
+        if writer.draining {
+            draining_generations.insert(writer.generation);
+            draining += 1;
+        }
+        if writer.degraded && !writer.draining {
+            degraded += 1;
+        }
+        if !writer.degraded && !writer.draining {
+            healthy += 1;
+        }
+        match writer.state {
+            "warm" => contour_warm += 1,
+            "active" => contour_active += 1,
+            _ => contour_draining += 1,
+        }
+    }
+
+    RuntimeMePoolStateData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: status.generated_at_epoch_secs,
+        data: Some(RuntimeMePoolStatePayload {
+            generations: RuntimeMePoolStateGenerationData {
+                active_generation: runtime.active_generation,
+                warm_generation: runtime.warm_generation,
+                pending_hardswap_generation: runtime.pending_hardswap_generation,
+                pending_hardswap_age_secs: runtime.pending_hardswap_age_secs,
+                draining_generations: draining_generations.into_iter().collect(),
+            },
+            hardswap: RuntimeMePoolStateHardswapData {
+                enabled: runtime.hardswap_enabled,
+                pending: runtime.pending_hardswap_generation != 0,
+            },
+            writers: RuntimeMePoolStateWriterData {
+                total: status.writers.len(),
+                alive_non_draining: status.writers.len().saturating_sub(draining),
+                draining,
+                degraded,
+                contour: RuntimeMePoolStateWriterContourData {
+                    warm: contour_warm,
+                    active: contour_active,
+                    draining: contour_draining,
+                },
+                health: RuntimeMePoolStateWriterHealthData {
+                    healthy,
+                    degraded,
+                    draining,
+                },
+            },
+            refill: RuntimeMePoolStateRefillData {
+                inflight_endpoints_total: refill.inflight_endpoints_total,
+                inflight_dc_total: refill.inflight_dc_total,
+                by_dc: refill
+                    .by_dc
+                    .into_iter()
+                    .map(|entry| RuntimeMePoolStateRefillDcData {
+                        dc: entry.dc,
+                        family: entry.family,
+                        inflight: entry.inflight,
+                    })
+                    .collect(),
+            },
+        }),
+    }
+}
+
+pub(super) async fn build_runtime_me_quality_data(shared: &ApiShared) -> RuntimeMeQualityData {
+    let now_epoch_secs = now_epoch_secs();
+    let Some(pool) = shared.me_pool.read().await.clone() else {
+        return RuntimeMeQualityData {
+            enabled: false,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    };
+
+    let status = pool.api_status_snapshot().await;
+    RuntimeMeQualityData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: status.generated_at_epoch_secs,
+        data: Some(RuntimeMeQualityPayload {
+            counters: RuntimeMeQualityCountersData {
+                idle_close_by_peer_total: shared.stats.get_me_idle_close_by_peer_total(),
+                reader_eof_total: shared.stats.get_me_reader_eof_total(),
+                kdf_drift_total: shared.stats.get_me_kdf_drift_total(),
+                kdf_port_only_drift_total: shared.stats.get_me_kdf_port_only_drift_total(),
+                reconnect_attempt_total: shared.stats.get_me_reconnect_attempts(),
+                reconnect_success_total: shared.stats.get_me_reconnect_success(),
+            },
+            route_drops: RuntimeMeQualityRouteDropData {
+                no_conn_total: shared.stats.get_me_route_drop_no_conn(),
+                channel_closed_total: shared.stats.get_me_route_drop_channel_closed(),
+                queue_full_total: shared.stats.get_me_route_drop_queue_full(),
+                queue_full_base_total: shared.stats.get_me_route_drop_queue_full_base(),
+                queue_full_high_total: shared.stats.get_me_route_drop_queue_full_high(),
+            },
+            dc_rtt: status
+                .dcs
+                .into_iter()
+                .map(|dc| RuntimeMeQualityDcRttData {
+                    dc: dc.dc,
+                    rtt_ema_ms: dc.rtt_ms,
+                    alive_writers: dc.alive_writers,
+                    required_writers: dc.required_writers,
+                    coverage_pct: dc.coverage_pct,
+                })
+                .collect(),
+        }),
+    }
+}
+
+pub(super) async fn build_runtime_upstream_quality_data(
+    shared: &ApiShared,
+) -> RuntimeUpstreamQualityData {
+    let generated_at_epoch_secs = now_epoch_secs();
+    let policy = shared.upstream_manager.api_policy_snapshot();
+    let counters = RuntimeUpstreamQualityCountersData {
+        connect_attempt_total: shared.stats.get_upstream_connect_attempt_total(),
+        connect_success_total: shared.stats.get_upstream_connect_success_total(),
+        connect_fail_total: shared.stats.get_upstream_connect_fail_total(),
+        connect_failfast_hard_error_total: shared.stats.get_upstream_connect_failfast_hard_error_total(),
+    };
+
+    let Some(snapshot) = shared.upstream_manager.try_api_snapshot() else {
+        return RuntimeUpstreamQualityData {
+            enabled: false,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs,
+            policy: RuntimeUpstreamQualityPolicyData {
+                connect_retry_attempts: policy.connect_retry_attempts,
+                connect_retry_backoff_ms: policy.connect_retry_backoff_ms,
+                connect_budget_ms: policy.connect_budget_ms,
+                unhealthy_fail_threshold: policy.unhealthy_fail_threshold,
+                connect_failfast_hard_errors: policy.connect_failfast_hard_errors,
+            },
+            counters,
+            summary: None,
+            upstreams: None,
+        };
+    };
+
+    RuntimeUpstreamQualityData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs,
+        policy: RuntimeUpstreamQualityPolicyData {
+            connect_retry_attempts: policy.connect_retry_attempts,
+            connect_retry_backoff_ms: policy.connect_retry_backoff_ms,
+            connect_budget_ms: policy.connect_budget_ms,
+            unhealthy_fail_threshold: policy.unhealthy_fail_threshold,
+            connect_failfast_hard_errors: policy.connect_failfast_hard_errors,
+        },
+        counters,
+        summary: Some(RuntimeUpstreamQualitySummaryData {
+            configured_total: snapshot.summary.configured_total,
+            healthy_total: snapshot.summary.healthy_total,
+            unhealthy_total: snapshot.summary.unhealthy_total,
+            direct_total: snapshot.summary.direct_total,
+            socks4_total: snapshot.summary.socks4_total,
+            socks5_total: snapshot.summary.socks5_total,
+        }),
+        upstreams: Some(
+            snapshot
+                .upstreams
+                .into_iter()
+                .map(|upstream| RuntimeUpstreamQualityUpstreamData {
+                    upstream_id: upstream.upstream_id,
+                    route_kind: match upstream.route_kind {
+                        crate::transport::UpstreamRouteKind::Direct => "direct",
+                        crate::transport::UpstreamRouteKind::Socks4 => "socks4",
+                        crate::transport::UpstreamRouteKind::Socks5 => "socks5",
+                    },
+                    address: upstream.address,
+                    weight: upstream.weight,
+                    scopes: upstream.scopes,
+                    healthy: upstream.healthy,
+                    fails: upstream.fails,
+                    last_check_age_secs: upstream.last_check_age_secs,
+                    effective_latency_ms: upstream.effective_latency_ms,
+                    dc: upstream
+                        .dc
+                        .into_iter()
+                        .map(|dc| RuntimeUpstreamQualityDcData {
+                            dc: dc.dc,
+                            latency_ema_ms: dc.latency_ema_ms,
+                            ip_preference: match dc.ip_preference {
+                                crate::transport::upstream::IpPreference::Unknown => "unknown",
+                                crate::transport::upstream::IpPreference::PreferV6 => "prefer_v6",
+                                crate::transport::upstream::IpPreference::PreferV4 => "prefer_v4",
+                                crate::transport::upstream::IpPreference::BothWork => "both_work",
+                                crate::transport::upstream::IpPreference::Unavailable => "unavailable",
+                            },
+                        })
+                        .collect(),
+                })
+                .collect(),
+        ),
+    }
+}
+
+pub(super) async fn build_runtime_nat_stun_data(shared: &ApiShared) -> RuntimeNatStunData {
+    let now_epoch_secs = now_epoch_secs();
+    let Some(pool) = shared.me_pool.read().await.clone() else {
+        return RuntimeNatStunData {
+            enabled: false,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    };
+
+    let snapshot = pool.api_nat_stun_snapshot().await;
+    RuntimeNatStunData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: now_epoch_secs,
+        data: Some(RuntimeNatStunPayload {
+            flags: RuntimeNatStunFlagsData {
+                nat_probe_enabled: snapshot.nat_probe_enabled,
+                nat_probe_disabled_runtime: snapshot.nat_probe_disabled_runtime,
+                nat_probe_attempts: snapshot.nat_probe_attempts,
+            },
+            servers: RuntimeNatStunServersData {
+                configured: snapshot.configured_servers,
+                live: snapshot.live_servers.clone(),
+                live_total: snapshot.live_servers.len(),
+            },
+            reflection: RuntimeNatStunReflectionBlockData {
+                v4: snapshot.reflection_v4.map(|entry| RuntimeNatStunReflectionData {
+                    addr: entry.addr.to_string(),
+                    age_secs: entry.age_secs,
+                }),
+                v6: snapshot.reflection_v6.map(|entry| RuntimeNatStunReflectionData {
+                    addr: entry.addr.to_string(),
+                    age_secs: entry.age_secs,
+                }),
+            },
+            stun_backoff_remaining_ms: snapshot.stun_backoff_remaining_ms,
+        }),
+    }
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_selftest.rs

@@ -0,0 +1,299 @@
+use std::net::IpAddr;
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::Serialize;
+
+use crate::config::{ProxyConfig, UpstreamType};
+use crate::network::probe::{detect_interface_ipv4, detect_interface_ipv6, is_bogon};
+use crate::transport::middle_proxy::{bnd_snapshot, timeskew_snapshot, upstream_bnd_snapshots};
+use crate::transport::UpstreamRouteKind;
+
+use super::ApiShared;
+
+const SOURCE_UNAVAILABLE_REASON: &str = "source_unavailable";
+const KDF_EWMA_TAU_SECS: f64 = 600.0;
+const KDF_EWMA_THRESHOLD_ERRORS_PER_MIN: f64 = 0.30;
+const TIMESKEW_THRESHOLD_SECS: u64 = 60;
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestKdfData {
+    pub(super) state: &'static str,
+    pub(super) ewma_errors_per_min: f64,
+    pub(super) threshold_errors_per_min: f64,
+    pub(super) errors_total: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestTimeskewData {
+    pub(super) state: &'static str,
+    pub(super) max_skew_secs_15m: Option<u64>,
+    pub(super) samples_15m: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_skew_secs: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_source: Option<&'static str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestIpFamilyData {
+    pub(super) addr: String,
+    pub(super) state: &'static str,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestIpData {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) v4: Option<RuntimeMeSelftestIpFamilyData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) v6: Option<RuntimeMeSelftestIpFamilyData>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestPidData {
+    pub(super) pid: u32,
+    pub(super) state: &'static str,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestBndData {
+    pub(super) addr_state: &'static str,
+    pub(super) port_state: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_addr: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestUpstreamData {
+    pub(super) upstream_id: usize,
+    pub(super) route_kind: &'static str,
+    pub(super) address: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) bnd: Option<RuntimeMeSelftestBndData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) ip: Option<String>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestPayload {
+    pub(super) kdf: RuntimeMeSelftestKdfData,
+    pub(super) timeskew: RuntimeMeSelftestTimeskewData,
+    pub(super) ip: RuntimeMeSelftestIpData,
+    pub(super) pid: RuntimeMeSelftestPidData,
+    pub(super) bnd: Option<RuntimeMeSelftestBndData>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) upstreams: Option<Vec<RuntimeMeSelftestUpstreamData>>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeMeSelftestData {
+    pub(super) enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reason: Option<&'static str>,
+    pub(super) generated_at_epoch_secs: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) data: Option<RuntimeMeSelftestPayload>,
+}
+
+#[derive(Default)]
+struct KdfEwmaState {
+    initialized: bool,
+    last_epoch_secs: u64,
+    last_total_errors: u64,
+    ewma_errors_per_min: f64,
+}
+
+static KDF_EWMA_STATE: OnceLock<Mutex<KdfEwmaState>> = OnceLock::new();
+
+fn kdf_ewma_state() -> &'static Mutex<KdfEwmaState> {
+    KDF_EWMA_STATE.get_or_init(|| Mutex::new(KdfEwmaState::default()))
+}
+
+pub(super) async fn build_runtime_me_selftest_data(
+    shared: &ApiShared,
+    cfg: &ProxyConfig,
+) -> RuntimeMeSelftestData {
+    let now_epoch_secs = now_epoch_secs();
+    if shared.me_pool.read().await.is_none() {
+        return RuntimeMeSelftestData {
+            enabled: false,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs: now_epoch_secs,
+            data: None,
+        };
+    }
+
+    let kdf_errors_total = shared
+        .stats
+        .get_me_kdf_drift_total()
+        .saturating_add(shared.stats.get_me_socks_kdf_strict_reject());
+    let kdf_ewma = update_kdf_ewma(now_epoch_secs, kdf_errors_total);
+    let kdf_state = if kdf_ewma >= KDF_EWMA_THRESHOLD_ERRORS_PER_MIN {
+        "error"
+    } else {
+        "ok"
+    };
+
+    let skew = timeskew_snapshot();
+    let timeskew_state = if skew.max_skew_secs_15m.unwrap_or(0) > TIMESKEW_THRESHOLD_SECS {
+        "error"
+    } else {
+        "ok"
+    };
+
+    let ip_v4 = detect_interface_ipv4().map(|ip| RuntimeMeSelftestIpFamilyData {
+        addr: ip.to_string(),
+        state: classify_ip(IpAddr::V4(ip)),
+    });
+    let ip_v6 = detect_interface_ipv6().map(|ip| RuntimeMeSelftestIpFamilyData {
+        addr: ip.to_string(),
+        state: classify_ip(IpAddr::V6(ip)),
+    });
+
+    let pid = std::process::id();
+    let pid_state = if pid == 1 { "one" } else { "non-one" };
+
+    let has_socks_upstreams = cfg.upstreams.iter().any(|upstream| {
+        upstream.enabled
+            && matches!(
+                upstream.upstream_type,
+                UpstreamType::Socks4 { .. } | UpstreamType::Socks5 { .. }
+            )
+    });
+
+    let bnd = if has_socks_upstreams {
+        let snapshot = bnd_snapshot();
+        Some(RuntimeMeSelftestBndData {
+            addr_state: snapshot.addr_status,
+            port_state: snapshot.port_status,
+            last_addr: snapshot.last_addr.map(|value| value.to_string()),
+            last_seen_age_secs: snapshot.last_seen_age_secs,
+        })
+    } else {
+        None
+    };
+    let upstreams = build_upstream_selftest_data(shared);
+
+    RuntimeMeSelftestData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs: now_epoch_secs,
+        data: Some(RuntimeMeSelftestPayload {
+            kdf: RuntimeMeSelftestKdfData {
+                state: kdf_state,
+                ewma_errors_per_min: round3(kdf_ewma),
+                threshold_errors_per_min: KDF_EWMA_THRESHOLD_ERRORS_PER_MIN,
+                errors_total: kdf_errors_total,
+            },
+            timeskew: RuntimeMeSelftestTimeskewData {
+                state: timeskew_state,
+                max_skew_secs_15m: skew.max_skew_secs_15m,
+                samples_15m: skew.samples_15m,
+                last_skew_secs: skew.last_skew_secs,
+                last_source: skew.last_source,
+                last_seen_age_secs: skew.last_seen_age_secs,
+            },
+            ip: RuntimeMeSelftestIpData {
+                v4: ip_v4,
+                v6: ip_v6,
+            },
+            pid: RuntimeMeSelftestPidData {
+                pid,
+                state: pid_state,
+            },
+            bnd,
+            upstreams,
+        }),
+    }
+}
+
+fn build_upstream_selftest_data(shared: &ApiShared) -> Option<Vec<RuntimeMeSelftestUpstreamData>> {
+    let snapshot = shared.upstream_manager.try_api_snapshot()?;
+    if snapshot.summary.configured_total <= 1 {
+        return None;
+    }
+
+    let mut upstream_bnd_by_id: HashMap<usize, _> = upstream_bnd_snapshots()
+        .into_iter()
+        .map(|entry| (entry.upstream_id, entry))
+        .collect();
+    let mut rows = Vec::with_capacity(snapshot.upstreams.len());
+    for upstream in snapshot.upstreams {
+        let upstream_bnd = upstream_bnd_by_id.remove(&upstream.upstream_id);
+        rows.push(RuntimeMeSelftestUpstreamData {
+            upstream_id: upstream.upstream_id,
+            route_kind: map_route_kind(upstream.route_kind),
+            address: upstream.address,
+            bnd: upstream_bnd.as_ref().map(|entry| RuntimeMeSelftestBndData {
+                addr_state: entry.addr_status,
+                port_state: entry.port_status,
+                last_addr: entry.last_addr.map(|value| value.to_string()),
+                last_seen_age_secs: entry.last_seen_age_secs,
+            }),
+            ip: upstream_bnd.and_then(|entry| entry.last_ip.map(|value| value.to_string())),
+        });
+    }
+    Some(rows)
+}
+
+fn update_kdf_ewma(now_epoch_secs: u64, total_errors: u64) -> f64 {
+    let Ok(mut guard) = kdf_ewma_state().lock() else {
+        return 0.0;
+    };
+
+    if !guard.initialized {
+        guard.initialized = true;
+        guard.last_epoch_secs = now_epoch_secs;
+        guard.last_total_errors = total_errors;
+        guard.ewma_errors_per_min = 0.0;
+        return guard.ewma_errors_per_min;
+    }
+
+    let dt_secs = now_epoch_secs.saturating_sub(guard.last_epoch_secs);
+    if dt_secs == 0 {
+        return guard.ewma_errors_per_min;
+    }
+
+    let delta_errors = total_errors.saturating_sub(guard.last_total_errors);
+    let instant_rate_per_min = (delta_errors as f64) * 60.0 / (dt_secs as f64);
+    let alpha = 1.0 - f64::exp(-(dt_secs as f64) / KDF_EWMA_TAU_SECS);
+    guard.ewma_errors_per_min = guard.ewma_errors_per_min
+        + alpha * (instant_rate_per_min - guard.ewma_errors_per_min);
+    guard.last_epoch_secs = now_epoch_secs;
+    guard.last_total_errors = total_errors;
+    guard.ewma_errors_per_min
+}
+
+fn classify_ip(ip: IpAddr) -> &'static str {
+    if ip.is_loopback() {
+        return "loopback";
+    }
+    if is_bogon(ip) {
+        return "bogon";
+    }
+    "good"
+}
+
+fn map_route_kind(value: UpstreamRouteKind) -> &'static str {
+    match value {
+        UpstreamRouteKind::Direct => "direct",
+        UpstreamRouteKind::Socks4 => "socks4",
+        UpstreamRouteKind::Socks5 => "socks5",
+    }
+}
+
+fn round3(value: f64) -> f64 {
+    (value * 1000.0).round() / 1000.0
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_stats.rs

@@ -0,0 +1,538 @@
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use crate::config::ApiConfig;
+use crate::stats::Stats;
+use crate::transport::upstream::IpPreference;
+use crate::transport::UpstreamRouteKind;
+
+use super::ApiShared;
+use super::model::{
+    DcEndpointWriters, DcStatus, DcStatusData, MeWriterStatus, MeWritersData, MeWritersSummary,
+    MinimalAllData, MinimalAllPayload, MinimalDcPathData, MinimalMeRuntimeData,
+    MinimalQuarantineData, UpstreamDcStatus, UpstreamStatus, UpstreamSummaryData, UpstreamsData,
+    ZeroAllData, ZeroCodeCount, ZeroCoreData, ZeroDesyncData, ZeroMiddleProxyData, ZeroPoolData,
+    ZeroUpstreamData,
+};
+
+const FEATURE_DISABLED_REASON: &str = "feature_disabled";
+const SOURCE_UNAVAILABLE_REASON: &str = "source_unavailable";
+
+#[derive(Clone)]
+pub(crate) struct MinimalCacheEntry {
+    pub(super) expires_at: Instant,
+    pub(super) payload: MinimalAllPayload,
+    pub(super) generated_at_epoch_secs: u64,
+}
+
+pub(super) fn build_zero_all_data(stats: &Stats, configured_users: usize) -> ZeroAllData {
+    let telemetry = stats.telemetry_policy();
+    let handshake_error_codes = stats
+        .get_me_handshake_error_code_counts()
+        .into_iter()
+        .map(|(code, total)| ZeroCodeCount { code, total })
+        .collect();
+
+    ZeroAllData {
+        generated_at_epoch_secs: now_epoch_secs(),
+        core: ZeroCoreData {
+            uptime_seconds: stats.uptime_secs(),
+            connections_total: stats.get_connects_all(),
+            connections_bad_total: stats.get_connects_bad(),
+            handshake_timeouts_total: stats.get_handshake_timeouts(),
+            configured_users,
+            telemetry_core_enabled: telemetry.core_enabled,
+            telemetry_user_enabled: telemetry.user_enabled,
+            telemetry_me_level: telemetry.me_level.to_string(),
+        },
+        upstream: build_zero_upstream_data(stats),
+        middle_proxy: ZeroMiddleProxyData {
+            keepalive_sent_total: stats.get_me_keepalive_sent(),
+            keepalive_failed_total: stats.get_me_keepalive_failed(),
+            keepalive_pong_total: stats.get_me_keepalive_pong(),
+            keepalive_timeout_total: stats.get_me_keepalive_timeout(),
+            rpc_proxy_req_signal_sent_total: stats.get_me_rpc_proxy_req_signal_sent_total(),
+            rpc_proxy_req_signal_failed_total: stats.get_me_rpc_proxy_req_signal_failed_total(),
+            rpc_proxy_req_signal_skipped_no_meta_total: stats
+                .get_me_rpc_proxy_req_signal_skipped_no_meta_total(),
+            rpc_proxy_req_signal_response_total: stats.get_me_rpc_proxy_req_signal_response_total(),
+            rpc_proxy_req_signal_close_sent_total: stats
+                .get_me_rpc_proxy_req_signal_close_sent_total(),
+            reconnect_attempt_total: stats.get_me_reconnect_attempts(),
+            reconnect_success_total: stats.get_me_reconnect_success(),
+            handshake_reject_total: stats.get_me_handshake_reject_total(),
+            handshake_error_codes,
+            reader_eof_total: stats.get_me_reader_eof_total(),
+            idle_close_by_peer_total: stats.get_me_idle_close_by_peer_total(),
+            route_drop_no_conn_total: stats.get_me_route_drop_no_conn(),
+            route_drop_channel_closed_total: stats.get_me_route_drop_channel_closed(),
+            route_drop_queue_full_total: stats.get_me_route_drop_queue_full(),
+            route_drop_queue_full_base_total: stats.get_me_route_drop_queue_full_base(),
+            route_drop_queue_full_high_total: stats.get_me_route_drop_queue_full_high(),
+            socks_kdf_strict_reject_total: stats.get_me_socks_kdf_strict_reject(),
+            socks_kdf_compat_fallback_total: stats.get_me_socks_kdf_compat_fallback(),
+            endpoint_quarantine_total: stats.get_me_endpoint_quarantine_total(),
+            kdf_drift_total: stats.get_me_kdf_drift_total(),
+            kdf_port_only_drift_total: stats.get_me_kdf_port_only_drift_total(),
+            hardswap_pending_reuse_total: stats.get_me_hardswap_pending_reuse_total(),
+            hardswap_pending_ttl_expired_total: stats.get_me_hardswap_pending_ttl_expired_total(),
+            single_endpoint_outage_enter_total: stats.get_me_single_endpoint_outage_enter_total(),
+            single_endpoint_outage_exit_total: stats.get_me_single_endpoint_outage_exit_total(),
+            single_endpoint_outage_reconnect_attempt_total: stats
+                .get_me_single_endpoint_outage_reconnect_attempt_total(),
+            single_endpoint_outage_reconnect_success_total: stats
+                .get_me_single_endpoint_outage_reconnect_success_total(),
+            single_endpoint_quarantine_bypass_total: stats
+                .get_me_single_endpoint_quarantine_bypass_total(),
+            single_endpoint_shadow_rotate_total: stats.get_me_single_endpoint_shadow_rotate_total(),
+            single_endpoint_shadow_rotate_skipped_quarantine_total: stats
+                .get_me_single_endpoint_shadow_rotate_skipped_quarantine_total(),
+            floor_mode_switch_total: stats.get_me_floor_mode_switch_total(),
+            floor_mode_switch_static_to_adaptive_total: stats
+                .get_me_floor_mode_switch_static_to_adaptive_total(),
+            floor_mode_switch_adaptive_to_static_total: stats
+                .get_me_floor_mode_switch_adaptive_to_static_total(),
+        },
+        pool: ZeroPoolData {
+            pool_swap_total: stats.get_pool_swap_total(),
+            pool_drain_active: stats.get_pool_drain_active(),
+            pool_force_close_total: stats.get_pool_force_close_total(),
+            pool_stale_pick_total: stats.get_pool_stale_pick_total(),
+            writer_removed_total: stats.get_me_writer_removed_total(),
+            writer_removed_unexpected_total: stats.get_me_writer_removed_unexpected_total(),
+            refill_triggered_total: stats.get_me_refill_triggered_total(),
+            refill_skipped_inflight_total: stats.get_me_refill_skipped_inflight_total(),
+            refill_failed_total: stats.get_me_refill_failed_total(),
+            writer_restored_same_endpoint_total: stats.get_me_writer_restored_same_endpoint_total(),
+            writer_restored_fallback_total: stats.get_me_writer_restored_fallback_total(),
+        },
+        desync: ZeroDesyncData {
+            secure_padding_invalid_total: stats.get_secure_padding_invalid(),
+            desync_total: stats.get_desync_total(),
+            desync_full_logged_total: stats.get_desync_full_logged(),
+            desync_suppressed_total: stats.get_desync_suppressed(),
+            desync_frames_bucket_0: stats.get_desync_frames_bucket_0(),
+            desync_frames_bucket_1_2: stats.get_desync_frames_bucket_1_2(),
+            desync_frames_bucket_3_10: stats.get_desync_frames_bucket_3_10(),
+            desync_frames_bucket_gt_10: stats.get_desync_frames_bucket_gt_10(),
+        },
+    }
+}
+
+fn build_zero_upstream_data(stats: &Stats) -> ZeroUpstreamData {
+    ZeroUpstreamData {
+        connect_attempt_total: stats.get_upstream_connect_attempt_total(),
+        connect_success_total: stats.get_upstream_connect_success_total(),
+        connect_fail_total: stats.get_upstream_connect_fail_total(),
+        connect_failfast_hard_error_total: stats.get_upstream_connect_failfast_hard_error_total(),
+        connect_attempts_bucket_1: stats.get_upstream_connect_attempts_bucket_1(),
+        connect_attempts_bucket_2: stats.get_upstream_connect_attempts_bucket_2(),
+        connect_attempts_bucket_3_4: stats.get_upstream_connect_attempts_bucket_3_4(),
+        connect_attempts_bucket_gt_4: stats.get_upstream_connect_attempts_bucket_gt_4(),
+        connect_duration_success_bucket_le_100ms: stats
+            .get_upstream_connect_duration_success_bucket_le_100ms(),
+        connect_duration_success_bucket_101_500ms: stats
+            .get_upstream_connect_duration_success_bucket_101_500ms(),
+        connect_duration_success_bucket_501_1000ms: stats
+            .get_upstream_connect_duration_success_bucket_501_1000ms(),
+        connect_duration_success_bucket_gt_1000ms: stats
+            .get_upstream_connect_duration_success_bucket_gt_1000ms(),
+        connect_duration_fail_bucket_le_100ms: stats.get_upstream_connect_duration_fail_bucket_le_100ms(),
+        connect_duration_fail_bucket_101_500ms: stats
+            .get_upstream_connect_duration_fail_bucket_101_500ms(),
+        connect_duration_fail_bucket_501_1000ms: stats
+            .get_upstream_connect_duration_fail_bucket_501_1000ms(),
+        connect_duration_fail_bucket_gt_1000ms: stats
+            .get_upstream_connect_duration_fail_bucket_gt_1000ms(),
+    }
+}
+
+pub(super) fn build_upstreams_data(shared: &ApiShared, api_cfg: &ApiConfig) -> UpstreamsData {
+    let generated_at_epoch_secs = now_epoch_secs();
+    let zero = build_zero_upstream_data(&shared.stats);
+    if !api_cfg.minimal_runtime_enabled {
+        return UpstreamsData {
+            enabled: false,
+            reason: Some(FEATURE_DISABLED_REASON),
+            generated_at_epoch_secs,
+            zero,
+            summary: None,
+            upstreams: None,
+        };
+    }
+
+    let Some(snapshot) = shared.upstream_manager.try_api_snapshot() else {
+        return UpstreamsData {
+            enabled: true,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs,
+            zero,
+            summary: None,
+            upstreams: None,
+        };
+    };
+
+    let summary = UpstreamSummaryData {
+        configured_total: snapshot.summary.configured_total,
+        healthy_total: snapshot.summary.healthy_total,
+        unhealthy_total: snapshot.summary.unhealthy_total,
+        direct_total: snapshot.summary.direct_total,
+        socks4_total: snapshot.summary.socks4_total,
+        socks5_total: snapshot.summary.socks5_total,
+    };
+    let upstreams = snapshot
+        .upstreams
+        .into_iter()
+        .map(|upstream| UpstreamStatus {
+            upstream_id: upstream.upstream_id,
+            route_kind: map_route_kind(upstream.route_kind),
+            address: upstream.address,
+            weight: upstream.weight,
+            scopes: upstream.scopes,
+            healthy: upstream.healthy,
+            fails: upstream.fails,
+            last_check_age_secs: upstream.last_check_age_secs,
+            effective_latency_ms: upstream.effective_latency_ms,
+            dc: upstream
+                .dc
+                .into_iter()
+                .map(|dc| UpstreamDcStatus {
+                    dc: dc.dc,
+                    latency_ema_ms: dc.latency_ema_ms,
+                    ip_preference: map_ip_preference(dc.ip_preference),
+                })
+                .collect(),
+        })
+        .collect();
+
+    UpstreamsData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs,
+        zero,
+        summary: Some(summary),
+        upstreams: Some(upstreams),
+    }
+}
+
+pub(super) async fn build_minimal_all_data(
+    shared: &ApiShared,
+    api_cfg: &ApiConfig,
+) -> MinimalAllData {
+    let now = now_epoch_secs();
+    if !api_cfg.minimal_runtime_enabled {
+        return MinimalAllData {
+            enabled: false,
+            reason: Some(FEATURE_DISABLED_REASON),
+            generated_at_epoch_secs: now,
+            data: None,
+        };
+    }
+
+    let Some((generated_at_epoch_secs, payload)) =
+        get_minimal_payload_cached(shared, api_cfg.minimal_runtime_cache_ttl_ms).await
+    else {
+        return MinimalAllData {
+            enabled: true,
+            reason: Some(SOURCE_UNAVAILABLE_REASON),
+            generated_at_epoch_secs: now,
+            data: Some(MinimalAllPayload {
+                me_writers: disabled_me_writers(now, SOURCE_UNAVAILABLE_REASON),
+                dcs: disabled_dcs(now, SOURCE_UNAVAILABLE_REASON),
+                me_runtime: None,
+                network_path: Vec::new(),
+            }),
+        };
+    };
+
+    MinimalAllData {
+        enabled: true,
+        reason: None,
+        generated_at_epoch_secs,
+        data: Some(payload),
+    }
+}
+
+pub(super) async fn build_me_writers_data(
+    shared: &ApiShared,
+    api_cfg: &ApiConfig,
+) -> MeWritersData {
+    let now = now_epoch_secs();
+    if !api_cfg.minimal_runtime_enabled {
+        return disabled_me_writers(now, FEATURE_DISABLED_REASON);
+    }
+
+    let Some((_, payload)) =
+        get_minimal_payload_cached(shared, api_cfg.minimal_runtime_cache_ttl_ms).await
+    else {
+        return disabled_me_writers(now, SOURCE_UNAVAILABLE_REASON);
+    };
+    payload.me_writers
+}
+
+pub(super) async fn build_dcs_data(shared: &ApiShared, api_cfg: &ApiConfig) -> DcStatusData {
+    let now = now_epoch_secs();
+    if !api_cfg.minimal_runtime_enabled {
+        return disabled_dcs(now, FEATURE_DISABLED_REASON);
+    }
+
+    let Some((_, payload)) =
+        get_minimal_payload_cached(shared, api_cfg.minimal_runtime_cache_ttl_ms).await
+    else {
+        return disabled_dcs(now, SOURCE_UNAVAILABLE_REASON);
+    };
+    payload.dcs
+}
+
+async fn get_minimal_payload_cached(
+    shared: &ApiShared,
+    cache_ttl_ms: u64,
+) -> Option<(u64, MinimalAllPayload)> {
+    if cache_ttl_ms > 0 {
+        let now = Instant::now();
+        let cached = shared.minimal_cache.lock().await.clone();
+        if let Some(entry) = cached
+            && now < entry.expires_at
+        {
+            return Some((entry.generated_at_epoch_secs, entry.payload));
+        }
+    }
+
+    let pool = shared.me_pool.read().await.clone()?;
+    let status = pool.api_status_snapshot().await;
+    let runtime = pool.api_runtime_snapshot().await;
+    let generated_at_epoch_secs = status.generated_at_epoch_secs;
+
+    let me_writers = MeWritersData {
+        middle_proxy_enabled: true,
+        reason: None,
+        generated_at_epoch_secs,
+        summary: MeWritersSummary {
+            configured_dc_groups: status.configured_dc_groups,
+            configured_endpoints: status.configured_endpoints,
+            available_endpoints: status.available_endpoints,
+            available_pct: status.available_pct,
+            required_writers: status.required_writers,
+            alive_writers: status.alive_writers,
+            coverage_pct: status.coverage_pct,
+            fresh_alive_writers: status.fresh_alive_writers,
+            fresh_coverage_pct: status.fresh_coverage_pct,
+        },
+        writers: status
+            .writers
+            .into_iter()
+            .map(|entry| MeWriterStatus {
+                writer_id: entry.writer_id,
+                dc: entry.dc,
+                endpoint: entry.endpoint.to_string(),
+                generation: entry.generation,
+                state: entry.state,
+                draining: entry.draining,
+                degraded: entry.degraded,
+                bound_clients: entry.bound_clients,
+                idle_for_secs: entry.idle_for_secs,
+                rtt_ema_ms: entry.rtt_ema_ms,
+                matches_active_generation: entry.matches_active_generation,
+                in_desired_map: entry.in_desired_map,
+                allow_drain_fallback: entry.allow_drain_fallback,
+                drain_started_at_epoch_secs: entry.drain_started_at_epoch_secs,
+                drain_deadline_epoch_secs: entry.drain_deadline_epoch_secs,
+                drain_over_ttl: entry.drain_over_ttl,
+            })
+            .collect(),
+    };
+    let dcs = DcStatusData {
+        middle_proxy_enabled: true,
+        reason: None,
+        generated_at_epoch_secs,
+        dcs: status
+            .dcs
+            .into_iter()
+            .map(|entry| DcStatus {
+                dc: entry.dc,
+                endpoints: entry
+                    .endpoints
+                    .into_iter()
+                    .map(|value| value.to_string())
+                    .collect(),
+                endpoint_writers: entry
+                    .endpoint_writers
+                    .into_iter()
+                    .map(|coverage| DcEndpointWriters {
+                        endpoint: coverage.endpoint.to_string(),
+                        active_writers: coverage.active_writers,
+                    })
+                    .collect(),
+                available_endpoints: entry.available_endpoints,
+                available_pct: entry.available_pct,
+                required_writers: entry.required_writers,
+                floor_min: entry.floor_min,
+                floor_target: entry.floor_target,
+                floor_max: entry.floor_max,
+                floor_capped: entry.floor_capped,
+                alive_writers: entry.alive_writers,
+                coverage_pct: entry.coverage_pct,
+                fresh_alive_writers: entry.fresh_alive_writers,
+                fresh_coverage_pct: entry.fresh_coverage_pct,
+                rtt_ms: entry.rtt_ms,
+                load: entry.load,
+            })
+            .collect(),
+    };
+    let me_runtime = MinimalMeRuntimeData {
+        active_generation: runtime.active_generation,
+        warm_generation: runtime.warm_generation,
+        pending_hardswap_generation: runtime.pending_hardswap_generation,
+        pending_hardswap_age_secs: runtime.pending_hardswap_age_secs,
+        hardswap_enabled: runtime.hardswap_enabled,
+        floor_mode: runtime.floor_mode,
+        adaptive_floor_idle_secs: runtime.adaptive_floor_idle_secs,
+        adaptive_floor_min_writers_single_endpoint: runtime
+            .adaptive_floor_min_writers_single_endpoint,
+        adaptive_floor_min_writers_multi_endpoint: runtime
+            .adaptive_floor_min_writers_multi_endpoint,
+        adaptive_floor_recover_grace_secs: runtime.adaptive_floor_recover_grace_secs,
+        adaptive_floor_writers_per_core_total: runtime
+            .adaptive_floor_writers_per_core_total,
+        adaptive_floor_cpu_cores_override: runtime.adaptive_floor_cpu_cores_override,
+        adaptive_floor_max_extra_writers_single_per_core: runtime
+            .adaptive_floor_max_extra_writers_single_per_core,
+        adaptive_floor_max_extra_writers_multi_per_core: runtime
+            .adaptive_floor_max_extra_writers_multi_per_core,
+        adaptive_floor_max_active_writers_per_core: runtime
+            .adaptive_floor_max_active_writers_per_core,
+        adaptive_floor_max_warm_writers_per_core: runtime
+            .adaptive_floor_max_warm_writers_per_core,
+        adaptive_floor_max_active_writers_global: runtime
+            .adaptive_floor_max_active_writers_global,
+        adaptive_floor_max_warm_writers_global: runtime
+            .adaptive_floor_max_warm_writers_global,
+        adaptive_floor_cpu_cores_detected: runtime.adaptive_floor_cpu_cores_detected,
+        adaptive_floor_cpu_cores_effective: runtime.adaptive_floor_cpu_cores_effective,
+        adaptive_floor_global_cap_raw: runtime.adaptive_floor_global_cap_raw,
+        adaptive_floor_global_cap_effective: runtime.adaptive_floor_global_cap_effective,
+        adaptive_floor_target_writers_total: runtime.adaptive_floor_target_writers_total,
+        adaptive_floor_active_cap_configured: runtime.adaptive_floor_active_cap_configured,
+        adaptive_floor_active_cap_effective: runtime.adaptive_floor_active_cap_effective,
+        adaptive_floor_warm_cap_configured: runtime.adaptive_floor_warm_cap_configured,
+        adaptive_floor_warm_cap_effective: runtime.adaptive_floor_warm_cap_effective,
+        adaptive_floor_active_writers_current: runtime.adaptive_floor_active_writers_current,
+        adaptive_floor_warm_writers_current: runtime.adaptive_floor_warm_writers_current,
+        me_keepalive_enabled: runtime.me_keepalive_enabled,
+        me_keepalive_interval_secs: runtime.me_keepalive_interval_secs,
+        me_keepalive_jitter_secs: runtime.me_keepalive_jitter_secs,
+        me_keepalive_payload_random: runtime.me_keepalive_payload_random,
+        rpc_proxy_req_every_secs: runtime.rpc_proxy_req_every_secs,
+        me_reconnect_max_concurrent_per_dc: runtime.me_reconnect_max_concurrent_per_dc,
+        me_reconnect_backoff_base_ms: runtime.me_reconnect_backoff_base_ms,
+        me_reconnect_backoff_cap_ms: runtime.me_reconnect_backoff_cap_ms,
+        me_reconnect_fast_retry_count: runtime.me_reconnect_fast_retry_count,
+        me_pool_drain_ttl_secs: runtime.me_pool_drain_ttl_secs,
+        me_pool_force_close_secs: runtime.me_pool_force_close_secs,
+        me_pool_min_fresh_ratio: runtime.me_pool_min_fresh_ratio,
+        me_bind_stale_mode: runtime.me_bind_stale_mode,
+        me_bind_stale_ttl_secs: runtime.me_bind_stale_ttl_secs,
+        me_single_endpoint_shadow_writers: runtime.me_single_endpoint_shadow_writers,
+        me_single_endpoint_outage_mode_enabled: runtime.me_single_endpoint_outage_mode_enabled,
+        me_single_endpoint_outage_disable_quarantine: runtime
+            .me_single_endpoint_outage_disable_quarantine,
+        me_single_endpoint_outage_backoff_min_ms: runtime.me_single_endpoint_outage_backoff_min_ms,
+        me_single_endpoint_outage_backoff_max_ms: runtime.me_single_endpoint_outage_backoff_max_ms,
+        me_single_endpoint_shadow_rotate_every_secs: runtime
+            .me_single_endpoint_shadow_rotate_every_secs,
+        me_deterministic_writer_sort: runtime.me_deterministic_writer_sort,
+        me_writer_pick_mode: runtime.me_writer_pick_mode,
+        me_writer_pick_sample_size: runtime.me_writer_pick_sample_size,
+        me_socks_kdf_policy: runtime.me_socks_kdf_policy,
+        quarantined_endpoints_total: runtime.quarantined_endpoints.len(),
+        quarantined_endpoints: runtime
+            .quarantined_endpoints
+            .into_iter()
+            .map(|entry| MinimalQuarantineData {
+                endpoint: entry.endpoint.to_string(),
+                remaining_ms: entry.remaining_ms,
+            })
+            .collect(),
+    };
+    let network_path = runtime
+        .network_path
+        .into_iter()
+        .map(|entry| MinimalDcPathData {
+            dc: entry.dc,
+            ip_preference: entry.ip_preference,
+            selected_addr_v4: entry.selected_addr_v4.map(|value| value.to_string()),
+            selected_addr_v6: entry.selected_addr_v6.map(|value| value.to_string()),
+        })
+        .collect();
+
+    let payload = MinimalAllPayload {
+        me_writers,
+        dcs,
+        me_runtime: Some(me_runtime),
+        network_path,
+    };
+
+    if cache_ttl_ms > 0 {
+        let entry = MinimalCacheEntry {
+            expires_at: Instant::now() + Duration::from_millis(cache_ttl_ms),
+            payload: payload.clone(),
+            generated_at_epoch_secs,
+        };
+        *shared.minimal_cache.lock().await = Some(entry);
+    }
+
+    Some((generated_at_epoch_secs, payload))
+}
+
+fn disabled_me_writers(now_epoch_secs: u64, reason: &'static str) -> MeWritersData {
+    MeWritersData {
+        middle_proxy_enabled: false,
+        reason: Some(reason),
+        generated_at_epoch_secs: now_epoch_secs,
+        summary: MeWritersSummary {
+            configured_dc_groups: 0,
+            configured_endpoints: 0,
+            available_endpoints: 0,
+            available_pct: 0.0,
+            required_writers: 0,
+            alive_writers: 0,
+            coverage_pct: 0.0,
+            fresh_alive_writers: 0,
+            fresh_coverage_pct: 0.0,
+        },
+        writers: Vec::new(),
+    }
+}
+
+fn disabled_dcs(now_epoch_secs: u64, reason: &'static str) -> DcStatusData {
+    DcStatusData {
+        middle_proxy_enabled: false,
+        reason: Some(reason),
+        generated_at_epoch_secs: now_epoch_secs,
+        dcs: Vec::new(),
+    }
+}
+
+fn map_route_kind(value: UpstreamRouteKind) -> &'static str {
+    match value {
+        UpstreamRouteKind::Direct => "direct",
+        UpstreamRouteKind::Socks4 => "socks4",
+        UpstreamRouteKind::Socks5 => "socks5",
+    }
+}
+
+fn map_ip_preference(value: IpPreference) -> &'static str {
+    match value {
+        IpPreference::Unknown => "unknown",
+        IpPreference::PreferV6 => "prefer_v6",
+        IpPreference::PreferV4 => "prefer_v4",
+        IpPreference::BothWork => "both_work",
+        IpPreference::Unavailable => "unavailable",
+    }
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_watch.rs

@@ -0,0 +1,66 @@
+use std::sync::Arc;
+use std::sync::atomic::Ordering;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use tokio::sync::watch;
+
+use crate::config::ProxyConfig;
+
+use super::ApiRuntimeState;
+use super::events::ApiEventStore;
+
+pub(super) fn spawn_runtime_watchers(
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    admission_rx: watch::Receiver<bool>,
+    runtime_state: Arc<ApiRuntimeState>,
+    runtime_events: Arc<ApiEventStore>,
+) {
+    let mut config_rx_reload = config_rx;
+    let runtime_state_reload = runtime_state.clone();
+    let runtime_events_reload = runtime_events.clone();
+    tokio::spawn(async move {
+        loop {
+            if config_rx_reload.changed().await.is_err() {
+                break;
+            }
+            runtime_state_reload
+                .config_reload_count
+                .fetch_add(1, Ordering::Relaxed);
+            runtime_state_reload
+                .last_config_reload_epoch_secs
+                .store(now_epoch_secs(), Ordering::Relaxed);
+            runtime_events_reload.record("config.reload.applied", "config receiver updated");
+        }
+    });
+
+    let mut admission_rx_watch = admission_rx;
+    tokio::spawn(async move {
+        runtime_state
+            .admission_open
+            .store(*admission_rx_watch.borrow(), Ordering::Relaxed);
+        runtime_events.record(
+            "admission.state",
+            format!("accepting_new_connections={}", *admission_rx_watch.borrow()),
+        );
+        loop {
+            if admission_rx_watch.changed().await.is_err() {
+                break;
+            }
+            let admission_open = *admission_rx_watch.borrow();
+            runtime_state
+                .admission_open
+                .store(admission_open, Ordering::Relaxed);
+            runtime_events.record(
+                "admission.state",
+                format!("accepting_new_connections={}", admission_open),
+            );
+        }
+    });
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}

src/api/runtime_zero.rs

@@ -0,0 +1,307 @@
+use std::sync::atomic::Ordering;
+
+use serde::Serialize;
+
+use crate::config::{MeFloorMode, MeWriterPickMode, ProxyConfig, UserMaxUniqueIpsMode};
+use crate::proxy::route_mode::RelayRouteMode;
+
+use super::ApiShared;
+use super::runtime_init::build_runtime_startup_summary;
+
+#[derive(Serialize)]
+pub(super) struct SystemInfoData {
+    pub(super) version: String,
+    pub(super) target_arch: String,
+    pub(super) target_os: String,
+    pub(super) build_profile: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) git_commit: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) build_time_utc: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) rustc_version: Option<String>,
+    pub(super) process_started_at_epoch_secs: u64,
+    pub(super) uptime_seconds: f64,
+    pub(super) config_path: String,
+    pub(super) config_hash: String,
+    pub(super) config_reload_count: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) last_config_reload_epoch_secs: Option<u64>,
+}
+
+#[derive(Serialize)]
+pub(super) struct RuntimeGatesData {
+    pub(super) accepting_new_connections: bool,
+    pub(super) conditional_cast_enabled: bool,
+    pub(super) me_runtime_ready: bool,
+    pub(super) me2dc_fallback_enabled: bool,
+    pub(super) use_middle_proxy: bool,
+    pub(super) route_mode: &'static str,
+    pub(super) reroute_active: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub(super) reroute_to_direct_at_epoch_secs: Option<u64>,
+    pub(super) startup_status: &'static str,
+    pub(super) startup_stage: String,
+    pub(super) startup_progress_pct: f64,
+}
+
+#[derive(Serialize)]
+pub(super) struct EffectiveTimeoutLimits {
+    pub(super) client_handshake_secs: u64,
+    pub(super) tg_connect_secs: u64,
+    pub(super) client_keepalive_secs: u64,
+    pub(super) client_ack_secs: u64,
+    pub(super) me_one_retry: u8,
+    pub(super) me_one_timeout_ms: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct EffectiveUpstreamLimits {
+    pub(super) connect_retry_attempts: u32,
+    pub(super) connect_retry_backoff_ms: u64,
+    pub(super) connect_budget_ms: u64,
+    pub(super) unhealthy_fail_threshold: u32,
+    pub(super) connect_failfast_hard_errors: bool,
+}
+
+#[derive(Serialize)]
+pub(super) struct EffectiveMiddleProxyLimits {
+    pub(super) floor_mode: &'static str,
+    pub(super) adaptive_floor_idle_secs: u64,
+    pub(super) adaptive_floor_min_writers_single_endpoint: u8,
+    pub(super) adaptive_floor_min_writers_multi_endpoint: u8,
+    pub(super) adaptive_floor_recover_grace_secs: u64,
+    pub(super) adaptive_floor_writers_per_core_total: u16,
+    pub(super) adaptive_floor_cpu_cores_override: u16,
+    pub(super) adaptive_floor_max_extra_writers_single_per_core: u16,
+    pub(super) adaptive_floor_max_extra_writers_multi_per_core: u16,
+    pub(super) adaptive_floor_max_active_writers_per_core: u16,
+    pub(super) adaptive_floor_max_warm_writers_per_core: u16,
+    pub(super) adaptive_floor_max_active_writers_global: u32,
+    pub(super) adaptive_floor_max_warm_writers_global: u32,
+    pub(super) reconnect_max_concurrent_per_dc: u32,
+    pub(super) reconnect_backoff_base_ms: u64,
+    pub(super) reconnect_backoff_cap_ms: u64,
+    pub(super) reconnect_fast_retry_count: u32,
+    pub(super) writer_pick_mode: &'static str,
+    pub(super) writer_pick_sample_size: u8,
+    pub(super) me2dc_fallback: bool,
+}
+
+#[derive(Serialize)]
+pub(super) struct EffectiveUserIpPolicyLimits {
+    pub(super) global_each: usize,
+    pub(super) mode: &'static str,
+    pub(super) window_secs: u64,
+}
+
+#[derive(Serialize)]
+pub(super) struct EffectiveLimitsData {
+    pub(super) update_every_secs: u64,
+    pub(super) me_reinit_every_secs: u64,
+    pub(super) me_pool_force_close_secs: u64,
+    pub(super) timeouts: EffectiveTimeoutLimits,
+    pub(super) upstream: EffectiveUpstreamLimits,
+    pub(super) middle_proxy: EffectiveMiddleProxyLimits,
+    pub(super) user_ip_policy: EffectiveUserIpPolicyLimits,
+}
+
+#[derive(Serialize)]
+pub(super) struct SecurityPostureData {
+    pub(super) api_read_only: bool,
+    pub(super) api_whitelist_enabled: bool,
+    pub(super) api_whitelist_entries: usize,
+    pub(super) api_auth_header_enabled: bool,
+    pub(super) proxy_protocol_enabled: bool,
+    pub(super) log_level: String,
+    pub(super) telemetry_core_enabled: bool,
+    pub(super) telemetry_user_enabled: bool,
+    pub(super) telemetry_me_level: String,
+}
+
+pub(super) fn build_system_info_data(
+    shared: &ApiShared,
+    _cfg: &ProxyConfig,
+    revision: &str,
+) -> SystemInfoData {
+    let last_reload_epoch_secs = shared
+        .runtime_state
+        .last_config_reload_epoch_secs
+        .load(Ordering::Relaxed);
+    let last_config_reload_epoch_secs = (last_reload_epoch_secs > 0).then_some(last_reload_epoch_secs);
+
+    let git_commit = option_env!("TELEMT_GIT_COMMIT")
+        .or(option_env!("VERGEN_GIT_SHA"))
+        .or(option_env!("GIT_COMMIT"))
+        .map(ToString::to_string);
+    let build_time_utc = option_env!("BUILD_TIME_UTC")
+        .or(option_env!("VERGEN_BUILD_TIMESTAMP"))
+        .map(ToString::to_string);
+    let rustc_version = option_env!("RUSTC_VERSION")
+        .or(option_env!("VERGEN_RUSTC_SEMVER"))
+        .map(ToString::to_string);
+
+    SystemInfoData {
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        target_arch: std::env::consts::ARCH.to_string(),
+        target_os: std::env::consts::OS.to_string(),
+        build_profile: option_env!("PROFILE").unwrap_or("unknown").to_string(),
+        git_commit,
+        build_time_utc,
+        rustc_version,
+        process_started_at_epoch_secs: shared.runtime_state.process_started_at_epoch_secs,
+        uptime_seconds: shared.stats.uptime_secs(),
+        config_path: shared.config_path.display().to_string(),
+        config_hash: revision.to_string(),
+        config_reload_count: shared.runtime_state.config_reload_count.load(Ordering::Relaxed),
+        last_config_reload_epoch_secs,
+    }
+}
+
+pub(super) async fn build_runtime_gates_data(
+    shared: &ApiShared,
+    cfg: &ProxyConfig,
+) -> RuntimeGatesData {
+    let startup_summary = build_runtime_startup_summary(shared).await;
+    let route_state = shared.route_runtime.snapshot();
+    let route_mode = route_state.mode.as_str();
+    let reroute_active = cfg.general.use_middle_proxy
+        && cfg.general.me2dc_fallback
+        && matches!(route_state.mode, RelayRouteMode::Direct);
+    let reroute_to_direct_at_epoch_secs = if reroute_active {
+        shared.route_runtime.direct_since_epoch_secs()
+    } else {
+        None
+    };
+    let me_runtime_ready = if !cfg.general.use_middle_proxy {
+        true
+    } else {
+        shared
+            .me_pool
+            .read()
+            .await
+            .as_ref()
+            .map(|pool| pool.is_runtime_ready())
+            .unwrap_or(false)
+    };
+
+    RuntimeGatesData {
+        accepting_new_connections: shared.runtime_state.admission_open.load(Ordering::Relaxed),
+        conditional_cast_enabled: cfg.general.use_middle_proxy,
+        me_runtime_ready,
+        me2dc_fallback_enabled: cfg.general.me2dc_fallback,
+        use_middle_proxy: cfg.general.use_middle_proxy,
+        route_mode,
+        reroute_active,
+        reroute_to_direct_at_epoch_secs,
+        startup_status: startup_summary.status,
+        startup_stage: startup_summary.stage,
+        startup_progress_pct: startup_summary.progress_pct,
+    }
+}
+
+pub(super) fn build_limits_effective_data(cfg: &ProxyConfig) -> EffectiveLimitsData {
+    EffectiveLimitsData {
+        update_every_secs: cfg.general.effective_update_every_secs(),
+        me_reinit_every_secs: cfg.general.effective_me_reinit_every_secs(),
+        me_pool_force_close_secs: cfg.general.effective_me_pool_force_close_secs(),
+        timeouts: EffectiveTimeoutLimits {
+            client_handshake_secs: cfg.timeouts.client_handshake,
+            tg_connect_secs: cfg.timeouts.tg_connect,
+            client_keepalive_secs: cfg.timeouts.client_keepalive,
+            client_ack_secs: cfg.timeouts.client_ack,
+            me_one_retry: cfg.timeouts.me_one_retry,
+            me_one_timeout_ms: cfg.timeouts.me_one_timeout_ms,
+        },
+        upstream: EffectiveUpstreamLimits {
+            connect_retry_attempts: cfg.general.upstream_connect_retry_attempts,
+            connect_retry_backoff_ms: cfg.general.upstream_connect_retry_backoff_ms,
+            connect_budget_ms: cfg.general.upstream_connect_budget_ms,
+            unhealthy_fail_threshold: cfg.general.upstream_unhealthy_fail_threshold,
+            connect_failfast_hard_errors: cfg.general.upstream_connect_failfast_hard_errors,
+        },
+        middle_proxy: EffectiveMiddleProxyLimits {
+            floor_mode: me_floor_mode_label(cfg.general.me_floor_mode),
+            adaptive_floor_idle_secs: cfg.general.me_adaptive_floor_idle_secs,
+            adaptive_floor_min_writers_single_endpoint: cfg
+                .general
+                .me_adaptive_floor_min_writers_single_endpoint,
+            adaptive_floor_min_writers_multi_endpoint: cfg
+                .general
+                .me_adaptive_floor_min_writers_multi_endpoint,
+            adaptive_floor_recover_grace_secs: cfg.general.me_adaptive_floor_recover_grace_secs,
+            adaptive_floor_writers_per_core_total: cfg
+                .general
+                .me_adaptive_floor_writers_per_core_total,
+            adaptive_floor_cpu_cores_override: cfg
+                .general
+                .me_adaptive_floor_cpu_cores_override,
+            adaptive_floor_max_extra_writers_single_per_core: cfg
+                .general
+                .me_adaptive_floor_max_extra_writers_single_per_core,
+            adaptive_floor_max_extra_writers_multi_per_core: cfg
+                .general
+                .me_adaptive_floor_max_extra_writers_multi_per_core,
+            adaptive_floor_max_active_writers_per_core: cfg
+                .general
+                .me_adaptive_floor_max_active_writers_per_core,
+            adaptive_floor_max_warm_writers_per_core: cfg
+                .general
+                .me_adaptive_floor_max_warm_writers_per_core,
+            adaptive_floor_max_active_writers_global: cfg
+                .general
+                .me_adaptive_floor_max_active_writers_global,
+            adaptive_floor_max_warm_writers_global: cfg
+                .general
+                .me_adaptive_floor_max_warm_writers_global,
+            reconnect_max_concurrent_per_dc: cfg.general.me_reconnect_max_concurrent_per_dc,
+            reconnect_backoff_base_ms: cfg.general.me_reconnect_backoff_base_ms,
+            reconnect_backoff_cap_ms: cfg.general.me_reconnect_backoff_cap_ms,
+            reconnect_fast_retry_count: cfg.general.me_reconnect_fast_retry_count,
+            writer_pick_mode: me_writer_pick_mode_label(cfg.general.me_writer_pick_mode),
+            writer_pick_sample_size: cfg.general.me_writer_pick_sample_size,
+            me2dc_fallback: cfg.general.me2dc_fallback,
+        },
+        user_ip_policy: EffectiveUserIpPolicyLimits {
+            global_each: cfg.access.user_max_unique_ips_global_each,
+            mode: user_max_unique_ips_mode_label(cfg.access.user_max_unique_ips_mode),
+            window_secs: cfg.access.user_max_unique_ips_window_secs,
+        },
+    }
+}
+
+pub(super) fn build_security_posture_data(cfg: &ProxyConfig) -> SecurityPostureData {
+    SecurityPostureData {
+        api_read_only: cfg.server.api.read_only,
+        api_whitelist_enabled: !cfg.server.api.whitelist.is_empty(),
+        api_whitelist_entries: cfg.server.api.whitelist.len(),
+        api_auth_header_enabled: !cfg.server.api.auth_header.is_empty(),
+        proxy_protocol_enabled: cfg.server.proxy_protocol,
+        log_level: cfg.general.log_level.to_string(),
+        telemetry_core_enabled: cfg.general.telemetry.core_enabled,
+        telemetry_user_enabled: cfg.general.telemetry.user_enabled,
+        telemetry_me_level: cfg.general.telemetry.me_level.to_string(),
+    }
+}
+
+fn user_max_unique_ips_mode_label(mode: UserMaxUniqueIpsMode) -> &'static str {
+    match mode {
+        UserMaxUniqueIpsMode::ActiveWindow => "active_window",
+        UserMaxUniqueIpsMode::TimeWindow => "time_window",
+        UserMaxUniqueIpsMode::Combined => "combined",
+    }
+}
+
+fn me_floor_mode_label(mode: MeFloorMode) -> &'static str {
+    match mode {
+        MeFloorMode::Static => "static",
+        MeFloorMode::Adaptive => "adaptive",
+    }
+}
+
+fn me_writer_pick_mode_label(mode: MeWriterPickMode) -> &'static str {
+    match mode {
+        MeWriterPickMode::SortedRr => "sorted_rr",
+        MeWriterPickMode::P2c => "p2c",
+    }
+}

src/api/users.rs

@@ -0,0 +1,560 @@
+use std::net::IpAddr;
+
+use hyper::StatusCode;
+
+use crate::config::ProxyConfig;
+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,
+};
+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,
+};
+
+pub(super) async fn create_user(
+    body: CreateUserRequest,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(CreateUserResponse, String), ApiFailure> {
+    let touches_user_ad_tags = body.user_ad_tag.is_some();
+    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_max_unique_ips = body.max_unique_ips.is_some();
+
+    if !is_valid_username(&body.username) {
+        return Err(ApiFailure::bad_request(
+            "username must match [A-Za-z0-9_.-] and be 1..64 chars",
+        ));
+    }
+
+    let secret = match body.secret {
+        Some(secret) => {
+            if !is_valid_user_secret(&secret) {
+                return Err(ApiFailure::bad_request(
+                    "secret must be exactly 32 hex characters",
+                ));
+            }
+            secret
+        }
+        None => random_user_secret(),
+    };
+
+    if let Some(ad_tag) = body.user_ad_tag.as_ref() && !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 _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?;
+
+    if cfg.access.users.contains_key(&body.username) {
+        return Err(ApiFailure::new(
+            StatusCode::CONFLICT,
+            "user_exists",
+            "User already exists",
+        ));
+    }
+
+    cfg.access.users.insert(body.username.clone(), secret.clone());
+    if let Some(ad_tag) = body.user_ad_tag {
+        cfg.access.user_ad_tags.insert(body.username.clone(), ad_tag);
+    }
+    if let Some(limit) = body.max_tcp_conns {
+        cfg.access.user_max_tcp_conns.insert(body.username.clone(), limit);
+    }
+    if let Some(expiration) = expiration {
+        cfg.access
+            .user_expirations
+            .insert(body.username.clone(), expiration);
+    }
+    if let Some(quota) = body.data_quota_bytes {
+        cfg.access.user_data_quota.insert(body.username.clone(), quota);
+    }
+
+    let updated_limit = body.max_unique_ips;
+    if let Some(limit) = updated_limit {
+        cfg.access
+            .user_max_unique_ips
+            .insert(body.username.clone(), limit);
+    }
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+
+    let mut touched_sections = vec![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_max_unique_ips {
+        touched_sections.push(AccessSection::UserMaxUniqueIps);
+    }
+
+    let revision = 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(&body.username, limit).await;
+    }
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+    )
+    .await;
+    let user = users
+        .into_iter()
+        .find(|entry| entry.username == body.username)
+        .unwrap_or(UserInfo {
+            username: body.username.clone(),
+            user_ad_tag: None,
+            max_tcp_conns: None,
+            expiration_rfc3339: None,
+            data_quota_bytes: None,
+            max_unique_ips: updated_limit,
+            current_connections: 0,
+            active_unique_ips: 0,
+            active_unique_ips_list: Vec::new(),
+            recent_unique_ips: 0,
+            recent_unique_ips_list: Vec::new(),
+            total_octets: 0,
+            links: build_user_links(
+                &cfg,
+                &secret,
+                detected_ip_v4,
+                detected_ip_v6,
+            ),
+        });
+
+    Ok((CreateUserResponse { user, secret }, revision))
+}
+
+pub(super) async fn patch_user(
+    user: &str,
+    body: PatchUserRequest,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(UserInfo, String), ApiFailure> {
+    if let Some(secret) = body.secret.as_ref() && !is_valid_user_secret(secret) {
+        return Err(ApiFailure::bad_request(
+            "secret must be exactly 32 hex characters",
+        ));
+    }
+    if let Some(ad_tag) = body.user_ad_tag.as_ref() && !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 _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?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+
+    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);
+    }
+    if let Some(limit) = body.max_tcp_conns {
+        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);
+    }
+    if let Some(quota) = body.data_quota_bytes {
+        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);
+    }
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+
+    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    drop(_guard);
+    if let Some(limit) = updated_limit {
+        shared.ip_tracker.set_user_limit(user, limit).await;
+    }
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+    )
+    .await;
+    let user_info = users
+        .into_iter()
+        .find(|entry| entry.username == user)
+        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
+
+    Ok((user_info, revision))
+}
+
+pub(super) async fn rotate_secret(
+    user: &str,
+    body: RotateSecretRequest,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(CreateUserResponse, String), ApiFailure> {
+    let secret = body.secret.unwrap_or_else(random_user_secret);
+    if !is_valid_user_secret(&secret) {
+        return Err(ApiFailure::bad_request(
+            "secret must be exactly 32 hex characters",
+        ));
+    }
+
+    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?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+
+    cfg.access.users.insert(user.to_string(), secret.clone());
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+    let touched_sections = [
+        AccessSection::Users,
+        AccessSection::UserAdTags,
+        AccessSection::UserMaxTcpConns,
+        AccessSection::UserExpirations,
+        AccessSection::UserDataQuota,
+        AccessSection::UserMaxUniqueIps,
+    ];
+    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
+    drop(_guard);
+
+    let (detected_ip_v4, detected_ip_v6) = shared.detected_link_ips();
+    let users = users_from_config(
+        &cfg,
+        &shared.stats,
+        &shared.ip_tracker,
+        detected_ip_v4,
+        detected_ip_v6,
+    )
+    .await;
+    let user_info = users
+        .into_iter()
+        .find(|entry| entry.username == user)
+        .ok_or_else(|| ApiFailure::internal("failed to build updated user view"))?;
+
+    Ok((
+        CreateUserResponse {
+            user: user_info,
+            secret,
+        },
+        revision,
+    ))
+}
+
+pub(super) async fn delete_user(
+    user: &str,
+    expected_revision: Option<String>,
+    shared: &ApiShared,
+) -> Result<(String, String), ApiFailure> {
+    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?;
+
+    if !cfg.access.users.contains_key(user) {
+        return Err(ApiFailure::new(
+            StatusCode::NOT_FOUND,
+            "not_found",
+            "User not found",
+        ));
+    }
+    if cfg.access.users.len() <= 1 {
+        return Err(ApiFailure::new(
+            StatusCode::CONFLICT,
+            "last_user_forbidden",
+            "Cannot delete the last configured user",
+        ));
+    }
+
+    cfg.access.users.remove(user);
+    cfg.access.user_ad_tags.remove(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_max_unique_ips.remove(user);
+
+    cfg.validate()
+        .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
+    let touched_sections = [
+        AccessSection::Users,
+        AccessSection::UserAdTags,
+        AccessSection::UserMaxTcpConns,
+        AccessSection::UserExpirations,
+        AccessSection::UserDataQuota,
+        AccessSection::UserMaxUniqueIps,
+    ];
+    let revision = save_access_sections_to_disk(&shared.config_path, &cfg, &touched_sections).await?;
+    drop(_guard);
+    shared.ip_tracker.remove_user_limit(user).await;
+    shared.ip_tracker.clear_user_ips(user).await;
+
+    Ok((user.to_string(), revision))
+}
+
+pub(super) async fn users_from_config(
+    cfg: &ProxyConfig,
+    stats: &Stats,
+    ip_tracker: &UserIpTracker,
+    startup_detected_ip_v4: Option<IpAddr>,
+    startup_detected_ip_v6: Option<IpAddr>,
+) -> Vec<UserInfo> {
+    let mut names = cfg.access.users.keys().cloned().collect::<Vec<_>>();
+    names.sort();
+    let active_ip_lists = ip_tracker.get_active_ips_for_users(&names).await;
+    let recent_ip_lists = ip_tracker.get_recent_ips_for_users(&names).await;
+
+    let mut users = Vec::with_capacity(names.len());
+    for username in names {
+        let active_ip_list = active_ip_lists
+            .get(&username)
+            .cloned()
+            .unwrap_or_else(Vec::new);
+        let recent_ip_list = recent_ip_lists
+            .get(&username)
+            .cloned()
+            .unwrap_or_else(Vec::new);
+        let links = cfg
+            .access
+            .users
+            .get(&username)
+            .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(),
+            });
+        users.push(UserInfo {
+            user_ad_tag: cfg.access.user_ad_tags.get(&username).cloned(),
+            max_tcp_conns: cfg.access.user_max_tcp_conns.get(&username).copied(),
+            expiration_rfc3339: cfg
+                .access
+                .user_expirations
+                .get(&username)
+                .map(chrono::DateTime::<chrono::Utc>::to_rfc3339),
+            data_quota_bytes: cfg.access.user_data_quota.get(&username).copied(),
+            max_unique_ips: cfg
+                .access
+                .user_max_unique_ips
+                .get(&username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or(
+                    (cfg.access.user_max_unique_ips_global_each > 0)
+                        .then_some(cfg.access.user_max_unique_ips_global_each),
+                ),
+            current_connections: stats.get_user_curr_connects(&username),
+            active_unique_ips: active_ip_list.len(),
+            active_unique_ips_list: active_ip_list,
+            recent_unique_ips: recent_ip_list.len(),
+            recent_unique_ips_list: recent_ip_list,
+            total_octets: stats.get_user_total_octets(&username),
+            links,
+            username,
+        });
+    }
+    users
+}
+
+fn build_user_links(
+    cfg: &ProxyConfig,
+    secret: &str,
+    startup_detected_ip_v4: Option<IpAddr>,
+    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 tls_domains = resolve_tls_domains(cfg);
+
+    let mut classic = Vec::new();
+    let mut secure = Vec::new();
+    let mut tls = Vec::new();
+
+    for host in &hosts {
+        if cfg.general.modes.classic {
+            classic.push(format!(
+                "tg://proxy?server={}&port={}&secret={}",
+                host, port, secret
+            ));
+        }
+        if cfg.general.modes.secure {
+            secure.push(format!(
+                "tg://proxy?server={}&port={}&secret=dd{}",
+                host, port, secret
+            ));
+        }
+        if cfg.general.modes.tls {
+            for domain in &tls_domains {
+                let domain_hex = hex::encode(domain);
+                tls.push(format!(
+                    "tg://proxy?server={}&port={}&secret=ee{}{}",
+                    host, port, secret, domain_hex
+                ));
+            }
+        }
+    }
+
+    UserLinks {
+        classic,
+        secure,
+        tls,
+    }
+}
+
+fn resolve_link_hosts(
+    cfg: &ProxyConfig,
+    startup_detected_ip_v4: Option<IpAddr>,
+    startup_detected_ip_v6: Option<IpAddr>,
+) -> Vec<String> {
+    if let Some(host) = cfg
+        .general
+        .links
+        .public_host
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        return vec![host.to_string()];
+    }
+
+    let mut hosts = Vec::new();
+    for listener in &cfg.server.listeners {
+        if let Some(host) = listener
+            .announce
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        {
+            push_unique_host(&mut hosts, host);
+            continue;
+        }
+        if let Some(ip) = listener.announce_ip {
+            if !ip.is_unspecified() {
+                push_unique_host(&mut hosts, &ip.to_string());
+                continue;
+            }
+        }
+        if listener.ip.is_unspecified() {
+            let detected_ip = if listener.ip.is_ipv4() {
+                startup_detected_ip_v4
+            } else {
+                startup_detected_ip_v6
+            };
+            if let Some(ip) = detected_ip {
+                push_unique_host(&mut hosts, &ip.to_string());
+            } else {
+                push_unique_host(&mut hosts, &listener.ip.to_string());
+            }
+            continue;
+        }
+        push_unique_host(&mut hosts, &listener.ip.to_string());
+    }
+
+    if !hosts.is_empty() {
+        return hosts;
+    }
+
+    if let Some(ip) = startup_detected_ip_v4.or(startup_detected_ip_v6) {
+        return vec![ip.to_string()];
+    }
+
+    if let Some(host) = cfg.server.listen_addr_ipv4.as_deref() {
+        push_host_from_legacy_listen(&mut hosts, host);
+    }
+    if let Some(host) = cfg.server.listen_addr_ipv6.as_deref() {
+        push_host_from_legacy_listen(&mut hosts, host);
+    }
+    if !hosts.is_empty() {
+        return hosts;
+    }
+
+    vec!["UNKNOWN".to_string()]
+}
+
+fn push_host_from_legacy_listen(hosts: &mut Vec<String>, raw: &str) {
+    let candidate = raw.trim();
+    if candidate.is_empty() {
+        return;
+    }
+
+    match candidate.parse::<IpAddr>() {
+        Ok(ip) if ip.is_unspecified() => {}
+        Ok(ip) => push_unique_host(hosts, &ip.to_string()),
+        Err(_) => push_unique_host(hosts, candidate),
+    }
+}
+
+fn push_unique_host(hosts: &mut Vec<String>, candidate: &str) {
+    if !hosts.iter().any(|existing| existing == candidate) {
+        hosts.push(candidate.to_string());
+    }
+}
+
+fn resolve_tls_domains(cfg: &ProxyConfig) -> Vec<&str> {
+    let mut domains = Vec::with_capacity(1 + cfg.censorship.tls_domains.len());
+    let primary = cfg.censorship.tls_domain.as_str();
+    if !primary.is_empty() {
+        domains.push(primary);
+    }
+    for domain in &cfg.censorship.tls_domains {
+        let value = domain.as_str();
+        if value.is_empty() || domains.contains(&value) {
+            continue;
+        }
+        domains.push(value);
+    }
+    domains
+}

src/config/defaults.rs

@@ -9,8 +9,37 @@ const DEFAULT_MIDDLE_PROXY_WARM_STANDBY: usize = 16;
 const DEFAULT_ME_RECONNECT_MAX_CONCURRENT_PER_DC: u32 = 8;
 const DEFAULT_ME_RECONNECT_FAST_RETRY_COUNT: u32 = 16;
 const DEFAULT_ME_SINGLE_ENDPOINT_SHADOW_WRITERS: u8 = 2;
-const DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS: u32 = 3;
-const DEFAULT_UPSTREAM_UNHEALTHY_FAIL_THRESHOLD: u32 = 4;
+const DEFAULT_ME_ADAPTIVE_FLOOR_IDLE_SECS: u64 = 90;
+const DEFAULT_ME_ADAPTIVE_FLOOR_MIN_WRITERS_SINGLE_ENDPOINT: u8 = 1;
+const DEFAULT_ME_ADAPTIVE_FLOOR_MIN_WRITERS_MULTI_ENDPOINT: u8 = 1;
+const DEFAULT_ME_ADAPTIVE_FLOOR_RECOVER_GRACE_SECS: u64 = 180;
+const DEFAULT_ME_ADAPTIVE_FLOOR_WRITERS_PER_CORE_TOTAL: u16 = 48;
+const DEFAULT_ME_ADAPTIVE_FLOOR_CPU_CORES_OVERRIDE: u16 = 0;
+const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_EXTRA_WRITERS_SINGLE_PER_CORE: u16 = 1;
+const DEFAULT_ME_ADAPTIVE_FLOOR_MAX_EXTRA_WRITERS_MULTI_PER_CORE: u16 = 2;
+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_WRITER_CMD_CHANNEL_CAPACITY: usize = 4096;
+const DEFAULT_ME_ROUTE_CHANNEL_CAPACITY: usize = 768;
+const DEFAULT_ME_C2ME_CHANNEL_CAPACITY: usize = 1024;
+const DEFAULT_ME_READER_ROUTE_DATA_WAIT_MS: u64 = 2;
+const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_FRAMES: usize = 32;
+const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_BYTES: usize = 128 * 1024;
+const DEFAULT_ME_D2C_FLUSH_BATCH_MAX_DELAY_US: u64 = 1500;
+const DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE: bool = false;
+const DEFAULT_DIRECT_RELAY_COPY_BUF_C2S_BYTES: usize = 64 * 1024;
+const DEFAULT_DIRECT_RELAY_COPY_BUF_S2C_BYTES: usize = 256 * 1024;
+const DEFAULT_ME_WRITER_PICK_SAMPLE_SIZE: u8 = 3;
+const DEFAULT_ME_HEALTH_INTERVAL_MS_UNHEALTHY: u64 = 1000;
+const DEFAULT_ME_HEALTH_INTERVAL_MS_HEALTHY: u64 = 3000;
+const DEFAULT_ME_ADMISSION_POLL_MS: u64 = 1000;
+const DEFAULT_ME_WARN_RATE_LIMIT_MS: u64 = 5000;
+const DEFAULT_USER_MAX_UNIQUE_IPS_WINDOW_SECS: u64 = 30;
+const DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS: u32 = 2;
+const DEFAULT_UPSTREAM_UNHEALTHY_FAIL_THRESHOLD: u32 = 5;
+const DEFAULT_UPSTREAM_CONNECT_BUDGET_MS: u64 = 3000;
 const DEFAULT_LISTEN_ADDR_IPV6: &str = "::";
 const DEFAULT_ACCESS_USER: &str = "default";
 const DEFAULT_ACCESS_SECRET: &str = "00000000000000000000000000000000";
@@ -89,6 +118,39 @@ pub(crate) fn default_metrics_whitelist() -> Vec<IpNetwork> {
     ]
 }
 
+pub(crate) fn default_api_listen() -> String {
+    "0.0.0.0:9091".to_string()
+}
+
+pub(crate) fn default_api_whitelist() -> Vec<IpNetwork> {
+    vec!["127.0.0.0/8".parse().unwrap()]
+}
+
+pub(crate) fn default_api_request_body_limit_bytes() -> usize {
+    64 * 1024
+}
+
+pub(crate) fn default_api_minimal_runtime_enabled() -> bool {
+    true
+}
+
+pub(crate) fn default_api_minimal_runtime_cache_ttl_ms() -> u64 {
+    1000
+}
+
+pub(crate) fn default_api_runtime_edge_enabled() -> bool { false }
+pub(crate) fn default_api_runtime_edge_cache_ttl_ms() -> u64 { 1000 }
+pub(crate) fn default_api_runtime_edge_top_n() -> usize { 10 }
+pub(crate) fn default_api_runtime_edge_events_capacity() -> usize { 256 }
+
+pub(crate) fn default_proxy_protocol_header_timeout_ms() -> u64 {
+    500
+}
+
+pub(crate) fn default_server_max_connections() -> u32 {
+    10_000
+}
+
 pub(crate) fn default_prefer_4() -> u8 {
     4
 }
@@ -105,6 +167,10 @@ pub(crate) fn default_unknown_dc_log_path() -> Option<String> {
     Some("unknown-dc.txt".to_string())
 }
 
+pub(crate) fn default_unknown_dc_file_log_enabled() -> bool {
+    false
+}
+
 pub(crate) fn default_pool_size() -> usize {
     8
 }
@@ -113,6 +179,14 @@ pub(crate) fn default_proxy_secret_path() -> Option<String> {
     Some("proxy-secret".to_string())
 }
 
+pub(crate) fn default_proxy_config_v4_cache_path() -> Option<String> {
+    Some("cache/proxy-config-v4.txt".to_string())
+}
+
+pub(crate) fn default_proxy_config_v6_cache_path() -> Option<String> {
+    Some("cache/proxy-config-v6.txt".to_string())
+}
+
 pub(crate) fn default_middle_proxy_nat_stun() -> Option<String> {
     None
 }
@@ -129,12 +203,20 @@ pub(crate) fn default_middle_proxy_warm_standby() -> usize {
     DEFAULT_MIDDLE_PROXY_WARM_STANDBY
 }
 
+pub(crate) fn default_me_init_retry_attempts() -> u32 {
+    0
+}
+
+pub(crate) fn default_me2dc_fallback() -> bool {
+    true
+}
+
 pub(crate) fn default_keepalive_interval() -> u64 {
-    25
+    8
 }
 
 pub(crate) fn default_keepalive_jitter() -> u64 {
-    5
+    2
 }
 
 pub(crate) fn default_warmup_step_delay_ms() -> u64 {
@@ -185,18 +267,138 @@ pub(crate) fn default_me_single_endpoint_shadow_rotate_every_secs() -> u64 {
     900
 }
 
+pub(crate) fn default_me_adaptive_floor_idle_secs() -> u64 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_IDLE_SECS
+}
+
+pub(crate) fn default_me_adaptive_floor_min_writers_single_endpoint() -> u8 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MIN_WRITERS_SINGLE_ENDPOINT
+}
+
+pub(crate) fn default_me_adaptive_floor_min_writers_multi_endpoint() -> u8 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MIN_WRITERS_MULTI_ENDPOINT
+}
+
+pub(crate) fn default_me_adaptive_floor_recover_grace_secs() -> u64 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_RECOVER_GRACE_SECS
+}
+
+pub(crate) fn default_me_adaptive_floor_writers_per_core_total() -> u16 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_WRITERS_PER_CORE_TOTAL
+}
+
+pub(crate) fn default_me_adaptive_floor_cpu_cores_override() -> u16 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_CPU_CORES_OVERRIDE
+}
+
+pub(crate) fn default_me_adaptive_floor_max_extra_writers_single_per_core() -> u16 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MAX_EXTRA_WRITERS_SINGLE_PER_CORE
+}
+
+pub(crate) fn default_me_adaptive_floor_max_extra_writers_multi_per_core() -> u16 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MAX_EXTRA_WRITERS_MULTI_PER_CORE
+}
+
+pub(crate) fn default_me_adaptive_floor_max_active_writers_per_core() -> u16 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_PER_CORE
+}
+
+pub(crate) fn default_me_adaptive_floor_max_warm_writers_per_core() -> u16 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_PER_CORE
+}
+
+pub(crate) fn default_me_adaptive_floor_max_active_writers_global() -> u32 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MAX_ACTIVE_WRITERS_GLOBAL
+}
+
+pub(crate) fn default_me_adaptive_floor_max_warm_writers_global() -> u32 {
+    DEFAULT_ME_ADAPTIVE_FLOOR_MAX_WARM_WRITERS_GLOBAL
+}
+
+pub(crate) fn default_me_writer_cmd_channel_capacity() -> usize {
+    DEFAULT_ME_WRITER_CMD_CHANNEL_CAPACITY
+}
+
+pub(crate) fn default_me_route_channel_capacity() -> usize {
+    DEFAULT_ME_ROUTE_CHANNEL_CAPACITY
+}
+
+pub(crate) fn default_me_c2me_channel_capacity() -> usize {
+    DEFAULT_ME_C2ME_CHANNEL_CAPACITY
+}
+
+pub(crate) fn default_me_reader_route_data_wait_ms() -> u64 {
+    DEFAULT_ME_READER_ROUTE_DATA_WAIT_MS
+}
+
+pub(crate) fn default_me_d2c_flush_batch_max_frames() -> usize {
+    DEFAULT_ME_D2C_FLUSH_BATCH_MAX_FRAMES
+}
+
+pub(crate) fn default_me_d2c_flush_batch_max_bytes() -> usize {
+    DEFAULT_ME_D2C_FLUSH_BATCH_MAX_BYTES
+}
+
+pub(crate) fn default_me_d2c_flush_batch_max_delay_us() -> u64 {
+    DEFAULT_ME_D2C_FLUSH_BATCH_MAX_DELAY_US
+}
+
+pub(crate) fn default_me_d2c_ack_flush_immediate() -> bool {
+    DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE
+}
+
+pub(crate) fn default_direct_relay_copy_buf_c2s_bytes() -> usize {
+    DEFAULT_DIRECT_RELAY_COPY_BUF_C2S_BYTES
+}
+
+pub(crate) fn default_direct_relay_copy_buf_s2c_bytes() -> usize {
+    DEFAULT_DIRECT_RELAY_COPY_BUF_S2C_BYTES
+}
+
+pub(crate) fn default_me_writer_pick_sample_size() -> u8 {
+    DEFAULT_ME_WRITER_PICK_SAMPLE_SIZE
+}
+
+pub(crate) fn default_me_health_interval_ms_unhealthy() -> u64 {
+    DEFAULT_ME_HEALTH_INTERVAL_MS_UNHEALTHY
+}
+
+pub(crate) fn default_me_health_interval_ms_healthy() -> u64 {
+    DEFAULT_ME_HEALTH_INTERVAL_MS_HEALTHY
+}
+
+pub(crate) fn default_me_admission_poll_ms() -> u64 {
+    DEFAULT_ME_ADMISSION_POLL_MS
+}
+
+pub(crate) fn default_me_warn_rate_limit_ms() -> u64 {
+    DEFAULT_ME_WARN_RATE_LIMIT_MS
+}
+
 pub(crate) fn default_upstream_connect_retry_attempts() -> u32 {
     DEFAULT_UPSTREAM_CONNECT_RETRY_ATTEMPTS
 }
 
 pub(crate) fn default_upstream_connect_retry_backoff_ms() -> u64 {
-    250
+    100
 }
 
 pub(crate) fn default_upstream_unhealthy_fail_threshold() -> u32 {
     DEFAULT_UPSTREAM_UNHEALTHY_FAIL_THRESHOLD
 }
 
+pub(crate) fn default_upstream_connect_budget_ms() -> u64 {
+    DEFAULT_UPSTREAM_CONNECT_BUDGET_MS
+}
+
+pub(crate) fn default_upstream_connect_failfast_hard_errors() -> bool {
+    false
+}
+
+pub(crate) fn default_rpc_proxy_req_every() -> u64 {
+    0
+}
+
 pub(crate) fn default_crypto_pending_buffer() -> usize {
     256 * 1024
 }
@@ -221,6 +423,18 @@ pub(crate) fn default_me_route_backpressure_high_watermark_pct() -> u8 {
     80
 }
 
+pub(crate) fn default_me_route_no_writer_wait_ms() -> u64 {
+    250
+}
+
+pub(crate) fn default_me_route_inline_recovery_attempts() -> u32 {
+    3
+}
+
+pub(crate) fn default_me_route_inline_recovery_wait_ms() -> u64 {
+    3000
+}
+
 pub(crate) fn default_beobachten_minutes() -> u64 {
     10
 }
@@ -374,6 +588,10 @@ pub(crate) fn default_me_pool_drain_ttl_secs() -> u64 {
     90
 }
 
+pub(crate) fn default_me_pool_drain_threshold() -> u64 {
+    128
+}
+
 pub(crate) fn default_me_bind_stale_ttl_secs() -> u64 {
     default_me_pool_drain_ttl_secs()
 }
@@ -421,6 +639,14 @@ pub(crate) fn default_access_users() -> HashMap<String, String> {
     )])
 }
 
+pub(crate) fn default_user_max_unique_ips_window_secs() -> u64 {
+    DEFAULT_USER_MAX_UNIQUE_IPS_WINDOW_SECS
+}
+
+pub(crate) fn default_user_max_unique_ips_global_each() -> usize {
+    0
+}
+
 // Custom deserializer helpers
 
 #[derive(Deserialize)]

src/config/load.rs

@@ -1,8 +1,9 @@
 #![allow(deprecated)]
 
-use std::collections::HashMap;
-use std::net::IpAddr;
-use std::path::Path;
+use std::collections::{BTreeSet, HashMap};
+use std::hash::{DefaultHasher, Hash, Hasher};
+use std::net::{IpAddr, SocketAddr};
+use std::path::{Path, PathBuf};
 
 use rand::Rng;
 use tracing::warn;
@@ -13,7 +14,37 @@ use crate::error::{ProxyError, Result};
 use super::defaults::*;
 use super::types::*;
 
-fn preprocess_includes(content: &str, base_dir: &Path, depth: u8) -> Result<String> {
+#[derive(Debug, Clone)]
+pub(crate) struct LoadedConfig {
+    pub(crate) config: ProxyConfig,
+    pub(crate) source_files: Vec<PathBuf>,
+    pub(crate) rendered_hash: u64,
+}
+
+fn normalize_config_path(path: &Path) -> PathBuf {
+    path.canonicalize().unwrap_or_else(|_| {
+        if path.is_absolute() {
+            path.to_path_buf()
+        } else {
+            std::env::current_dir()
+                .map(|cwd| cwd.join(path))
+                .unwrap_or_else(|_| path.to_path_buf())
+        }
+    })
+}
+
+fn hash_rendered_snapshot(rendered: &str) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    rendered.hash(&mut hasher);
+    hasher.finish()
+}
+
+fn preprocess_includes(
+    content: &str,
+    base_dir: &Path,
+    depth: u8,
+    source_files: &mut BTreeSet<PathBuf>,
+) -> Result<String> {
     if depth > 10 {
         return Err(ProxyError::Config("Include depth > 10".into()));
     }
@@ -25,10 +56,16 @@ fn preprocess_includes(content: &str, base_dir: &Path, depth: u8) -> Result<Stri
             if let Some(rest) = rest.strip_prefix('=') {
                 let path_str = rest.trim().trim_matches('"');
                 let resolved = base_dir.join(path_str);
+                source_files.insert(normalize_config_path(&resolved));
                 let included = std::fs::read_to_string(&resolved)
                     .map_err(|e| ProxyError::Config(e.to_string()))?;
                 let included_dir = resolved.parent().unwrap_or(base_dir);
-                output.push_str(&preprocess_includes(&included, included_dir, depth + 1)?);
+                output.push_str(&preprocess_includes(
+                    &included,
+                    included_dir,
+                    depth + 1,
+                    source_files,
+                )?);
                 output.push('\n');
                 continue;
             }
@@ -138,10 +175,16 @@ pub struct ProxyConfig {
 
 impl ProxyConfig {
     pub fn load<P: AsRef<Path>>(path: P) -> Result<Self> {
-        let content =
-            std::fs::read_to_string(&path).map_err(|e| ProxyError::Config(e.to_string()))?;
-        let base_dir = path.as_ref().parent().unwrap_or(Path::new("."));
-        let processed = preprocess_includes(&content, base_dir, 0)?;
+        Self::load_with_metadata(path).map(|loaded| loaded.config)
+    }
+
+    pub(crate) fn load_with_metadata<P: AsRef<Path>>(path: P) -> Result<LoadedConfig> {
+        let path = path.as_ref();
+        let content = std::fs::read_to_string(path).map_err(|e| ProxyError::Config(e.to_string()))?;
+        let base_dir = path.parent().unwrap_or(Path::new("."));
+        let mut source_files = BTreeSet::new();
+        source_files.insert(normalize_config_path(path));
+        let processed = preprocess_includes(&content, base_dir, 0, &mut source_files)?;
 
         let parsed_toml: toml::Value =
             toml::from_str(&processed).map_err(|e| ProxyError::Config(e.to_string()))?;
@@ -203,6 +246,22 @@ impl ProxyConfig {
 
         sanitize_ad_tag(&mut config.general.ad_tag);
 
+        if let Some(path) = &config.general.proxy_config_v4_cache_path
+            && path.trim().is_empty()
+        {
+            return Err(ProxyError::Config(
+                "general.proxy_config_v4_cache_path cannot be empty when provided".to_string(),
+            ));
+        }
+
+        if let Some(path) = &config.general.proxy_config_v6_cache_path
+            && path.trim().is_empty()
+        {
+            return Err(ProxyError::Config(
+                "general.proxy_config_v6_cache_path cannot be empty when provided".to_string(),
+            ));
+        }
+
         if let Some(update_every) = config.general.update_every {
             if update_every == 0 {
                 return Err(ProxyError::Config(
@@ -237,18 +296,122 @@ impl ProxyConfig {
             ));
         }
 
+        if config.general.me_init_retry_attempts > 1_000_000 {
+            return Err(ProxyError::Config(
+                "general.me_init_retry_attempts must be within [0, 1000000]".to_string(),
+            ));
+        }
+
         if config.general.upstream_connect_retry_attempts == 0 {
             return Err(ProxyError::Config(
                 "general.upstream_connect_retry_attempts must be > 0".to_string(),
             ));
         }
 
+        if config.general.upstream_connect_budget_ms == 0 {
+            return Err(ProxyError::Config(
+                "general.upstream_connect_budget_ms must be > 0".to_string(),
+            ));
+        }
+
         if config.general.upstream_unhealthy_fail_threshold == 0 {
             return Err(ProxyError::Config(
                 "general.upstream_unhealthy_fail_threshold must be > 0".to_string(),
             ));
         }
 
+        if config.general.rpc_proxy_req_every != 0
+            && !(10..=300).contains(&config.general.rpc_proxy_req_every)
+        {
+            return Err(ProxyError::Config(
+                "general.rpc_proxy_req_every must be 0 or within [10, 300]".to_string(),
+            ));
+        }
+
+        if config.general.me_writer_cmd_channel_capacity == 0 {
+            return Err(ProxyError::Config(
+                "general.me_writer_cmd_channel_capacity must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_route_channel_capacity == 0 {
+            return Err(ProxyError::Config(
+                "general.me_route_channel_capacity must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_c2me_channel_capacity == 0 {
+            return Err(ProxyError::Config(
+                "general.me_c2me_channel_capacity must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_reader_route_data_wait_ms > 20 {
+            return Err(ProxyError::Config(
+                "general.me_reader_route_data_wait_ms must be within [0, 20]".to_string(),
+            ));
+        }
+
+        if !(1..=512).contains(&config.general.me_d2c_flush_batch_max_frames) {
+            return Err(ProxyError::Config(
+                "general.me_d2c_flush_batch_max_frames must be within [1, 512]".to_string(),
+            ));
+        }
+
+        if !(4096..=2 * 1024 * 1024).contains(&config.general.me_d2c_flush_batch_max_bytes) {
+            return Err(ProxyError::Config(
+                "general.me_d2c_flush_batch_max_bytes must be within [4096, 2097152]".to_string(),
+            ));
+        }
+
+        if config.general.me_d2c_flush_batch_max_delay_us > 5000 {
+            return Err(ProxyError::Config(
+                "general.me_d2c_flush_batch_max_delay_us must be within [0, 5000]".to_string(),
+            ));
+        }
+
+        if !(4096..=1024 * 1024).contains(&config.general.direct_relay_copy_buf_c2s_bytes) {
+            return Err(ProxyError::Config(
+                "general.direct_relay_copy_buf_c2s_bytes must be within [4096, 1048576]".to_string(),
+            ));
+        }
+
+        if !(8192..=2 * 1024 * 1024).contains(&config.general.direct_relay_copy_buf_s2c_bytes) {
+            return Err(ProxyError::Config(
+                "general.direct_relay_copy_buf_s2c_bytes must be within [8192, 2097152]".to_string(),
+            ));
+        }
+
+        if config.general.me_health_interval_ms_unhealthy == 0 {
+            return Err(ProxyError::Config(
+                "general.me_health_interval_ms_unhealthy must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_health_interval_ms_healthy == 0 {
+            return Err(ProxyError::Config(
+                "general.me_health_interval_ms_healthy must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_admission_poll_ms == 0 {
+            return Err(ProxyError::Config(
+                "general.me_admission_poll_ms must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_warn_rate_limit_ms == 0 {
+            return Err(ProxyError::Config(
+                "general.me_warn_rate_limit_ms must be > 0".to_string(),
+            ));
+        }
+
+        if config.access.user_max_unique_ips_window_secs == 0 {
+            return Err(ProxyError::Config(
+                "access.user_max_unique_ips_window_secs must be > 0".to_string(),
+            ));
+        }
+
         if config.general.me_reinit_every_secs == 0 {
             return Err(ProxyError::Config(
                 "general.me_reinit_every_secs must be > 0".to_string(),
@@ -261,6 +424,54 @@ impl ProxyConfig {
             ));
         }
 
+        if config.general.me_adaptive_floor_min_writers_single_endpoint == 0
+            || config.general.me_adaptive_floor_min_writers_single_endpoint > 32
+        {
+            return Err(ProxyError::Config(
+                "general.me_adaptive_floor_min_writers_single_endpoint must be within [1, 32]"
+                    .to_string(),
+            ));
+        }
+
+        if config.general.me_adaptive_floor_min_writers_multi_endpoint == 0
+            || config.general.me_adaptive_floor_min_writers_multi_endpoint > 32
+        {
+            return Err(ProxyError::Config(
+                "general.me_adaptive_floor_min_writers_multi_endpoint must be within [1, 32]"
+                    .to_string(),
+            ));
+        }
+
+        if config.general.me_adaptive_floor_writers_per_core_total == 0 {
+            return Err(ProxyError::Config(
+                "general.me_adaptive_floor_writers_per_core_total must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_adaptive_floor_max_active_writers_per_core == 0 {
+            return Err(ProxyError::Config(
+                "general.me_adaptive_floor_max_active_writers_per_core must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_adaptive_floor_max_warm_writers_per_core == 0 {
+            return Err(ProxyError::Config(
+                "general.me_adaptive_floor_max_warm_writers_per_core must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_adaptive_floor_max_active_writers_global == 0 {
+            return Err(ProxyError::Config(
+                "general.me_adaptive_floor_max_active_writers_global must be > 0".to_string(),
+            ));
+        }
+
+        if config.general.me_adaptive_floor_max_warm_writers_global == 0 {
+            return Err(ProxyError::Config(
+                "general.me_adaptive_floor_max_warm_writers_global must be > 0".to_string(),
+            ));
+        }
+
         if config.general.me_single_endpoint_outage_backoff_min_ms == 0 {
             return Err(ProxyError::Config(
                 "general.me_single_endpoint_outage_backoff_min_ms must be > 0".to_string(),
@@ -381,6 +592,72 @@ impl ProxyConfig {
             ));
         }
 
+        if !(10..=5000).contains(&config.general.me_route_no_writer_wait_ms) {
+            return Err(ProxyError::Config(
+                "general.me_route_no_writer_wait_ms must be within [10, 5000]".to_string(),
+            ));
+        }
+
+        if !(2..=4).contains(&config.general.me_writer_pick_sample_size) {
+            return Err(ProxyError::Config(
+                "general.me_writer_pick_sample_size must be within [2, 4]".to_string(),
+            ));
+        }
+
+        if config.general.me_route_inline_recovery_attempts == 0 {
+            return Err(ProxyError::Config(
+                "general.me_route_inline_recovery_attempts must be > 0".to_string(),
+            ));
+        }
+
+        if !(10..=30000).contains(&config.general.me_route_inline_recovery_wait_ms) {
+            return Err(ProxyError::Config(
+                "general.me_route_inline_recovery_wait_ms must be within [10, 30000]".to_string(),
+            ));
+        }
+
+        if config.server.api.request_body_limit_bytes == 0 {
+            return Err(ProxyError::Config(
+                "server.api.request_body_limit_bytes must be > 0".to_string(),
+            ));
+        }
+
+        if config.server.api.minimal_runtime_cache_ttl_ms > 60_000 {
+            return Err(ProxyError::Config(
+                "server.api.minimal_runtime_cache_ttl_ms must be within [0, 60000]".to_string(),
+            ));
+        }
+
+        if config.server.api.runtime_edge_cache_ttl_ms > 60_000 {
+            return Err(ProxyError::Config(
+                "server.api.runtime_edge_cache_ttl_ms must be within [0, 60000]".to_string(),
+            ));
+        }
+
+        if !(1..=1000).contains(&config.server.api.runtime_edge_top_n) {
+            return Err(ProxyError::Config(
+                "server.api.runtime_edge_top_n must be within [1, 1000]".to_string(),
+            ));
+        }
+
+        if !(16..=4096).contains(&config.server.api.runtime_edge_events_capacity) {
+            return Err(ProxyError::Config(
+                "server.api.runtime_edge_events_capacity must be within [16, 4096]".to_string(),
+            ));
+        }
+
+        if config.server.api.listen.parse::<SocketAddr>().is_err() {
+            return Err(ProxyError::Config(
+                "server.api.listen must be in IP:PORT format".to_string(),
+            ));
+        }
+
+        if config.server.proxy_protocol_header_timeout_ms == 0 {
+            return Err(ProxyError::Config(
+                "server.proxy_protocol_header_timeout_ms must be > 0".to_string(),
+            ));
+        }
+
         if config.general.effective_me_pool_force_close_secs() > 0
             && config.general.effective_me_pool_force_close_secs()
                 < config.general.me_pool_drain_ttl_secs
@@ -462,10 +739,11 @@ impl ProxyConfig {
             warn!("prefer_ipv6 is deprecated, use [network].prefer = 6");
         }
 
-        // Auto-enable NAT probe when Middle Proxy is requested.
-        if config.general.use_middle_proxy && !config.general.middle_proxy_nat_probe {
-            config.general.middle_proxy_nat_probe = true;
-            warn!("Auto-enabled middle_proxy_nat_probe for middle proxy mode");
+        if config.general.use_middle_proxy && !config.general.me_secret_atomic_snapshot {
+            config.general.me_secret_atomic_snapshot = true;
+            warn!(
+                "Auto-enabled me_secret_atomic_snapshot for middle proxy mode to keep KDF key_selector/secret coherent"
+            );
         }
 
         validate_network_cfg(&mut config.network)?;
@@ -551,7 +829,11 @@ impl ProxyConfig {
             .entry("203".to_string())
             .or_insert_with(|| vec!["91.105.192.100:443".to_string()]);
 
-        Ok(config)
+        Ok(LoadedConfig {
+            config,
+            source_files: source_files.into_iter().collect(),
+            rendered_hash: hash_rendered_snapshot(&processed),
+        })
     }
 
     pub fn validate(&self) -> Result<()> {
@@ -618,6 +900,22 @@ mod tests {
             cfg.general.me_reconnect_fast_retry_count,
             default_me_reconnect_fast_retry_count()
         );
+        assert_eq!(
+            cfg.general.me_init_retry_attempts,
+            default_me_init_retry_attempts()
+        );
+        assert_eq!(
+            cfg.general.me2dc_fallback,
+            default_me2dc_fallback()
+        );
+        assert_eq!(
+            cfg.general.proxy_config_v4_cache_path,
+            default_proxy_config_v4_cache_path()
+        );
+        assert_eq!(
+            cfg.general.proxy_config_v6_cache_path,
+            default_proxy_config_v6_cache_path()
+        );
         assert_eq!(
             cfg.general.me_single_endpoint_shadow_writers,
             default_me_single_endpoint_shadow_writers()
@@ -642,6 +940,19 @@ mod tests {
             cfg.general.me_single_endpoint_shadow_rotate_every_secs,
             default_me_single_endpoint_shadow_rotate_every_secs()
         );
+        assert_eq!(cfg.general.me_floor_mode, MeFloorMode::default());
+        assert_eq!(
+            cfg.general.me_adaptive_floor_idle_secs,
+            default_me_adaptive_floor_idle_secs()
+        );
+        assert_eq!(
+            cfg.general.me_adaptive_floor_min_writers_single_endpoint,
+            default_me_adaptive_floor_min_writers_single_endpoint()
+        );
+        assert_eq!(
+            cfg.general.me_adaptive_floor_recover_grace_secs,
+            default_me_adaptive_floor_recover_grace_secs()
+        );
         assert_eq!(
             cfg.general.upstream_connect_retry_attempts,
             default_upstream_connect_retry_attempts()
@@ -654,10 +965,56 @@ mod tests {
             cfg.general.upstream_unhealthy_fail_threshold,
             default_upstream_unhealthy_fail_threshold()
         );
+        assert_eq!(
+            cfg.general.upstream_connect_failfast_hard_errors,
+            default_upstream_connect_failfast_hard_errors()
+        );
+        assert_eq!(
+            cfg.general.rpc_proxy_req_every,
+            default_rpc_proxy_req_every()
+        );
         assert_eq!(cfg.general.update_every, default_update_every());
         assert_eq!(cfg.server.listen_addr_ipv4, default_listen_addr_ipv4());
         assert_eq!(cfg.server.listen_addr_ipv6, default_listen_addr_ipv6_opt());
+        assert_eq!(cfg.server.api.listen, default_api_listen());
+        assert_eq!(cfg.server.api.whitelist, default_api_whitelist());
+        assert_eq!(
+            cfg.server.api.request_body_limit_bytes,
+            default_api_request_body_limit_bytes()
+        );
+        assert_eq!(
+            cfg.server.api.minimal_runtime_enabled,
+            default_api_minimal_runtime_enabled()
+        );
+        assert_eq!(
+            cfg.server.api.minimal_runtime_cache_ttl_ms,
+            default_api_minimal_runtime_cache_ttl_ms()
+        );
+        assert_eq!(
+            cfg.server.api.runtime_edge_enabled,
+            default_api_runtime_edge_enabled()
+        );
+        assert_eq!(
+            cfg.server.api.runtime_edge_cache_ttl_ms,
+            default_api_runtime_edge_cache_ttl_ms()
+        );
+        assert_eq!(
+            cfg.server.api.runtime_edge_top_n,
+            default_api_runtime_edge_top_n()
+        );
+        assert_eq!(
+            cfg.server.api.runtime_edge_events_capacity,
+            default_api_runtime_edge_events_capacity()
+        );
         assert_eq!(cfg.access.users, default_access_users());
+        assert_eq!(
+            cfg.access.user_max_unique_ips_mode,
+            UserMaxUniqueIpsMode::default()
+        );
+        assert_eq!(
+            cfg.access.user_max_unique_ips_window_secs,
+            default_user_max_unique_ips_window_secs()
+        );
     }
 
     #[test]
@@ -680,6 +1037,19 @@ mod tests {
             general.me_reconnect_fast_retry_count,
             default_me_reconnect_fast_retry_count()
         );
+        assert_eq!(
+            general.me_init_retry_attempts,
+            default_me_init_retry_attempts()
+        );
+        assert_eq!(general.me2dc_fallback, default_me2dc_fallback());
+        assert_eq!(
+            general.proxy_config_v4_cache_path,
+            default_proxy_config_v4_cache_path()
+        );
+        assert_eq!(
+            general.proxy_config_v6_cache_path,
+            default_proxy_config_v6_cache_path()
+        );
         assert_eq!(
             general.me_single_endpoint_shadow_writers,
             default_me_single_endpoint_shadow_writers()
@@ -704,6 +1074,19 @@ mod tests {
             general.me_single_endpoint_shadow_rotate_every_secs,
             default_me_single_endpoint_shadow_rotate_every_secs()
         );
+        assert_eq!(general.me_floor_mode, MeFloorMode::default());
+        assert_eq!(
+            general.me_adaptive_floor_idle_secs,
+            default_me_adaptive_floor_idle_secs()
+        );
+        assert_eq!(
+            general.me_adaptive_floor_min_writers_single_endpoint,
+            default_me_adaptive_floor_min_writers_single_endpoint()
+        );
+        assert_eq!(
+            general.me_adaptive_floor_recover_grace_secs,
+            default_me_adaptive_floor_recover_grace_secs()
+        );
         assert_eq!(
             general.upstream_connect_retry_attempts,
             default_upstream_connect_retry_attempts()
@@ -716,10 +1099,45 @@ mod tests {
             general.upstream_unhealthy_fail_threshold,
             default_upstream_unhealthy_fail_threshold()
         );
+        assert_eq!(
+            general.upstream_connect_failfast_hard_errors,
+            default_upstream_connect_failfast_hard_errors()
+        );
+        assert_eq!(general.rpc_proxy_req_every, default_rpc_proxy_req_every());
         assert_eq!(general.update_every, default_update_every());
 
         let server = ServerConfig::default();
         assert_eq!(server.listen_addr_ipv6, Some(default_listen_addr_ipv6()));
+        assert_eq!(server.api.listen, default_api_listen());
+        assert_eq!(server.api.whitelist, default_api_whitelist());
+        assert_eq!(
+            server.api.request_body_limit_bytes,
+            default_api_request_body_limit_bytes()
+        );
+        assert_eq!(
+            server.api.minimal_runtime_enabled,
+            default_api_minimal_runtime_enabled()
+        );
+        assert_eq!(
+            server.api.minimal_runtime_cache_ttl_ms,
+            default_api_minimal_runtime_cache_ttl_ms()
+        );
+        assert_eq!(
+            server.api.runtime_edge_enabled,
+            default_api_runtime_edge_enabled()
+        );
+        assert_eq!(
+            server.api.runtime_edge_cache_ttl_ms,
+            default_api_runtime_edge_cache_ttl_ms()
+        );
+        assert_eq!(
+            server.api.runtime_edge_top_n,
+            default_api_runtime_edge_top_n()
+        );
+        assert_eq!(
+            server.api.runtime_edge_events_capacity,
+            default_api_runtime_edge_events_capacity()
+        );
 
         let access = AccessConfig::default();
         assert_eq!(access.users, default_access_users());
@@ -740,6 +1158,48 @@ mod tests {
         );
     }
 
+    #[test]
+    fn load_with_metadata_collects_include_files() {
+        let nonce = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        let dir = std::env::temp_dir().join(format!("telemt_load_metadata_{nonce}"));
+        std::fs::create_dir_all(&dir).unwrap();
+        let main_path = dir.join("config.toml");
+        let include_path = dir.join("included.toml");
+
+        std::fs::write(
+            &include_path,
+            r#"
+                [access.users]
+                user = "00000000000000000000000000000000"
+            "#,
+        )
+        .unwrap();
+        std::fs::write(
+            &main_path,
+            r#"
+                include = "included.toml"
+
+                [censorship]
+                tls_domain = "example.com"
+            "#,
+        )
+        .unwrap();
+
+        let loaded = ProxyConfig::load_with_metadata(&main_path).unwrap();
+        let main_normalized = normalize_config_path(&main_path);
+        let include_normalized = normalize_config_path(&include_path);
+
+        assert!(loaded.source_files.contains(&main_normalized));
+        assert!(loaded.source_files.contains(&include_normalized));
+
+        let _ = std::fs::remove_file(main_path);
+        let _ = std::fs::remove_file(include_path);
+        let _ = std::fs::remove_dir(dir);
+    }
+
     #[test]
     fn dc_overrides_inject_dc203_default() {
         let toml = r#"
@@ -931,6 +1391,90 @@ mod tests {
         let _ = std::fs::remove_file(path);
     }
 
+    #[test]
+    fn me_adaptive_floor_min_writers_out_of_range_is_rejected() {
+        let toml = r#"
+            [general]
+            me_adaptive_floor_min_writers_single_endpoint = 0
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_me_adaptive_floor_min_writers_out_of_range_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(
+            err.contains(
+                "general.me_adaptive_floor_min_writers_single_endpoint must be within [1, 32]"
+            )
+        );
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn me_floor_mode_adaptive_is_parsed() {
+        let toml = r#"
+            [general]
+            me_floor_mode = "adaptive"
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_me_floor_mode_adaptive_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let cfg = ProxyConfig::load(&path).unwrap();
+        assert_eq!(cfg.general.me_floor_mode, MeFloorMode::Adaptive);
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn me_adaptive_floor_max_active_writers_per_core_zero_is_rejected() {
+        let toml = r#"
+            [general]
+            me_adaptive_floor_max_active_writers_per_core = 0
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_me_adaptive_floor_max_active_per_core_zero_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("general.me_adaptive_floor_max_active_writers_per_core must be > 0"));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn me_adaptive_floor_max_warm_writers_global_zero_is_rejected() {
+        let toml = r#"
+            [general]
+            me_adaptive_floor_max_warm_writers_global = 0
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_me_adaptive_floor_max_warm_global_zero_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("general.me_adaptive_floor_max_warm_writers_global must be > 0"));
+        let _ = std::fs::remove_file(path);
+    }
+
     #[test]
     fn upstream_connect_retry_attempts_zero_is_rejected() {
         let toml = r#"
@@ -971,6 +1515,141 @@ mod tests {
         let _ = std::fs::remove_file(path);
     }
 
+    #[test]
+    fn rpc_proxy_req_every_out_of_range_is_rejected() {
+        let toml = r#"
+            [general]
+            rpc_proxy_req_every = 9
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_rpc_proxy_req_every_out_of_range_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("general.rpc_proxy_req_every must be 0 or within [10, 300]"));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn rpc_proxy_req_every_zero_and_valid_range_are_accepted() {
+        let toml_zero = r#"
+            [general]
+            rpc_proxy_req_every = 0
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path_zero = dir.join("telemt_rpc_proxy_req_every_zero_ok_test.toml");
+        std::fs::write(&path_zero, toml_zero).unwrap();
+        let cfg_zero = ProxyConfig::load(&path_zero).unwrap();
+        assert_eq!(cfg_zero.general.rpc_proxy_req_every, 0);
+        let _ = std::fs::remove_file(path_zero);
+
+        let toml_valid = r#"
+            [general]
+            rpc_proxy_req_every = 40
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let path_valid = dir.join("telemt_rpc_proxy_req_every_valid_ok_test.toml");
+        std::fs::write(&path_valid, toml_valid).unwrap();
+        let cfg_valid = ProxyConfig::load(&path_valid).unwrap();
+        assert_eq!(cfg_valid.general.rpc_proxy_req_every, 40);
+        let _ = std::fs::remove_file(path_valid);
+    }
+
+    #[test]
+    fn me_route_no_writer_wait_ms_out_of_range_is_rejected() {
+        let toml = r#"
+            [general]
+            me_route_no_writer_wait_ms = 5
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_me_route_no_writer_wait_ms_out_of_range_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("general.me_route_no_writer_wait_ms must be within [10, 5000]"));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn me_route_no_writer_mode_is_parsed() {
+        let toml = r#"
+            [general]
+            me_route_no_writer_mode = "inline_recovery_legacy"
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_me_route_no_writer_mode_parse_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let cfg = ProxyConfig::load(&path).unwrap();
+        assert_eq!(
+            cfg.general.me_route_no_writer_mode,
+            crate::config::MeRouteNoWriterMode::InlineRecoveryLegacy
+        );
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn proxy_config_cache_paths_empty_are_rejected() {
+        let toml = r#"
+            [general]
+            proxy_config_v4_cache_path = "   "
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_proxy_config_v4_cache_path_empty_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("general.proxy_config_v4_cache_path cannot be empty"));
+        let _ = std::fs::remove_file(path);
+
+        let toml_v6 = r#"
+            [general]
+            proxy_config_v6_cache_path = ""
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let path_v6 = dir.join("telemt_proxy_config_v6_cache_path_empty_test.toml");
+        std::fs::write(&path_v6, toml_v6).unwrap();
+        let err_v6 = ProxyConfig::load(&path_v6).unwrap_err().to_string();
+        assert!(err_v6.contains("general.proxy_config_v6_cache_path cannot be empty"));
+        let _ = std::fs::remove_file(path_v6);
+    }
+
     #[test]
     fn me_hardswap_warmup_defaults_are_set() {
         let toml = r#"
@@ -1166,6 +1845,94 @@ mod tests {
         let _ = std::fs::remove_file(path);
     }
 
+    #[test]
+    fn api_minimal_runtime_cache_ttl_out_of_range_is_rejected() {
+        let toml = r#"
+            [server.api]
+            enabled = true
+            listen = "127.0.0.1:9091"
+            minimal_runtime_cache_ttl_ms = 70000
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_api_minimal_runtime_cache_ttl_invalid_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("server.api.minimal_runtime_cache_ttl_ms must be within [0, 60000]"));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn api_runtime_edge_cache_ttl_out_of_range_is_rejected() {
+        let toml = r#"
+            [server.api]
+            enabled = true
+            listen = "127.0.0.1:9091"
+            runtime_edge_cache_ttl_ms = 70000
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_api_runtime_edge_cache_ttl_invalid_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("server.api.runtime_edge_cache_ttl_ms must be within [0, 60000]"));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn api_runtime_edge_top_n_out_of_range_is_rejected() {
+        let toml = r#"
+            [server.api]
+            enabled = true
+            listen = "127.0.0.1:9091"
+            runtime_edge_top_n = 0
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_api_runtime_edge_top_n_invalid_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("server.api.runtime_edge_top_n must be within [1, 1000]"));
+        let _ = std::fs::remove_file(path);
+    }
+
+    #[test]
+    fn api_runtime_edge_events_capacity_out_of_range_is_rejected() {
+        let toml = r#"
+            [server.api]
+            enabled = true
+            listen = "127.0.0.1:9091"
+            runtime_edge_events_capacity = 8
+
+            [censorship]
+            tls_domain = "example.com"
+
+            [access.users]
+            user = "00000000000000000000000000000000"
+        "#;
+        let dir = std::env::temp_dir();
+        let path = dir.join("telemt_api_runtime_edge_events_capacity_invalid_test.toml");
+        std::fs::write(&path, toml).unwrap();
+        let err = ProxyConfig::load(&path).unwrap_err().to_string();
+        assert!(err.contains("server.api.runtime_edge_events_capacity must be within [16, 4096]"));
+        let _ = std::fs::remove_file(path);
+    }
+
     #[test]
     fn force_close_bumped_when_below_drain_ttl() {
         let toml = r#"

src/config/types.rs

@@ -3,6 +3,7 @@ use ipnetwork::IpNetwork;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::net::IpAddr;
+use std::path::PathBuf;
 
 use super::defaults::*;
 
@@ -158,6 +159,99 @@ impl MeBindStaleMode {
     }
 }
 
+/// Middle-End writer floor policy mode.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum MeFloorMode {
+    Static,
+    #[default]
+    Adaptive,
+}
+
+impl MeFloorMode {
+    pub fn as_u8(self) -> u8 {
+        match self {
+            MeFloorMode::Static => 0,
+            MeFloorMode::Adaptive => 1,
+        }
+    }
+
+    pub fn from_u8(raw: u8) -> Self {
+        match raw {
+            1 => MeFloorMode::Adaptive,
+            _ => MeFloorMode::Static,
+        }
+    }
+}
+
+/// Middle-End route behavior when no writer is immediately available.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum MeRouteNoWriterMode {
+    AsyncRecoveryFailfast,
+    InlineRecoveryLegacy,
+    #[default]
+    HybridAsyncPersistent,
+}
+
+impl MeRouteNoWriterMode {
+    pub fn as_u8(self) -> u8 {
+        match self {
+            MeRouteNoWriterMode::AsyncRecoveryFailfast => 0,
+            MeRouteNoWriterMode::InlineRecoveryLegacy => 1,
+            MeRouteNoWriterMode::HybridAsyncPersistent => 2,
+        }
+    }
+
+    pub fn from_u8(raw: u8) -> Self {
+        match raw {
+            0 => MeRouteNoWriterMode::AsyncRecoveryFailfast,
+            1 => MeRouteNoWriterMode::InlineRecoveryLegacy,
+            2 => MeRouteNoWriterMode::HybridAsyncPersistent,
+            _ => MeRouteNoWriterMode::HybridAsyncPersistent,
+        }
+    }
+}
+
+/// Middle-End writer selection mode for new client bindings.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum MeWriterPickMode {
+    SortedRr,
+    #[default]
+    P2c,
+}
+
+impl MeWriterPickMode {
+    pub fn as_u8(self) -> u8 {
+        match self {
+            MeWriterPickMode::SortedRr => 0,
+            MeWriterPickMode::P2c => 1,
+        }
+    }
+
+    pub fn from_u8(raw: u8) -> Self {
+        match raw {
+            0 => MeWriterPickMode::SortedRr,
+            1 => MeWriterPickMode::P2c,
+            _ => MeWriterPickMode::P2c,
+        }
+    }
+}
+
+/// Per-user unique source IP limit mode.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum UserMaxUniqueIpsMode {
+    /// Count only currently active source IPs.
+    #[default]
+    ActiveWindow,
+    /// Count source IPs seen within the recent time window.
+    TimeWindow,
+    /// Enforce both active and recent-window limits at the same time.
+    Combined,
+}
+
 /// Telemetry controls for hot-path counters and ME diagnostics.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct TelemetryConfig {
@@ -263,6 +357,9 @@ impl Default for NetworkConfig {
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct GeneralConfig {
+    #[serde(default)]
+    pub data_path: Option<PathBuf>,
+
     #[serde(default)]
     pub modes: ProxyModes,
 
@@ -280,6 +377,14 @@ pub struct GeneralConfig {
     #[serde(default = "default_proxy_secret_path")]
     pub proxy_secret_path: 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 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>,
+
     /// 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>,
@@ -315,6 +420,15 @@ pub struct GeneralConfig {
     #[serde(default = "default_middle_proxy_warm_standby")]
     pub middle_proxy_warm_standby: usize,
 
+    /// Startup retries for Middle-End pool initialization before ME→Direct fallback.
+    /// 0 means unlimited retries.
+    #[serde(default = "default_me_init_retry_attempts")]
+    pub me_init_retry_attempts: u32,
+
+    /// Allow fallback from Middle-End mode to direct DC when ME startup cannot be initialized.
+    #[serde(default = "default_me2dc_fallback")]
+    pub me2dc_fallback: bool,
+
     /// Enable ME keepalive padding frames.
     #[serde(default = "default_true")]
     pub me_keepalive_enabled: bool,
@@ -331,6 +445,53 @@ pub struct GeneralConfig {
     #[serde(default = "default_true")]
     pub me_keepalive_payload_random: bool,
 
+    /// Interval in seconds for service RPC_PROXY_REQ activity signals to ME.
+    /// 0 disables service activity signals.
+    #[serde(default = "default_rpc_proxy_req_every")]
+    pub rpc_proxy_req_every: u64,
+
+    /// Capacity of per-ME writer command channel.
+    #[serde(default = "default_me_writer_cmd_channel_capacity")]
+    pub me_writer_cmd_channel_capacity: usize,
+
+    /// Capacity of per-connection ME response route channel.
+    #[serde(default = "default_me_route_channel_capacity")]
+    pub me_route_channel_capacity: usize,
+
+    /// Capacity of per-client command queue from client reader to ME sender task.
+    #[serde(default = "default_me_c2me_channel_capacity")]
+    pub me_c2me_channel_capacity: usize,
+
+    /// Bounded wait in milliseconds for routing ME DATA to per-connection queue.
+    /// `0` keeps legacy no-wait behavior.
+    #[serde(default = "default_me_reader_route_data_wait_ms")]
+    pub me_reader_route_data_wait_ms: u64,
+
+    /// Maximum number of ME->Client responses coalesced before flush.
+    #[serde(default = "default_me_d2c_flush_batch_max_frames")]
+    pub me_d2c_flush_batch_max_frames: usize,
+
+    /// Maximum total payload bytes coalesced before flush.
+    #[serde(default = "default_me_d2c_flush_batch_max_bytes")]
+    pub me_d2c_flush_batch_max_bytes: usize,
+
+    /// Maximum wait in microseconds to coalesce additional ME->Client responses.
+    /// `0` disables timed coalescing.
+    #[serde(default = "default_me_d2c_flush_batch_max_delay_us")]
+    pub me_d2c_flush_batch_max_delay_us: u64,
+
+    /// Flush client writer immediately after quick-ack write.
+    #[serde(default = "default_me_d2c_ack_flush_immediate")]
+    pub me_d2c_ack_flush_immediate: bool,
+
+    /// Copy buffer size for client->DC direction in direct relay.
+    #[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.
+    #[serde(default = "default_direct_relay_copy_buf_s2c_bytes")]
+    pub direct_relay_copy_buf_s2c_bytes: usize,
+
     /// Max pending ciphertext buffer per client writer (bytes).
     /// Controls FakeTLS backpressure vs throughput.
     #[serde(default = "default_crypto_pending_buffer")]
@@ -419,6 +580,59 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_single_endpoint_shadow_rotate_every_secs")]
     pub me_single_endpoint_shadow_rotate_every_secs: u64,
 
+    /// Floor policy mode for ME writer targets.
+    #[serde(default)]
+    pub me_floor_mode: MeFloorMode,
+
+    /// Idle time in seconds before adaptive floor can reduce single-endpoint writer target.
+    #[serde(default = "default_me_adaptive_floor_idle_secs")]
+    pub me_adaptive_floor_idle_secs: u64,
+
+    /// Minimum writer target for single-endpoint DC groups in adaptive floor mode.
+    #[serde(default = "default_me_adaptive_floor_min_writers_single_endpoint")]
+    pub me_adaptive_floor_min_writers_single_endpoint: u8,
+
+    /// Minimum writer target for multi-endpoint DC groups in adaptive floor mode.
+    #[serde(default = "default_me_adaptive_floor_min_writers_multi_endpoint")]
+    pub me_adaptive_floor_min_writers_multi_endpoint: u8,
+
+    /// Grace period in seconds to hold static floor after activity in adaptive mode.
+    #[serde(default = "default_me_adaptive_floor_recover_grace_secs")]
+    pub me_adaptive_floor_recover_grace_secs: u64,
+
+    /// Global ME writer budget per logical CPU core in adaptive mode.
+    #[serde(default = "default_me_adaptive_floor_writers_per_core_total")]
+    pub me_adaptive_floor_writers_per_core_total: u16,
+
+    /// Override logical CPU core count for adaptive floor calculations.
+    /// Set to 0 to use runtime auto-detection.
+    #[serde(default = "default_me_adaptive_floor_cpu_cores_override")]
+    pub me_adaptive_floor_cpu_cores_override: u16,
+
+    /// Per-core max extra writers above base required floor for single-endpoint DC groups.
+    #[serde(default = "default_me_adaptive_floor_max_extra_writers_single_per_core")]
+    pub me_adaptive_floor_max_extra_writers_single_per_core: u16,
+
+    /// Per-core max extra writers above base required floor for multi-endpoint DC groups.
+    #[serde(default = "default_me_adaptive_floor_max_extra_writers_multi_per_core")]
+    pub me_adaptive_floor_max_extra_writers_multi_per_core: u16,
+
+    /// Hard cap for active ME writers per logical CPU core.
+    #[serde(default = "default_me_adaptive_floor_max_active_writers_per_core")]
+    pub me_adaptive_floor_max_active_writers_per_core: u16,
+
+    /// Hard cap for warm ME writers per logical CPU core.
+    #[serde(default = "default_me_adaptive_floor_max_warm_writers_per_core")]
+    pub me_adaptive_floor_max_warm_writers_per_core: u16,
+
+    /// Hard global cap for active ME writers.
+    #[serde(default = "default_me_adaptive_floor_max_active_writers_global")]
+    pub me_adaptive_floor_max_active_writers_global: u32,
+
+    /// Hard global cap for warm ME writers.
+    #[serde(default = "default_me_adaptive_floor_max_warm_writers_global")]
+    pub me_adaptive_floor_max_warm_writers_global: u32,
+
     /// Connect attempts for the selected upstream before returning error/fallback.
     #[serde(default = "default_upstream_connect_retry_attempts")]
     pub upstream_connect_retry_attempts: u32,
@@ -427,10 +641,18 @@ pub struct GeneralConfig {
     #[serde(default = "default_upstream_connect_retry_backoff_ms")]
     pub upstream_connect_retry_backoff_ms: u64,
 
+    /// Total wall-clock budget in milliseconds for one upstream connect request across retries.
+    #[serde(default = "default_upstream_connect_budget_ms")]
+    pub upstream_connect_budget_ms: u64,
+
     /// Consecutive failed requests before upstream is marked unhealthy.
     #[serde(default = "default_upstream_unhealthy_fail_threshold")]
     pub upstream_unhealthy_fail_threshold: u32,
 
+    /// Skip additional retries for hard non-transient upstream connect errors.
+    #[serde(default = "default_upstream_connect_failfast_hard_errors")]
+    pub upstream_connect_failfast_hard_errors: bool,
+
     /// Ignore STUN/interface IP mismatch (keep using Middle Proxy even if NAT detected).
     #[serde(default)]
     pub stun_iface_mismatch_ignore: bool,
@@ -439,6 +661,10 @@ pub struct GeneralConfig {
     #[serde(default = "default_unknown_dc_log_path")]
     pub unknown_dc_log_path: Option<String>,
 
+    /// Enable unknown-DC file logging.
+    #[serde(default = "default_unknown_dc_file_log_enabled")]
+    pub unknown_dc_file_log_enabled: bool,
+
     #[serde(default)]
     pub log_level: LogLevel,
 
@@ -466,6 +692,38 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_route_backpressure_high_watermark_pct")]
     pub me_route_backpressure_high_watermark_pct: u8,
 
+    /// Health monitor interval in milliseconds while writer coverage is degraded.
+    #[serde(default = "default_me_health_interval_ms_unhealthy")]
+    pub me_health_interval_ms_unhealthy: u64,
+
+    /// Health monitor interval in milliseconds while writer coverage is stable.
+    #[serde(default = "default_me_health_interval_ms_healthy")]
+    pub me_health_interval_ms_healthy: u64,
+
+    /// Poll interval in milliseconds for conditional-admission state checks.
+    #[serde(default = "default_me_admission_poll_ms")]
+    pub me_admission_poll_ms: u64,
+
+    /// Cooldown for repetitive ME warning logs in milliseconds.
+    #[serde(default = "default_me_warn_rate_limit_ms")]
+    pub me_warn_rate_limit_ms: u64,
+
+    /// ME route behavior when no writer is immediately available.
+    #[serde(default)]
+    pub me_route_no_writer_mode: MeRouteNoWriterMode,
+
+    /// Maximum wait time in milliseconds for async-recovery failfast mode.
+    #[serde(default = "default_me_route_no_writer_wait_ms")]
+    pub me_route_no_writer_wait_ms: u64,
+
+    /// Number of inline recovery attempts in legacy mode.
+    #[serde(default = "default_me_route_inline_recovery_attempts")]
+    pub me_route_inline_recovery_attempts: u32,
+
+    /// Maximum wait time in milliseconds for inline recovery in legacy mode.
+    #[serde(default = "default_me_route_inline_recovery_wait_ms")]
+    pub me_route_inline_recovery_wait_ms: u64,
+
     /// [general.links] — proxy link generation overrides.
     #[serde(default)]
     pub links: LinksConfig,
@@ -540,6 +798,11 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_pool_drain_ttl_secs")]
     pub me_pool_drain_ttl_secs: u64,
 
+    /// Maximum allowed number of draining ME writers before oldest ones are force-closed in batches.
+    /// Set to 0 to disable threshold-based draining cleanup and keep timeout-only behavior.
+    #[serde(default = "default_me_pool_drain_threshold")]
+    pub me_pool_drain_threshold: u64,
+
     /// Policy for new binds on stale draining writers.
     #[serde(default)]
     pub me_bind_stale_mode: MeBindStaleMode,
@@ -584,6 +847,14 @@ pub struct GeneralConfig {
     #[serde(default = "default_me_deterministic_writer_sort")]
     pub me_deterministic_writer_sort: bool,
 
+    /// Writer selection mode for ME route bind path.
+    #[serde(default)]
+    pub me_writer_pick_mode: MeWriterPickMode,
+
+    /// Number of candidates sampled by writer picker in `p2c` mode.
+    #[serde(default = "default_me_writer_pick_sample_size")]
+    pub me_writer_pick_sample_size: u8,
+
     /// Enable NTP drift check at startup.
     #[serde(default = "default_ntp_check")]
     pub ntp_check: bool,
@@ -604,12 +875,15 @@ pub struct GeneralConfig {
 impl Default for GeneralConfig {
     fn default() -> Self {
         Self {
+            data_path: None,
             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_config_v4_cache_path: default_proxy_config_v4_cache_path(),
+            proxy_config_v6_cache_path: default_proxy_config_v6_cache_path(),
             middle_proxy_nat_ip: None,
             middle_proxy_nat_probe: default_true(),
             middle_proxy_nat_stun: default_middle_proxy_nat_stun(),
@@ -617,10 +891,23 @@ impl Default for GeneralConfig {
             stun_nat_probe_concurrency: default_stun_nat_probe_concurrency(),
             middle_proxy_pool_size: default_pool_size(),
             middle_proxy_warm_standby: default_middle_proxy_warm_standby(),
+            me_init_retry_attempts: default_me_init_retry_attempts(),
+            me2dc_fallback: default_me2dc_fallback(),
             me_keepalive_enabled: default_true(),
             me_keepalive_interval_secs: default_keepalive_interval(),
             me_keepalive_jitter_secs: default_keepalive_jitter(),
             me_keepalive_payload_random: default_true(),
+            rpc_proxy_req_every: default_rpc_proxy_req_every(),
+            me_writer_cmd_channel_capacity: default_me_writer_cmd_channel_capacity(),
+            me_route_channel_capacity: default_me_route_channel_capacity(),
+            me_c2me_channel_capacity: default_me_c2me_channel_capacity(),
+            me_reader_route_data_wait_ms: default_me_reader_route_data_wait_ms(),
+            me_d2c_flush_batch_max_frames: default_me_d2c_flush_batch_max_frames(),
+            me_d2c_flush_batch_max_bytes: default_me_d2c_flush_batch_max_bytes(),
+            me_d2c_flush_batch_max_delay_us: default_me_d2c_flush_batch_max_delay_us(),
+            me_d2c_ack_flush_immediate: default_me_d2c_ack_flush_immediate(),
+            direct_relay_copy_buf_c2s_bytes: default_direct_relay_copy_buf_c2s_bytes(),
+            direct_relay_copy_buf_s2c_bytes: default_direct_relay_copy_buf_s2c_bytes(),
             me_warmup_stagger_enabled: default_true(),
             me_warmup_step_delay_ms: default_warmup_step_delay_ms(),
             me_warmup_step_jitter_ms: default_warmup_step_jitter_ms(),
@@ -634,11 +921,27 @@ impl Default for GeneralConfig {
             me_single_endpoint_outage_backoff_min_ms: default_me_single_endpoint_outage_backoff_min_ms(),
             me_single_endpoint_outage_backoff_max_ms: default_me_single_endpoint_outage_backoff_max_ms(),
             me_single_endpoint_shadow_rotate_every_secs: default_me_single_endpoint_shadow_rotate_every_secs(),
+            me_floor_mode: MeFloorMode::default(),
+            me_adaptive_floor_idle_secs: default_me_adaptive_floor_idle_secs(),
+            me_adaptive_floor_min_writers_single_endpoint: default_me_adaptive_floor_min_writers_single_endpoint(),
+            me_adaptive_floor_min_writers_multi_endpoint: default_me_adaptive_floor_min_writers_multi_endpoint(),
+            me_adaptive_floor_recover_grace_secs: default_me_adaptive_floor_recover_grace_secs(),
+            me_adaptive_floor_writers_per_core_total: default_me_adaptive_floor_writers_per_core_total(),
+            me_adaptive_floor_cpu_cores_override: default_me_adaptive_floor_cpu_cores_override(),
+            me_adaptive_floor_max_extra_writers_single_per_core: default_me_adaptive_floor_max_extra_writers_single_per_core(),
+            me_adaptive_floor_max_extra_writers_multi_per_core: default_me_adaptive_floor_max_extra_writers_multi_per_core(),
+            me_adaptive_floor_max_active_writers_per_core: default_me_adaptive_floor_max_active_writers_per_core(),
+            me_adaptive_floor_max_warm_writers_per_core: default_me_adaptive_floor_max_warm_writers_per_core(),
+            me_adaptive_floor_max_active_writers_global: default_me_adaptive_floor_max_active_writers_global(),
+            me_adaptive_floor_max_warm_writers_global: default_me_adaptive_floor_max_warm_writers_global(),
             upstream_connect_retry_attempts: default_upstream_connect_retry_attempts(),
             upstream_connect_retry_backoff_ms: default_upstream_connect_retry_backoff_ms(),
+            upstream_connect_budget_ms: default_upstream_connect_budget_ms(),
             upstream_unhealthy_fail_threshold: default_upstream_unhealthy_fail_threshold(),
+            upstream_connect_failfast_hard_errors: default_upstream_connect_failfast_hard_errors(),
             stun_iface_mismatch_ignore: false,
             unknown_dc_log_path: default_unknown_dc_log_path(),
+            unknown_dc_file_log_enabled: default_unknown_dc_file_log_enabled(),
             log_level: LogLevel::Normal,
             disable_colors: false,
             telemetry: TelemetryConfig::default(),
@@ -646,6 +949,14 @@ impl Default for GeneralConfig {
             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: default_me_route_backpressure_high_watermark_pct(),
+            me_health_interval_ms_unhealthy: default_me_health_interval_ms_unhealthy(),
+            me_health_interval_ms_healthy: default_me_health_interval_ms_healthy(),
+            me_admission_poll_ms: default_me_admission_poll_ms(),
+            me_warn_rate_limit_ms: default_me_warn_rate_limit_ms(),
+            me_route_no_writer_mode: MeRouteNoWriterMode::default(),
+            me_route_no_writer_wait_ms: default_me_route_no_writer_wait_ms(),
+            me_route_inline_recovery_attempts: default_me_route_inline_recovery_attempts(),
+            me_route_inline_recovery_wait_ms: default_me_route_inline_recovery_wait_ms(),
             links: LinksConfig::default(),
             crypto_pending_buffer: default_crypto_pending_buffer(),
             max_client_frame: default_max_client_frame(),
@@ -672,6 +983,7 @@ impl Default for GeneralConfig {
             me_secret_atomic_snapshot: default_me_secret_atomic_snapshot(),
             proxy_secret_len_max: default_proxy_secret_len_max(),
             me_pool_drain_ttl_secs: default_me_pool_drain_ttl_secs(),
+            me_pool_drain_threshold: default_me_pool_drain_threshold(),
             me_bind_stale_mode: MeBindStaleMode::default(),
             me_bind_stale_ttl_secs: default_me_bind_stale_ttl_secs(),
             me_pool_min_fresh_ratio: default_me_pool_min_fresh_ratio(),
@@ -682,6 +994,8 @@ impl Default for GeneralConfig {
             me_reinit_trigger_channel: default_me_reinit_trigger_channel(),
             me_reinit_coalesce_window_ms: default_me_reinit_coalesce_window_ms(),
             me_deterministic_writer_sort: default_me_deterministic_writer_sort(),
+            me_writer_pick_mode: MeWriterPickMode::default(),
+            me_writer_pick_sample_size: default_me_writer_pick_sample_size(),
             ntp_check: default_ntp_check(),
             ntp_servers: default_ntp_servers(),
             auto_degradation_enabled: default_true(),
@@ -737,6 +1051,78 @@ impl Default for LinksConfig {
     }
 }
 
+/// API settings for control-plane endpoints.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct ApiConfig {
+    /// Enable or disable REST API.
+    #[serde(default = "default_true")]
+    pub enabled: bool,
+
+    /// Listen address for API in `IP:PORT` format.
+    #[serde(default = "default_api_listen")]
+    pub listen: String,
+
+    /// CIDR whitelist allowed to access API.
+    #[serde(default = "default_api_whitelist")]
+    pub whitelist: Vec<IpNetwork>,
+
+    /// Optional static value for `Authorization` header validation.
+    /// Empty string disables header auth.
+    #[serde(default)]
+    pub auth_header: String,
+
+    /// Maximum accepted HTTP request body size in bytes.
+    #[serde(default = "default_api_request_body_limit_bytes")]
+    pub request_body_limit_bytes: usize,
+
+    /// Enable runtime snapshots that require read-lock aggregation on API request path.
+    #[serde(default = "default_api_minimal_runtime_enabled")]
+    pub minimal_runtime_enabled: bool,
+
+    /// Cache TTL for minimal runtime snapshots in milliseconds (0 disables caching).
+    #[serde(default = "default_api_minimal_runtime_cache_ttl_ms")]
+    pub minimal_runtime_cache_ttl_ms: u64,
+
+    /// Enables runtime edge endpoints with optional cached aggregation.
+    #[serde(default = "default_api_runtime_edge_enabled")]
+    pub runtime_edge_enabled: bool,
+
+    /// Cache TTL for runtime edge aggregation payloads in milliseconds.
+    #[serde(default = "default_api_runtime_edge_cache_ttl_ms")]
+    pub runtime_edge_cache_ttl_ms: u64,
+
+    /// Top-N limit for edge connection leaderboard payloads.
+    #[serde(default = "default_api_runtime_edge_top_n")]
+    pub runtime_edge_top_n: usize,
+
+    /// Ring-buffer capacity for runtime edge control-plane events.
+    #[serde(default = "default_api_runtime_edge_events_capacity")]
+    pub runtime_edge_events_capacity: usize,
+
+    /// Read-only mode: mutating endpoints are rejected.
+    #[serde(default)]
+    pub read_only: bool,
+}
+
+impl Default for ApiConfig {
+    fn default() -> Self {
+        Self {
+            enabled: default_true(),
+            listen: default_api_listen(),
+            whitelist: default_api_whitelist(),
+            auth_header: String::new(),
+            request_body_limit_bytes: default_api_request_body_limit_bytes(),
+            minimal_runtime_enabled: default_api_minimal_runtime_enabled(),
+            minimal_runtime_cache_ttl_ms: default_api_minimal_runtime_cache_ttl_ms(),
+            runtime_edge_enabled: default_api_runtime_edge_enabled(),
+            runtime_edge_cache_ttl_ms: default_api_runtime_edge_cache_ttl_ms(),
+            runtime_edge_top_n: default_api_runtime_edge_top_n(),
+            runtime_edge_events_capacity: default_api_runtime_edge_events_capacity(),
+            read_only: false,
+        }
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ServerConfig {
     #[serde(default = "default_port")]
@@ -766,14 +1152,33 @@ pub struct ServerConfig {
     #[serde(default)]
     pub proxy_protocol: bool,
 
+    /// Timeout in milliseconds for reading and parsing PROXY protocol headers.
+    #[serde(default = "default_proxy_protocol_header_timeout_ms")]
+    pub proxy_protocol_header_timeout_ms: u64,
+
+    /// Trusted source CIDRs allowed to send incoming PROXY protocol headers.
+    ///
+    /// When non-empty, connections from addresses outside this allowlist are
+    /// rejected before `src_addr` is applied.
+    #[serde(default)]
+    pub proxy_protocol_trusted_cidrs: Vec<IpNetwork>,
+
     #[serde(default)]
     pub metrics_port: Option<u16>,
 
     #[serde(default = "default_metrics_whitelist")]
     pub metrics_whitelist: Vec<IpNetwork>,
 
+    #[serde(default, alias = "admin_api")]
+    pub api: ApiConfig,
+
     #[serde(default)]
     pub listeners: Vec<ListenerConfig>,
+
+    /// Maximum number of concurrent client connections.
+    /// 0 means unlimited.
+    #[serde(default = "default_server_max_connections")]
+    pub max_connections: u32,
 }
 
 impl Default for ServerConfig {
@@ -786,9 +1191,13 @@ impl Default for ServerConfig {
             listen_unix_sock_perm: None,
             listen_tcp: None,
             proxy_protocol: false,
+            proxy_protocol_header_timeout_ms: default_proxy_protocol_header_timeout_ms(),
+            proxy_protocol_trusted_cidrs: Vec::new(),
             metrics_port: None,
             metrics_whitelist: default_metrics_whitelist(),
+            api: ApiConfig::default(),
             listeners: Vec::new(),
+            max_connections: default_server_max_connections(),
         }
     }
 }
@@ -933,6 +1342,17 @@ pub struct AccessConfig {
     #[serde(default)]
     pub user_max_unique_ips: HashMap<String, usize>,
 
+    /// Global per-user unique IP limit applied when a user has no individual override.
+    /// `0` disables the inherited limit.
+    #[serde(default = "default_user_max_unique_ips_global_each")]
+    pub user_max_unique_ips_global_each: usize,
+
+    #[serde(default)]
+    pub user_max_unique_ips_mode: UserMaxUniqueIpsMode,
+
+    #[serde(default = "default_user_max_unique_ips_window_secs")]
+    pub user_max_unique_ips_window_secs: u64,
+
     #[serde(default = "default_replay_check_len")]
     pub replay_check_len: usize,
 
@@ -952,6 +1372,9 @@ impl Default for AccessConfig {
             user_expirations: HashMap::new(),
             user_data_quota: 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(),
+            user_max_unique_ips_window_secs: default_user_max_unique_ips_window_secs(),
             replay_check_len: default_replay_check_len(),
             replay_window_secs: default_replay_window_secs(),
             ignore_time_skew: false,

src/crypto/random.rs

@@ -21,6 +21,7 @@ struct SecureRandomInner {
     rng: StdRng,
     cipher: AesCtr,
     buffer: Vec<u8>,
+    buffer_start: usize,
 }
 
 impl Drop for SecureRandomInner {
@@ -48,6 +49,7 @@ impl SecureRandom {
                 rng,
                 cipher,
                 buffer: Vec::with_capacity(1024),
+                buffer_start: 0,
             }),
         }
     }
@@ -59,16 +61,29 @@ impl SecureRandom {
 
         let mut written = 0usize;
         while written < out.len() {
+            if inner.buffer_start >= inner.buffer.len() {
+                inner.buffer.clear();
+                inner.buffer_start = 0;
+            }
+
             if inner.buffer.is_empty() {
                 let mut chunk = vec![0u8; CHUNK_SIZE];
                 inner.rng.fill_bytes(&mut chunk);
                 inner.cipher.apply(&mut chunk);
                 inner.buffer.extend_from_slice(&chunk);
+                inner.buffer_start = 0;
             }
 
-            let take = (out.len() - written).min(inner.buffer.len());
-            out[written..written + take].copy_from_slice(&inner.buffer[..take]);
-            inner.buffer.drain(..take);
+            let available = inner.buffer.len().saturating_sub(inner.buffer_start);
+            let take = (out.len() - written).min(available);
+            let start = inner.buffer_start;
+            let end = start + take;
+            out[written..written + take].copy_from_slice(&inner.buffer[start..end]);
+            inner.buffer_start = end;
+            if inner.buffer_start >= inner.buffer.len() {
+                inner.buffer.clear();
+                inner.buffer_start = 0;
+            }
             written += take;
         }
     }

src/ip_tracker.rs

@@ -1,252 +1,351 @@
-// src/ip_tracker.rs
-// IP address tracking and limiting for users
+// IP address tracking and per-user unique IP limiting.
 
 #![allow(dead_code)]
 
-use std::collections::{HashMap, HashSet};
+use std::collections::HashMap;
 use std::net::IpAddr;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
 use tokio::sync::RwLock;
 
-/// Трекер уникальных IP-адресов для каждого пользователя MTProxy
-/// 
-/// Предоставляет thread-safe механизм для:
-/// - Отслеживания активных IP-адресов каждого пользователя
-/// - Ограничения количества уникальных IP на пользователя
-/// - Автоматической очистки при отключении клиентов
+use crate::config::UserMaxUniqueIpsMode;
+
 #[derive(Debug, Clone)]
 pub struct UserIpTracker {
-    /// Маппинг: Имя пользователя -> Множество активных IP-адресов
-    active_ips: Arc<RwLock<HashMap<String, HashSet<IpAddr>>>>,
-    
-    /// Маппинг: Имя пользователя -> Максимально разрешенное количество уникальных IP
+    active_ips: Arc<RwLock<HashMap<String, HashMap<IpAddr, usize>>>>,
+    recent_ips: Arc<RwLock<HashMap<String, HashMap<IpAddr, Instant>>>>,
     max_ips: Arc<RwLock<HashMap<String, usize>>>,
+    default_max_ips: Arc<RwLock<usize>>,
+    limit_mode: Arc<RwLock<UserMaxUniqueIpsMode>>,
+    limit_window: Arc<RwLock<Duration>>,
+    last_compact_epoch_secs: Arc<AtomicU64>,
 }
 
 impl UserIpTracker {
-    /// Создать новый пустой трекер
     pub fn new() -> Self {
         Self {
             active_ips: Arc::new(RwLock::new(HashMap::new())),
+            recent_ips: Arc::new(RwLock::new(HashMap::new())),
             max_ips: Arc::new(RwLock::new(HashMap::new())),
+            default_max_ips: Arc::new(RwLock::new(0)),
+            limit_mode: Arc::new(RwLock::new(UserMaxUniqueIpsMode::ActiveWindow)),
+            limit_window: Arc::new(RwLock::new(Duration::from_secs(30))),
+            last_compact_epoch_secs: Arc::new(AtomicU64::new(0)),
         }
     }
 
-    /// Установить лимит уникальных IP для конкретного пользователя
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
-    /// * `max_ips` - Максимальное количество одновременно активных IP-адресов
+    fn now_epoch_secs() -> u64 {
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs()
+    }
+
+    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 mut active_ips = self.active_ips.write().await;
+        let mut recent_ips = self.recent_ips.write().await;
+        let mut users = Vec::<String>::with_capacity(active_ips.len().saturating_add(recent_ips.len()));
+        users.extend(active_ips.keys().cloned());
+        for user in recent_ips.keys() {
+            if !active_ips.contains_key(user) {
+                users.push(user.clone());
+            }
+        }
+
+        for user in users {
+            let active_empty = active_ips.get(&user).map(|ips| ips.is_empty()).unwrap_or(true);
+            let recent_empty = recent_ips.get(&user).map(|ips| ips.is_empty()).unwrap_or(true);
+            if active_empty && recent_empty {
+                active_ips.remove(&user);
+                recent_ips.remove(&user);
+            }
+        }
+    }
+
+    pub async fn set_limit_policy(&self, mode: UserMaxUniqueIpsMode, window_secs: u64) {
+        {
+            let mut current_mode = self.limit_mode.write().await;
+            *current_mode = mode;
+        }
+        let mut current_window = self.limit_window.write().await;
+        *current_window = Duration::from_secs(window_secs.max(1));
+    }
+
     pub async fn set_user_limit(&self, username: &str, max_ips: usize) {
         let mut limits = self.max_ips.write().await;
         limits.insert(username.to_string(), max_ips);
     }
 
-    /// Загрузить лимиты из конфигурации
-    /// 
-    /// # Arguments
-    /// * `limits` - HashMap с лимитами из config.toml
-    pub async fn load_limits(&self, limits: &HashMap<String, usize>) {
-        let mut max_ips = self.max_ips.write().await;
-        for (user, limit) in limits {
-            max_ips.insert(user.clone(), *limit);
-        }
+    pub async fn remove_user_limit(&self, username: &str) {
+        let mut limits = self.max_ips.write().await;
+        limits.remove(username);
+    }
+
+    pub async fn load_limits(&self, default_limit: usize, limits: &HashMap<String, usize>) {
+        let mut default_max_ips = self.default_max_ips.write().await;
+        *default_max_ips = default_limit;
+        drop(default_max_ips);
+        let mut max_ips = self.max_ips.write().await;
+        max_ips.clone_from(limits);
+    }
+
+    fn prune_recent(user_recent: &mut HashMap<IpAddr, Instant>, now: Instant, window: Duration) {
+        if user_recent.is_empty() {
+            return;
+        }
+        user_recent.retain(|_, seen_at| now.duration_since(*seen_at) <= window);
     }
 
-    /// Проверить, может ли пользователь подключиться с данного IP-адреса
-    /// и добавить IP в список активных, если проверка успешна
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
-    /// * `ip` - IP-адрес клиента
-    /// 
-    /// # Returns
-    /// * `Ok(())` - Подключение разрешено, IP добавлен в активные
-    /// * `Err(String)` - Подключение отклонено с описанием причины
     pub async fn check_and_add(&self, username: &str, ip: IpAddr) -> Result<(), String> {
-        // Получаем лимит для пользователя
-        let max_ips = self.max_ips.read().await;
-        let limit = match max_ips.get(username) {
-            Some(limit) => *limit,
-            None => {
-                // Если лимит не задан - разрешаем безлимитный доступ
-                drop(max_ips);
-                let mut active_ips = self.active_ips.write().await;
-                let user_ips = active_ips
-                    .entry(username.to_string())
-                    .or_insert_with(HashSet::new);
-                user_ips.insert(ip);
-                return Ok(());
-            }
+        self.maybe_compact_empty_users().await;
+        let default_max_ips = *self.default_max_ips.read().await;
+        let limit = {
+            let max_ips = self.max_ips.read().await;
+            max_ips
+                .get(username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or((default_max_ips > 0).then_some(default_max_ips))
         };
-        drop(max_ips);
+        let mode = *self.limit_mode.read().await;
+        let window = *self.limit_window.read().await;
+        let now = Instant::now();
 
-        // Проверяем и обновляем активные IP
         let mut active_ips = self.active_ips.write().await;
-        let user_ips = active_ips
+        let user_active = active_ips
             .entry(username.to_string())
-            .or_insert_with(HashSet::new);
+            .or_insert_with(HashMap::new);
 
-        // Если IP уже есть в списке - это повторное подключение, разрешаем
-        if user_ips.contains(&ip) {
+        let mut recent_ips = self.recent_ips.write().await;
+        let user_recent = recent_ips
+            .entry(username.to_string())
+            .or_insert_with(HashMap::new);
+        Self::prune_recent(user_recent, now, window);
+
+        if let Some(count) = user_active.get_mut(&ip) {
+            *count = count.saturating_add(1);
+            user_recent.insert(ip, now);
             return Ok(());
         }
 
-        // Проверяем, не превышен ли лимит
-        if user_ips.len() >= limit {
-            return Err(format!(
-                "IP limit reached for user '{}': {}/{} unique IPs already connected",
-                username,
-                user_ips.len(),
-                limit
-            ));
+        if let Some(limit) = limit {
+            let active_limit_reached = user_active.len() >= limit;
+            let recent_limit_reached = user_recent.len() >= limit;
+            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,
+                    user_active.len(),
+                    limit,
+                    user_recent.len(),
+                    limit,
+                    mode
+                ));
+            }
         }
 
-        // Лимит не превышен - добавляем новый IP
-        user_ips.insert(ip);
+        user_active.insert(ip, 1);
+        user_recent.insert(ip, now);
         Ok(())
     }
 
-    /// Удалить IP-адрес из списка активных при отключении клиента
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
-    /// * `ip` - IP-адрес отключившегося клиента
     pub async fn remove_ip(&self, username: &str, ip: IpAddr) {
+        self.maybe_compact_empty_users().await;
         let mut active_ips = self.active_ips.write().await;
-        
         if let Some(user_ips) = active_ips.get_mut(username) {
-            user_ips.remove(&ip);
-            
-            // Если у пользователя не осталось активных IP - удаляем запись
-            // для экономии памяти
+            if let Some(count) = user_ips.get_mut(&ip) {
+                if *count > 1 {
+                    *count -= 1;
+                } else {
+                    user_ips.remove(&ip);
+                }
+            }
             if user_ips.is_empty() {
                 active_ips.remove(username);
             }
         }
     }
 
-    /// Получить текущее количество активных IP-адресов для пользователя
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
-    /// 
-    /// # Returns
-    /// Количество уникальных активных IP-адресов
-    pub async fn get_active_ip_count(&self, username: &str) -> usize {
-        let active_ips = self.active_ips.read().await;
-        active_ips
-            .get(username)
-            .map(|ips| ips.len())
-            .unwrap_or(0)
+    pub async fn get_recent_counts_for_users(&self, users: &[String]) -> HashMap<String, usize> {
+        let window = *self.limit_window.read().await;
+        let now = Instant::now();
+        let recent_ips = self.recent_ips.read().await;
+
+        let mut counts = HashMap::with_capacity(users.len());
+        for user in users {
+            let count = if let Some(user_recent) = 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>> {
+        let active_ips = self.active_ips.read().await;
+        let mut out = HashMap::with_capacity(users.len());
+        for user in users {
+            let mut ips = 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>> {
+        let window = *self.limit_window.read().await;
+        let now = Instant::now();
+        let recent_ips = self.recent_ips.read().await;
+
+        let mut out = HashMap::with_capacity(users.len());
+        for user in users {
+            let mut ips = if let Some(user_recent) = 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 {
+        let active_ips = self.active_ips.read().await;
+        active_ips.get(username).map(|ips| ips.len()).unwrap_or(0)
     }
 
-    /// Получить список всех активных IP-адресов для пользователя
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
-    /// 
-    /// # Returns
-    /// Вектор с активными IP-адресами
     pub async fn get_active_ips(&self, username: &str) -> Vec<IpAddr> {
         let active_ips = self.active_ips.read().await;
         active_ips
             .get(username)
-            .map(|ips| ips.iter().copied().collect())
+            .map(|ips| ips.keys().copied().collect())
             .unwrap_or_else(Vec::new)
     }
 
-    /// Получить статистику по всем пользователям
-    /// 
-    /// # Returns
-    /// Вектор кортежей: (имя_пользователя, количество_активных_IP, лимит)
     pub async fn get_stats(&self) -> Vec<(String, usize, usize)> {
         let active_ips = self.active_ips.read().await;
         let max_ips = self.max_ips.read().await;
+        let default_max_ips = *self.default_max_ips.read().await;
 
         let mut stats = Vec::new();
-        
-        // Собираем статистику по пользователям с активными подключениями
         for (username, user_ips) in active_ips.iter() {
-            let limit = max_ips.get(username).copied().unwrap_or(0);
+            let limit = max_ips
+                .get(username)
+                .copied()
+                .filter(|limit| *limit > 0)
+                .or((default_max_ips > 0).then_some(default_max_ips))
+                .unwrap_or(0);
             stats.push((username.clone(), user_ips.len(), limit));
         }
-        
-        stats.sort_by(|a, b| a.0.cmp(&b.0)); // Сортируем по имени пользователя
+
+        stats.sort_by(|a, b| a.0.cmp(&b.0));
         stats
     }
 
-    /// Очистить все активные IP для пользователя (при необходимости)
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
     pub async fn clear_user_ips(&self, username: &str) {
         let mut active_ips = self.active_ips.write().await;
         active_ips.remove(username);
+        drop(active_ips);
+
+        let mut recent_ips = self.recent_ips.write().await;
+        recent_ips.remove(username);
     }
 
-    /// Очистить всю статистику (использовать с осторожностью!)
     pub async fn clear_all(&self) {
         let mut active_ips = self.active_ips.write().await;
         active_ips.clear();
+        drop(active_ips);
+
+        let mut recent_ips = self.recent_ips.write().await;
+        recent_ips.clear();
     }
 
-    /// Проверить, подключен ли пользователь с данного IP
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
-    /// * `ip` - IP-адрес для проверки
-    /// 
-    /// # Returns
-    /// `true` если IP активен, `false` если нет
     pub async fn is_ip_active(&self, username: &str, ip: IpAddr) -> bool {
         let active_ips = self.active_ips.read().await;
         active_ips
             .get(username)
-            .map(|ips| ips.contains(&ip))
+            .map(|ips| ips.contains_key(&ip))
             .unwrap_or(false)
     }
 
-    /// Получить лимит для пользователя
-    /// 
-    /// # Arguments
-    /// * `username` - Имя пользователя
-    /// 
-    /// # Returns
-    /// Лимит IP-адресов или None, если лимит не установлен
     pub async fn get_user_limit(&self, username: &str) -> Option<usize> {
+        let default_max_ips = *self.default_max_ips.read().await;
         let max_ips = self.max_ips.read().await;
-        max_ips.get(username).copied()
+        max_ips
+            .get(username)
+            .copied()
+            .filter(|limit| *limit > 0)
+            .or((default_max_ips > 0).then_some(default_max_ips))
     }
 
-    /// Форматировать статистику в читаемый текст
-    /// 
-    /// # Returns
-    /// Строка со статистикой для логов или мониторинга
     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() }
+                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.push_str(&format!("  - {}\n", ip));
             }
         }
-        
+
         output
     }
 }
@@ -257,10 +356,6 @@ impl Default for UserIpTracker {
     }
 }
 
-// ============================================================================
-// ТЕСТЫ
-// ============================================================================
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -283,17 +378,33 @@ mod tests {
         let ip2 = test_ipv4(192, 168, 1, 2);
         let ip3 = test_ipv4(192, 168, 1, 3);
 
-        // Первые два IP должны быть приняты
         assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
         assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
-
-        // Третий IP должен быть отклонен
         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();
@@ -301,16 +412,29 @@ mod tests {
 
         let ip1 = test_ipv4(192, 168, 1, 1);
 
-        // Первое подключение
         assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
-        
-        // Повторное подключение с того же IP должно пройти
         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();
@@ -320,36 +444,28 @@ mod tests {
         let ip2 = test_ipv4(192, 168, 1, 2);
         let ip3 = test_ipv4(192, 168, 1, 3);
 
-        // Добавляем два IP
         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());
 
-        // Удаляем первый IP
         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();
-        // Не устанавливаем лимит для test_user
 
         let ip1 = test_ipv4(192, 168, 1, 1);
         let ip2 = test_ipv4(192, 168, 1, 2);
         let ip3 = test_ipv4(192, 168, 1, 3);
 
-        // Без лимита все IP должны проходить
         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);
     }
 
@@ -362,11 +478,9 @@ mod tests {
         let ip1 = test_ipv4(192, 168, 1, 1);
         let ip2 = test_ipv4(192, 168, 1, 2);
 
-        // user1 может использовать 2 IP
         assert!(tracker.check_and_add("user1", ip1).await.is_ok());
         assert!(tracker.check_and_add("user1", ip2).await.is_ok());
 
-        // user2 может использовать только 1 IP
         assert!(tracker.check_and_add("user2", ip1).await.is_ok());
         assert!(tracker.check_and_add("user2", ip2).await.is_err());
     }
@@ -379,10 +493,9 @@ mod tests {
         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);
     }
 
@@ -417,8 +530,7 @@ mod tests {
 
         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"));
     }
@@ -427,10 +539,10 @@ mod tests {
     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);
     }
@@ -440,9 +552,9 @@ mod tests {
         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);
     }
@@ -450,15 +562,115 @@ mod tests {
     #[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(&config_limits).await;
-        
+
+        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());
+    }
 }

src/maestro/admission.rs

@@ -0,0 +1,130 @@
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::sync::watch;
+use tracing::{info, warn};
+
+use crate::config::ProxyConfig;
+use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
+use crate::transport::middle_proxy::MePool;
+
+const STARTUP_FALLBACK_AFTER: Duration = Duration::from_secs(80);
+const RUNTIME_FALLBACK_AFTER: Duration = Duration::from_secs(6);
+
+pub(crate) async fn configure_admission_gate(
+    config: &Arc<ProxyConfig>,
+    me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    admission_tx: &watch::Sender<bool>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+) {
+    if config.general.use_middle_proxy {
+        if let Some(pool) = me_pool.as_ref() {
+            let initial_ready = pool.admission_ready_conditional_cast().await;
+            admission_tx.send_replace(initial_ready);
+            let _ = route_runtime.set_mode(RelayRouteMode::Middle);
+            if initial_ready {
+                info!("Conditional-admission gate: open / ME pool READY");
+            } else {
+                warn!("Conditional-admission gate: closed / ME pool is NOT ready)");
+            }
+
+            let pool_for_gate = pool.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 admission_poll_ms = config.general.me_admission_poll_ms.max(1);
+            let mut fallback_enabled = config.general.me2dc_fallback;
+            tokio::spawn(async move {
+                let mut gate_open = initial_ready;
+                let mut route_mode = RelayRouteMode::Middle;
+                let mut ready_observed = initial_ready;
+                let mut not_ready_since = if initial_ready {
+                    None
+                } else {
+                    Some(Instant::now())
+                };
+                loop {
+                    tokio::select! {
+                        changed = config_rx_gate.changed() => {
+                            if changed.is_err() {
+                                break;
+                            }
+                            let cfg = config_rx_gate.borrow_and_update().clone();
+                            admission_poll_ms = cfg.general.me_admission_poll_ms.max(1);
+                            fallback_enabled = cfg.general.me2dc_fallback;
+                            continue;
+                        }
+                        _ = tokio::time::sleep(Duration::from_millis(admission_poll_ms)) => {}
+                    }
+                    let ready = pool_for_gate.admission_ready_conditional_cast().await;
+                    let now = Instant::now();
+                    let (next_gate_open, next_route_mode, next_fallback_active) = if ready {
+                        ready_observed = true;
+                        not_ready_since = None;
+                        (true, RelayRouteMode::Middle, false)
+                    } else {
+                        let not_ready_started_at = *not_ready_since.get_or_insert(now);
+                        let not_ready_for = now.saturating_duration_since(not_ready_started_at);
+                        let fallback_after = if ready_observed {
+                            RUNTIME_FALLBACK_AFTER
+                        } else {
+                            STARTUP_FALLBACK_AFTER
+                        };
+                        if fallback_enabled && not_ready_for > fallback_after {
+                            (true, RelayRouteMode::Direct, true)
+                        } else {
+                            (false, RelayRouteMode::Middle, false)
+                        }
+                    };
+
+                    if next_route_mode != route_mode {
+                        route_mode = next_route_mode;
+                        if let Some(snapshot) = route_runtime_gate.set_mode(route_mode) {
+                            if matches!(route_mode, RelayRouteMode::Middle) {
+                                info!(
+                                    target_mode = route_mode.as_str(),
+                                    cutover_generation = snapshot.generation,
+                                    "Middle-End routing restored for new sessions"
+                                );
+                            } else {
+                                let fallback_after = if ready_observed {
+                                    RUNTIME_FALLBACK_AFTER
+                                } else {
+                                    STARTUP_FALLBACK_AFTER
+                                };
+                                warn!(
+                                    target_mode = route_mode.as_str(),
+                                    cutover_generation = snapshot.generation,
+                                    grace_secs = fallback_after.as_secs(),
+                                    "ME pool stayed not-ready beyond grace; routing new sessions via Direct-DC"
+                                );
+                            }
+                        }
+                    }
+
+                    if next_gate_open != gate_open {
+                        gate_open = next_gate_open;
+                        admission_tx_gate.send_replace(gate_open);
+                        if gate_open {
+                            if next_fallback_active {
+                                warn!("Conditional-admission gate opened in ME fallback mode");
+                            } else {
+                                info!("Conditional-admission gate opened / ME pool READY");
+                            }
+                        } else {
+                            warn!("Conditional-admission gate closed / ME pool is NOT ready");
+                        }
+                    }
+                }
+            });
+        } else {
+            admission_tx.send_replace(false);
+            let _ = route_runtime.set_mode(RelayRouteMode::Direct);
+            warn!("Conditional-admission gate: closed / ME pool is UNAVAILABLE");
+        }
+    } else {
+        admission_tx.send_replace(true);
+        let _ = route_runtime.set_mode(RelayRouteMode::Direct);
+    }
+}

src/maestro/connectivity.rs

@@ -0,0 +1,220 @@
+use std::sync::Arc;
+use std::time::Instant;
+
+use tokio::sync::RwLock;
+use tracing::info;
+
+use crate::config::ProxyConfig;
+use crate::crypto::SecureRandom;
+use crate::network::probe::NetworkDecision;
+use crate::startup::{
+    COMPONENT_DC_CONNECTIVITY_PING, COMPONENT_ME_CONNECTIVITY_PING, COMPONENT_RUNTIME_READY,
+    StartupTracker,
+};
+use crate::transport::middle_proxy::{
+    MePingFamily, MePingSample, MePool, format_me_route, format_sample_line, run_me_ping,
+};
+use crate::transport::UpstreamManager;
+
+pub(crate) async fn run_startup_connectivity(
+    config: &Arc<ProxyConfig>,
+    me_pool: &Option<Arc<MePool>>,
+    rng: Arc<SecureRandom>,
+    startup_tracker: &Arc<StartupTracker>,
+    upstream_manager: Arc<UpstreamManager>,
+    prefer_ipv6: bool,
+    decision: &NetworkDecision,
+    process_started_at: Instant,
+    api_me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+) {
+    if me_pool.is_some() {
+        startup_tracker
+            .start_component(
+                COMPONENT_ME_CONNECTIVITY_PING,
+                Some("run startup ME connectivity check".to_string()),
+            )
+            .await;
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_CONNECTIVITY_PING,
+                Some("ME pool is not available".to_string()),
+            )
+            .await;
+    }
+    if let Some(pool) = me_pool {
+        let me_results = run_me_ping(pool, &rng).await;
+
+        let v4_ok = me_results.iter().any(|r| {
+            matches!(r.family, MePingFamily::V4)
+                && r.samples.iter().any(|s| s.error.is_none() && s.handshake_ms.is_some())
+        });
+        let v6_ok = me_results.iter().any(|r| {
+            matches!(r.family, MePingFamily::V6)
+                && r.samples.iter().any(|s| s.error.is_none() && s.handshake_ms.is_some())
+        });
+
+        info!("================= Telegram ME Connectivity =================");
+        if v4_ok && v6_ok {
+            info!("  IPv4 and IPv6 available");
+        } else if v4_ok {
+            info!("  IPv4 only / IPv6 unavailable");
+        } else if v6_ok {
+            info!("  IPv6 only / IPv4 unavailable");
+        } else {
+            info!("  No ME connectivity");
+        }
+        let me_route =
+            format_me_route(&config.upstreams, &me_results, prefer_ipv6, v4_ok, v6_ok).await;
+        info!("  via {}", me_route);
+        info!("============================================================");
+
+        use std::collections::BTreeMap;
+        let mut grouped: BTreeMap<i32, Vec<MePingSample>> = BTreeMap::new();
+        for report in me_results {
+            for s in report.samples {
+                grouped.entry(s.dc).or_default().push(s);
+            }
+        }
+
+        let family_order = if prefer_ipv6 {
+            vec![MePingFamily::V6, MePingFamily::V4]
+        } else {
+            vec![MePingFamily::V4, MePingFamily::V6]
+        };
+
+        for (dc, samples) in grouped {
+            for family in &family_order {
+                let fam_samples: Vec<&MePingSample> = samples
+                    .iter()
+                    .filter(|s| matches!(s.family, f if &f == family))
+                    .collect();
+                if fam_samples.is_empty() {
+                    continue;
+                }
+
+                let fam_label = match family {
+                    MePingFamily::V4 => "IPv4",
+                    MePingFamily::V6 => "IPv6",
+                };
+                info!("    DC{} [{}]", dc, fam_label);
+                for sample in fam_samples {
+                    let line = format_sample_line(sample);
+                    info!("{}", line);
+                }
+            }
+        }
+        info!("============================================================");
+        startup_tracker
+            .complete_component(
+                COMPONENT_ME_CONNECTIVITY_PING,
+                Some("startup ME connectivity check completed".to_string()),
+            )
+            .await;
+    }
+
+    info!("================= Telegram DC Connectivity =================");
+    startup_tracker
+        .start_component(
+            COMPONENT_DC_CONNECTIVITY_PING,
+            Some("run startup DC connectivity check".to_string()),
+        )
+        .await;
+
+    let ping_results = upstream_manager
+        .ping_all_dcs(
+            prefer_ipv6,
+            &config.dc_overrides,
+            decision.ipv4_dc,
+            decision.ipv6_dc,
+        )
+        .await;
+
+    for upstream_result in &ping_results {
+        let v6_works = upstream_result.v6_results.iter().any(|r| r.rtt_ms.is_some());
+        let v4_works = upstream_result.v4_results.iter().any(|r| r.rtt_ms.is_some());
+
+        if upstream_result.both_available {
+            if prefer_ipv6 {
+                info!("  IPv6 in use / IPv4 is fallback");
+            } else {
+                info!("  IPv4 in use / IPv6 is fallback");
+            }
+        } else if v6_works && !v4_works {
+            info!("  IPv6 only / IPv4 unavailable");
+        } else if v4_works && !v6_works {
+            info!("  IPv4 only / IPv6 unavailable");
+        } else if !v6_works && !v4_works {
+            info!("  No DC connectivity");
+        }
+
+        info!("  via {}", upstream_result.upstream_name);
+        info!("============================================================");
+
+        if v6_works {
+            for dc in &upstream_result.v6_results {
+                let addr_str = format!("{}:{}", dc.dc_addr.ip(), dc.dc_addr.port());
+                match &dc.rtt_ms {
+                    Some(rtt) => {
+                        info!("    DC{} [IPv6] {} - {:.0} ms", dc.dc_idx, addr_str, rtt);
+                    }
+                    None => {
+                        let err = dc.error.as_deref().unwrap_or("fail");
+                        info!("    DC{} [IPv6] {} - FAIL ({})", dc.dc_idx, addr_str, err);
+                    }
+                }
+            }
+
+            info!("============================================================");
+        }
+
+        if v4_works {
+            for dc in &upstream_result.v4_results {
+                let addr_str = format!("{}:{}", dc.dc_addr.ip(), dc.dc_addr.port());
+                match &dc.rtt_ms {
+                    Some(rtt) => {
+                        info!(
+                            "    DC{} [IPv4] {}\t\t\t\t{:.0} ms",
+                            dc.dc_idx, addr_str, rtt
+                        );
+                    }
+                    None => {
+                        let err = dc.error.as_deref().unwrap_or("fail");
+                        info!(
+                            "    DC{} [IPv4] {}:\t\t\t\tFAIL ({})",
+                            dc.dc_idx, addr_str, err
+                        );
+                    }
+                }
+            }
+
+            info!("============================================================");
+        }
+    }
+    startup_tracker
+        .complete_component(
+            COMPONENT_DC_CONNECTIVITY_PING,
+            Some("startup DC connectivity check completed".to_string()),
+        )
+        .await;
+
+    let initialized_secs = process_started_at.elapsed().as_secs();
+    let second_suffix = if initialized_secs == 1 { "" } else { "s" };
+    startup_tracker
+        .start_component(
+            COMPONENT_RUNTIME_READY,
+            Some("finalize startup runtime state".to_string()),
+        )
+        .await;
+    info!("===================== Telegram Startup =====================");
+    info!(
+        "  DC/ME Initialized in {} second{}",
+        initialized_secs, second_suffix
+    );
+    info!("============================================================");
+
+    if let Some(pool) = me_pool {
+        pool.set_runtime_ready(true);
+    }
+    *api_me_pool.write().await = me_pool.clone();
+}

src/maestro/helpers.rs

@@ -0,0 +1,383 @@
+use std::time::Duration;
+use std::path::PathBuf;
+
+use tokio::sync::watch;
+use tracing::{debug, error, info, warn};
+
+use crate::cli;
+use crate::config::ProxyConfig;
+use crate::transport::middle_proxy::{
+    ProxyConfigData, fetch_proxy_config_with_raw, load_proxy_config_cache, save_proxy_config_cache,
+};
+
+pub(crate) fn resolve_runtime_config_path(config_path_cli: &str, startup_cwd: &std::path::Path) -> PathBuf {
+    let raw = PathBuf::from(config_path_cli);
+    let absolute = if raw.is_absolute() {
+        raw
+    } else {
+        startup_cwd.join(raw)
+    };
+    absolute.canonicalize().unwrap_or(absolute)
+}
+
+pub(crate) fn parse_cli() -> (String, Option<PathBuf>, bool, Option<String>) {
+    let mut config_path = "config.toml".to_string();
+    let mut data_path: Option<PathBuf> = None;
+    let mut silent = false;
+    let mut log_level: Option<String> = None;
+
+    let args: Vec<String> = std::env::args().skip(1).collect();
+
+    // Check for --init first (handled before tokio)
+    if let Some(init_opts) = cli::parse_init_args(&args) {
+        if let Err(e) = cli::run_init(init_opts) {
+            eprintln!("[telemt] Init failed: {}", e);
+            std::process::exit(1);
+        }
+        std::process::exit(0);
+    }
+
+    let mut i = 0;
+    while i < args.len() {
+        match args[i].as_str() {
+            "--data-path" => {
+                i += 1;
+                if i < args.len() {
+                    data_path = Some(PathBuf::from(args[i].clone()));
+                } else {
+                    eprintln!("Missing value for --data-path");
+                    std::process::exit(0);
+                }
+            }
+            s if s.starts_with("--data-path=") => {
+                data_path = Some(PathBuf::from(s.trim_start_matches("--data-path=").to_string()));
+            }
+            "--silent" | "-s" => {
+                silent = true;
+            }
+            "--log-level" => {
+                i += 1;
+                if i < args.len() {
+                    log_level = Some(args[i].clone());
+                }
+            }
+            s if s.starts_with("--log-level=") => {
+                log_level = Some(s.trim_start_matches("--log-level=").to_string());
+            }
+            "--help" | "-h" => {
+                eprintln!("Usage: telemt [config.toml] [OPTIONS]");
+                eprintln!();
+                eprintln!("Options:");
+                eprintln!("  --data-path <DIR>       Set data directory (absolute path; overrides config value)");
+                eprintln!("  --silent, -s            Suppress info logs");
+                eprintln!("  --log-level <LEVEL>     debug|verbose|normal|silent");
+                eprintln!("  --help, -h              Show this help");
+                eprintln!();
+                eprintln!("Setup (fire-and-forget):");
+                eprintln!(
+                    "  --init                  Generate config, install systemd service, start"
+                );
+                eprintln!("    --port <PORT>          Listen port (default: 443)");
+                eprintln!(
+                    "    --domain <DOMAIN>      TLS domain for masking (default: www.google.com)"
+                );
+                eprintln!(
+                    "    --secret <HEX>         32-char hex secret (auto-generated if omitted)"
+                );
+                eprintln!("    --user <NAME>          Username (default: user)");
+                eprintln!("    --config-dir <DIR>     Config directory (default: /etc/telemt)");
+                eprintln!("    --no-start             Don't start the service after install");
+                std::process::exit(0);
+            }
+            "--version" | "-V" => {
+                println!("telemt {}", env!("CARGO_PKG_VERSION"));
+                std::process::exit(0);
+            }
+            s if !s.starts_with('-') => {
+                config_path = s.to_string();
+            }
+            other => {
+                eprintln!("Unknown option: {}", other);
+            }
+        }
+        i += 1;
+    }
+
+    (config_path, data_path, silent, log_level)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::resolve_runtime_config_path;
+
+    #[test]
+    fn resolve_runtime_config_path_anchors_relative_to_startup_cwd() {
+        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_cfg_path_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+        let target = startup_cwd.join("config.toml");
+        std::fs::write(&target, " ").unwrap();
+
+        let resolved = resolve_runtime_config_path("config.toml", &startup_cwd);
+        assert_eq!(resolved, target.canonicalize().unwrap());
+
+        let _ = std::fs::remove_file(&target);
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+
+    #[test]
+    fn resolve_runtime_config_path_keeps_absolute_for_missing_file() {
+        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_cfg_path_missing_{nonce}"));
+        std::fs::create_dir_all(&startup_cwd).unwrap();
+
+        let resolved = resolve_runtime_config_path("missing.toml", &startup_cwd);
+        assert_eq!(resolved, startup_cwd.join("missing.toml"));
+
+        let _ = std::fs::remove_dir(&startup_cwd);
+    }
+}
+
+pub(crate) fn print_proxy_links(host: &str, port: u16, config: &ProxyConfig) {
+    info!(target: "telemt::links", "--- Proxy Links ({}) ---", host);
+    for user_name in config.general.links.show.resolve_users(&config.access.users) {
+        if let Some(secret) = config.access.users.get(user_name) {
+            info!(target: "telemt::links", "User: {}", user_name);
+            if config.general.modes.classic {
+                info!(
+                    target: "telemt::links",
+                    "  Classic: tg://proxy?server={}&port={}&secret={}",
+                    host, port, secret
+                );
+            }
+            if config.general.modes.secure {
+                info!(
+                    target: "telemt::links",
+                    "  DD:      tg://proxy?server={}&port={}&secret=dd{}",
+                    host, port, secret
+                );
+            }
+            if config.general.modes.tls {
+                let mut domains = Vec::with_capacity(1 + config.censorship.tls_domains.len());
+                domains.push(config.censorship.tls_domain.clone());
+                for d in &config.censorship.tls_domains {
+                    if !domains.contains(d) {
+                        domains.push(d.clone());
+                    }
+                }
+
+                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
+                    );
+                }
+            }
+        } 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<()> {
+    if let Some(parent) = std::path::Path::new(path).parent()
+        && !parent.as_os_str().is_empty()
+    {
+        tokio::fs::create_dir_all(parent).await?;
+    }
+    tokio::fs::write(path, payload).await
+}
+
+pub(crate) fn unit_label(value: u64, singular: &'static str, plural: &'static str) -> &'static str {
+    if value == 1 { singular } else { plural }
+}
+
+pub(crate) fn format_uptime(total_secs: u64) -> String {
+    const SECS_PER_MINUTE: u64 = 60;
+    const SECS_PER_HOUR: u64 = 60 * SECS_PER_MINUTE;
+    const SECS_PER_DAY: u64 = 24 * SECS_PER_HOUR;
+    const SECS_PER_MONTH: u64 = 30 * SECS_PER_DAY;
+    const SECS_PER_YEAR: u64 = 12 * SECS_PER_MONTH;
+
+    let mut remaining = total_secs;
+    let years = remaining / SECS_PER_YEAR;
+    remaining %= SECS_PER_YEAR;
+    let months = remaining / SECS_PER_MONTH;
+    remaining %= SECS_PER_MONTH;
+    let days = remaining / SECS_PER_DAY;
+    remaining %= SECS_PER_DAY;
+    let hours = remaining / SECS_PER_HOUR;
+    remaining %= SECS_PER_HOUR;
+    let minutes = remaining / SECS_PER_MINUTE;
+    let seconds = remaining % SECS_PER_MINUTE;
+
+    let mut parts = Vec::new();
+    if total_secs > SECS_PER_YEAR {
+        parts.push(format!("{} {}", years, unit_label(years, "year", "years")));
+    }
+    if total_secs > SECS_PER_MONTH {
+        parts.push(format!(
+            "{} {}",
+            months,
+            unit_label(months, "month", "months")
+        ));
+    }
+    if total_secs > SECS_PER_DAY {
+        parts.push(format!("{} {}", days, unit_label(days, "day", "days")));
+    }
+    if total_secs > SECS_PER_HOUR {
+        parts.push(format!("{} {}", hours, unit_label(hours, "hour", "hours")));
+    }
+    if total_secs > SECS_PER_MINUTE {
+        parts.push(format!(
+            "{} {}",
+            minutes,
+            unit_label(minutes, "minute", "minutes")
+        ));
+    }
+    parts.push(format!(
+        "{} {}",
+        seconds,
+        unit_label(seconds, "second", "seconds")
+    ));
+
+    format!("{} / {} seconds", parts.join(", "), total_secs)
+}
+
+pub(crate) async fn wait_until_admission_open(admission_rx: &mut watch::Receiver<bool>) -> bool {
+    loop {
+        if *admission_rx.borrow() {
+            return true;
+        }
+        if admission_rx.changed().await.is_err() {
+            return *admission_rx.borrow();
+        }
+    }
+}
+
+pub(crate) fn is_expected_handshake_eof(err: &crate::error::ProxyError) -> bool {
+    err.to_string().contains("expected 64 bytes, got 0")
+}
+
+pub(crate) async fn load_startup_proxy_config_snapshot(
+    url: &str,
+    cache_path: Option<&str>,
+    me2dc_fallback: bool,
+    label: &'static str,
+) -> Option<ProxyConfigData> {
+    loop {
+        match fetch_proxy_config_with_raw(url).await {
+            Ok((cfg, raw)) => {
+                if !cfg.map.is_empty() {
+                    if let Some(path) = cache_path
+                        && let Err(e) = save_proxy_config_cache(path, &raw).await
+                    {
+                        warn!(error = %e, path, snapshot = label, "Failed to store startup proxy-config cache");
+                    }
+                    return Some(cfg);
+                }
+
+                warn!(snapshot = label, url, "Startup proxy-config is empty; trying disk cache");
+                if let Some(path) = cache_path {
+                    match load_proxy_config_cache(path).await {
+                        Ok(cached) if !cached.map.is_empty() => {
+                            info!(
+                                snapshot = label,
+                                path,
+                                proxy_for_lines = cached.proxy_for_lines,
+                                "Loaded startup proxy-config from disk cache"
+                            );
+                            return Some(cached);
+                        }
+                        Ok(_) => {
+                            warn!(
+                                snapshot = label,
+                                path,
+                                "Startup proxy-config cache is empty; ignoring cache file"
+                            );
+                        }
+                        Err(cache_err) => {
+                            debug!(
+                                snapshot = label,
+                                path,
+                                error = %cache_err,
+                                "Startup proxy-config cache unavailable"
+                            );
+                        }
+                    }
+                }
+
+                if me2dc_fallback {
+                    error!(
+                        snapshot = label,
+                        "Startup proxy-config unavailable and no saved config found; falling back to direct mode"
+                    );
+                    return None;
+                }
+
+                warn!(
+                    snapshot = label,
+                    retry_in_secs = 2,
+                    "Startup proxy-config unavailable and no saved config found; retrying because me2dc_fallback=false"
+                );
+                tokio::time::sleep(Duration::from_secs(2)).await;
+            }
+            Err(fetch_err) => {
+                if let Some(path) = cache_path {
+                    match load_proxy_config_cache(path).await {
+                        Ok(cached) if !cached.map.is_empty() => {
+                            info!(
+                                snapshot = label,
+                                path,
+                                proxy_for_lines = cached.proxy_for_lines,
+                                "Loaded startup proxy-config from disk cache"
+                            );
+                            return Some(cached);
+                        }
+                        Ok(_) => {
+                            warn!(
+                                snapshot = label,
+                                path,
+                                "Startup proxy-config cache is empty; ignoring cache file"
+                            );
+                        }
+                        Err(cache_err) => {
+                            debug!(
+                                snapshot = label,
+                                path,
+                                error = %cache_err,
+                                "Startup proxy-config cache unavailable"
+                            );
+                        }
+                    }
+                }
+
+                if me2dc_fallback {
+                    error!(
+                        snapshot = label,
+                        error = %fetch_err,
+                        "Startup proxy-config unavailable and no cached data; falling back to direct mode"
+                    );
+                    return None;
+                }
+
+                warn!(
+                    snapshot = label,
+                    error = %fetch_err,
+                    retry_in_secs = 2,
+                    "Startup proxy-config unavailable; retrying because me2dc_fallback=false"
+                );
+                tokio::time::sleep(Duration::from_secs(2)).await;
+            }
+        }
+    }
+}

src/maestro/listeners.rs

@@ -0,0 +1,465 @@
+use std::error::Error;
+use std::net::{IpAddr, SocketAddr};
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::net::TcpListener;
+#[cfg(unix)]
+use tokio::net::UnixListener;
+use tokio::sync::{Semaphore, watch};
+use tracing::{debug, error, info, warn};
+
+use crate::config::ProxyConfig;
+use crate::crypto::SecureRandom;
+use crate::ip_tracker::UserIpTracker;
+use crate::proxy::route_mode::{ROUTE_SWITCH_ERROR_MSG, RouteRuntimeController};
+use crate::proxy::ClientHandler;
+use crate::startup::{COMPONENT_LISTENERS_BIND, StartupTracker};
+use crate::stats::beobachten::BeobachtenStore;
+use crate::stats::{ReplayChecker, Stats};
+use crate::stream::BufferPool;
+use crate::tls_front::TlsFrontCache;
+use crate::transport::middle_proxy::MePool;
+use crate::transport::{
+    ListenOptions, UpstreamManager, create_listener, find_listener_processes,
+};
+
+use super::helpers::{is_expected_handshake_eof, print_proxy_links, wait_until_admission_open};
+
+pub(crate) struct BoundListeners {
+    pub(crate) listeners: Vec<(TcpListener, bool)>,
+    pub(crate) has_unix_listener: bool,
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn bind_listeners(
+    config: &Arc<ProxyConfig>,
+    decision_ipv4_dc: bool,
+    decision_ipv6_dc: bool,
+    detected_ip_v4: Option<IpAddr>,
+    detected_ip_v6: Option<IpAddr>,
+    startup_tracker: &Arc<StartupTracker>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    admission_rx: watch::Receiver<bool>,
+    stats: Arc<Stats>,
+    upstream_manager: Arc<UpstreamManager>,
+    replay_checker: Arc<ReplayChecker>,
+    buffer_pool: Arc<BufferPool>,
+    rng: Arc<SecureRandom>,
+    me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    tls_cache: Option<Arc<TlsFrontCache>>,
+    ip_tracker: Arc<UserIpTracker>,
+    beobachten: Arc<BeobachtenStore>,
+    max_connections: Arc<Semaphore>,
+) -> Result<BoundListeners, Box<dyn Error>> {
+    startup_tracker
+        .start_component(
+            COMPONENT_LISTENERS_BIND,
+            Some("bind TCP/Unix listeners".to_string()),
+        )
+        .await;
+    let mut listeners = Vec::new();
+
+    for listener_conf in &config.server.listeners {
+        let addr = SocketAddr::new(listener_conf.ip, config.server.port);
+        if addr.is_ipv4() && !decision_ipv4_dc {
+            warn!(%addr, "Skipping IPv4 listener: IPv4 disabled by [network]");
+            continue;
+        }
+        if addr.is_ipv6() && !decision_ipv6_dc {
+            warn!(%addr, "Skipping IPv6 listener: IPv6 disabled by [network]");
+            continue;
+        }
+        let options = ListenOptions {
+            reuse_port: listener_conf.reuse_allow,
+            ipv6_only: listener_conf.ip.is_ipv6(),
+            ..Default::default()
+        };
+
+        match create_listener(addr, &options) {
+            Ok(socket) => {
+                let listener = TcpListener::from_std(socket.into())?;
+                info!("Listening on {}", addr);
+                let listener_proxy_protocol =
+                    listener_conf.proxy_protocol.unwrap_or(config.server.proxy_protocol);
+
+                let public_host = if let Some(ref announce) = listener_conf.announce {
+                    announce.clone()
+                } else if listener_conf.ip.is_unspecified() {
+                    if listener_conf.ip.is_ipv4() {
+                        detected_ip_v4
+                            .map(|ip| ip.to_string())
+                            .unwrap_or_else(|| listener_conf.ip.to_string())
+                    } else {
+                        detected_ip_v6
+                            .map(|ip| ip.to_string())
+                            .unwrap_or_else(|| listener_conf.ip.to_string())
+                    }
+                } else {
+                    listener_conf.ip.to_string()
+                };
+
+                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);
+                    print_proxy_links(&public_host, link_port, config);
+                }
+
+                listeners.push((listener, listener_proxy_protocol));
+            }
+            Err(e) => {
+                if e.kind() == std::io::ErrorKind::AddrInUse {
+                    let owners = find_listener_processes(addr);
+                    if owners.is_empty() {
+                        error!(
+                            %addr,
+                            "Failed to bind: address already in use (owner process unresolved)"
+                        );
+                    } else {
+                        for owner in owners {
+                            error!(
+                                %addr,
+                                pid = owner.pid,
+                                process = %owner.process,
+                                "Failed to bind: address already in use"
+                            );
+                        }
+                    }
+
+                    if !listener_conf.reuse_allow {
+                        error!(
+                            %addr,
+                            "reuse_allow=false; set [[server.listeners]].reuse_allow=true to allow multi-instance listening"
+                        );
+                    }
+                } else {
+                    error!("Failed to bind to {}: {}", addr, e);
+                }
+            }
+        }
+    }
+
+    if !config.general.links.show.is_empty()
+        && (config.general.links.public_host.is_some() || listeners.is_empty())
+    {
+        let (host, port) = if let Some(ref h) = config.general.links.public_host {
+            (
+                h.clone(),
+                config.general.links.public_port.unwrap_or(config.server.port),
+            )
+        } else {
+            let ip = detected_ip_v4
+                .or(detected_ip_v6)
+                .map(|ip| ip.to_string());
+            if ip.is_none() {
+                warn!(
+                    "show_link is configured but public IP could not be detected. Set public_host in config."
+                );
+            }
+            (
+                ip.unwrap_or_else(|| "UNKNOWN".to_string()),
+                config.general.links.public_port.unwrap_or(config.server.port),
+            )
+        };
+
+        print_proxy_links(&host, port, config);
+    }
+
+    let mut has_unix_listener = false;
+    #[cfg(unix)]
+    if let Some(ref unix_path) = config.server.listen_unix_sock {
+        let _ = tokio::fs::remove_file(unix_path).await;
+
+        let unix_listener = UnixListener::bind(unix_path)?;
+
+        if let Some(ref perm_str) = config.server.listen_unix_sock_perm {
+            match u32::from_str_radix(perm_str.trim_start_matches('0'), 8) {
+                Ok(mode) => {
+                    use std::os::unix::fs::PermissionsExt;
+                    let perms = std::fs::Permissions::from_mode(mode);
+                    if let Err(e) = std::fs::set_permissions(unix_path, perms) {
+                        error!("Failed to set unix socket permissions to {}: {}", perm_str, e);
+                    } else {
+                        info!("Listening on unix:{} (mode {})", unix_path, perm_str);
+                    }
+                }
+                Err(e) => {
+                    warn!("Invalid listen_unix_sock_perm '{}': {}. Ignoring.", perm_str, e);
+                    info!("Listening on unix:{}", unix_path);
+                }
+            }
+        } else {
+            info!("Listening on unix:{}", unix_path);
+        }
+
+        has_unix_listener = true;
+
+        let mut config_rx_unix: watch::Receiver<Arc<ProxyConfig>> = config_rx.clone();
+        let mut admission_rx_unix = admission_rx.clone();
+        let stats = stats.clone();
+        let upstream_manager = upstream_manager.clone();
+        let replay_checker = replay_checker.clone();
+        let buffer_pool = buffer_pool.clone();
+        let rng = rng.clone();
+        let me_pool = me_pool.clone();
+        let route_runtime = route_runtime.clone();
+        let tls_cache = tls_cache.clone();
+        let ip_tracker = ip_tracker.clone();
+        let beobachten = beobachten.clone();
+        let max_connections_unix = max_connections.clone();
+
+        tokio::spawn(async move {
+            let unix_conn_counter = Arc::new(std::sync::atomic::AtomicU64::new(1));
+
+            loop {
+                if !wait_until_admission_open(&mut admission_rx_unix).await {
+                    warn!("Conditional-admission gate channel closed for unix listener");
+                    break;
+                }
+                match unix_listener.accept().await {
+                    Ok((stream, _)) => {
+                        let permit = match max_connections_unix.clone().acquire_owned().await {
+                            Ok(permit) => permit,
+                            Err(_) => {
+                                error!("Connection limiter is closed");
+                                break;
+                            }
+                        };
+                        let conn_id =
+                            unix_conn_counter.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+                        let fake_peer =
+                            SocketAddr::from(([127, 0, 0, 1], (conn_id % 65535) as u16));
+
+                        let config = config_rx_unix.borrow_and_update().clone();
+                        let stats = stats.clone();
+                        let upstream_manager = upstream_manager.clone();
+                        let replay_checker = replay_checker.clone();
+                        let buffer_pool = buffer_pool.clone();
+                        let rng = rng.clone();
+                        let me_pool = me_pool.clone();
+                        let route_runtime = route_runtime.clone();
+                        let tls_cache = tls_cache.clone();
+                        let ip_tracker = ip_tracker.clone();
+                        let beobachten = beobachten.clone();
+                        let proxy_protocol_enabled = config.server.proxy_protocol;
+
+                        tokio::spawn(async move {
+                            let _permit = permit;
+                            if let Err(e) = crate::proxy::client::handle_client_stream(
+                                stream,
+                                fake_peer,
+                                config,
+                                stats,
+                                upstream_manager,
+                                replay_checker,
+                                buffer_pool,
+                                rng,
+                                me_pool,
+                                route_runtime,
+                                tls_cache,
+                                ip_tracker,
+                                beobachten,
+                                proxy_protocol_enabled,
+                            )
+                            .await
+                            {
+                                debug!(error = %e, "Unix socket connection error");
+                            }
+                        });
+                    }
+                    Err(e) => {
+                        error!("Unix socket accept error: {}", e);
+                        tokio::time::sleep(Duration::from_millis(100)).await;
+                    }
+                }
+            }
+        });
+    }
+
+    startup_tracker
+        .complete_component(
+            COMPONENT_LISTENERS_BIND,
+            Some(format!(
+                "listeners configured tcp={} unix={}",
+                listeners.len(),
+                has_unix_listener
+            )),
+        )
+        .await;
+
+    Ok(BoundListeners {
+        listeners,
+        has_unix_listener,
+    })
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn spawn_tcp_accept_loops(
+    listeners: Vec<(TcpListener, bool)>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    admission_rx: watch::Receiver<bool>,
+    stats: Arc<Stats>,
+    upstream_manager: Arc<UpstreamManager>,
+    replay_checker: Arc<ReplayChecker>,
+    buffer_pool: Arc<BufferPool>,
+    rng: Arc<SecureRandom>,
+    me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
+    tls_cache: Option<Arc<TlsFrontCache>>,
+    ip_tracker: Arc<UserIpTracker>,
+    beobachten: Arc<BeobachtenStore>,
+    max_connections: Arc<Semaphore>,
+) {
+    for (listener, listener_proxy_protocol) in listeners {
+        let mut config_rx: watch::Receiver<Arc<ProxyConfig>> = config_rx.clone();
+        let mut admission_rx_tcp = admission_rx.clone();
+        let stats = stats.clone();
+        let upstream_manager = upstream_manager.clone();
+        let replay_checker = replay_checker.clone();
+        let buffer_pool = buffer_pool.clone();
+        let rng = rng.clone();
+        let me_pool = me_pool.clone();
+        let route_runtime = route_runtime.clone();
+        let tls_cache = tls_cache.clone();
+        let ip_tracker = ip_tracker.clone();
+        let beobachten = beobachten.clone();
+        let max_connections_tcp = max_connections.clone();
+
+        tokio::spawn(async move {
+            loop {
+                if !wait_until_admission_open(&mut admission_rx_tcp).await {
+                    warn!("Conditional-admission gate channel closed for tcp listener");
+                    break;
+                }
+                match listener.accept().await {
+                    Ok((stream, peer_addr)) => {
+                        let permit = match max_connections_tcp.clone().acquire_owned().await {
+                            Ok(permit) => permit,
+                            Err(_) => {
+                                error!("Connection limiter is closed");
+                                break;
+                            }
+                        };
+                        let config = config_rx.borrow_and_update().clone();
+                        let stats = stats.clone();
+                        let upstream_manager = upstream_manager.clone();
+                        let replay_checker = replay_checker.clone();
+                        let buffer_pool = buffer_pool.clone();
+                        let rng = rng.clone();
+                        let me_pool = me_pool.clone();
+                        let route_runtime = route_runtime.clone();
+                        let tls_cache = tls_cache.clone();
+                        let ip_tracker = ip_tracker.clone();
+                        let beobachten = beobachten.clone();
+                        let proxy_protocol_enabled = listener_proxy_protocol;
+                        let real_peer_report = Arc::new(std::sync::Mutex::new(None));
+                        let real_peer_report_for_handler = real_peer_report.clone();
+
+                        tokio::spawn(async move {
+                            let _permit = permit;
+                            if let Err(e) = ClientHandler::new(
+                                stream,
+                                peer_addr,
+                                config,
+                                stats,
+                                upstream_manager,
+                                replay_checker,
+                                buffer_pool,
+                                rng,
+                                me_pool,
+                                route_runtime,
+                                tls_cache,
+                                ip_tracker,
+                                beobachten,
+                                proxy_protocol_enabled,
+                                real_peer_report_for_handler,
+                            )
+                            .run()
+                            .await
+                            {
+                                let real_peer = match real_peer_report.lock() {
+                                    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 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
+                                );
+
+                                match (peer_closed, me_closed) {
+                                    (true, _) => {
+                                        if let Some(real_peer) = real_peer {
+                                            debug!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed by client");
+                                        } else {
+                                            debug!(peer = %peer_addr, error = %e, "Connection closed by client");
+                                        }
+                                    }
+                                    (_, true) => {
+                                        if let Some(real_peer) = real_peer {
+                                            warn!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed: Middle-End dropped session");
+                                        } else {
+                                            warn!(peer = %peer_addr, error = %e, "Connection closed: Middle-End dropped session");
+                                        }
+                                    }
+                                    _ if route_switched => {
+                                        if let Some(real_peer) = real_peer {
+                                            info!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed by controlled route cutover");
+                                        } else {
+                                            info!(peer = %peer_addr, error = %e, "Connection closed by controlled route cutover");
+                                        }
+                                    }
+                                    _ if is_expected_handshake_eof(&e) => {
+                                        if let Some(real_peer) = real_peer {
+                                            info!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed during initial handshake");
+                                        } else {
+                                            info!(peer = %peer_addr, error = %e, "Connection closed during initial handshake");
+                                        }
+                                    }
+                                    _ => {
+                                        if let Some(real_peer) = real_peer {
+                                            warn!(peer = %peer_addr, real_peer = %real_peer, error = %e, "Connection closed with error");
+                                        } else {
+                                            warn!(peer = %peer_addr, error = %e, "Connection closed with error");
+                                        }
+                                    }
+                                }
+                            }
+                        });
+                    }
+                    Err(e) => {
+                        error!("Accept error: {}", e);
+                        tokio::time::sleep(Duration::from_millis(100)).await;
+                    }
+                }
+            }
+        });
+    }
+}

src/maestro/me_startup.rs

@@ -0,0 +1,516 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::sync::RwLock;
+use tracing::{error, info, warn};
+
+use crate::config::ProxyConfig;
+use crate::crypto::SecureRandom;
+use crate::network::probe::{NetworkDecision, NetworkProbe};
+use crate::startup::{
+    COMPONENT_ME_POOL_CONSTRUCT, COMPONENT_ME_POOL_INIT_STAGE1, COMPONENT_ME_PROXY_CONFIG_V4,
+    COMPONENT_ME_PROXY_CONFIG_V6, COMPONENT_ME_SECRET_FETCH, StartupMeStatus, StartupTracker,
+};
+use crate::stats::Stats;
+use crate::transport::middle_proxy::MePool;
+use crate::transport::UpstreamManager;
+
+use super::helpers::load_startup_proxy_config_snapshot;
+
+pub(crate) async fn initialize_me_pool(
+    use_middle_proxy: bool,
+    config: &ProxyConfig,
+    decision: &NetworkDecision,
+    probe: &NetworkProbe,
+    startup_tracker: &Arc<StartupTracker>,
+    upstream_manager: Arc<UpstreamManager>,
+    rng: Arc<SecureRandom>,
+    stats: Arc<Stats>,
+    api_me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
+) -> Option<Arc<MePool>> {
+    if !use_middle_proxy {
+        return None;
+    }
+
+    info!("=== Middle Proxy Mode ===");
+    let me_nat_probe = config.general.middle_proxy_nat_probe && config.network.stun_use;
+    if config.general.middle_proxy_nat_probe && !config.network.stun_use {
+        info!("Middle-proxy STUN probing disabled by network.stun_use=false");
+    }
+
+    let me2dc_fallback = config.general.me2dc_fallback;
+    let me_init_retry_attempts = config.general.me_init_retry_attempts;
+    let me_init_warn_after_attempts: u32 = 3;
+
+    // Global ad_tag (pool default). Used when user has no per-user tag in access.user_ad_tags.
+    let proxy_tag = config
+        .general
+        .ad_tag
+        .as_ref()
+        .map(|tag| hex::decode(tag).expect("general.ad_tag must be validated before startup"));
+
+    // =============================================================
+    // CRITICAL: Download Telegram proxy-secret (NOT user secret!)
+    //
+    // C MTProxy uses TWO separate secrets:
+    //   -S flag    = 16-byte user secret for client obfuscation
+    //   --aes-pwd  = 32-512 byte binary file for ME RPC auth
+    //
+    // proxy-secret is from: https://core.telegram.org/getProxySecret
+    // =============================================================
+    let proxy_secret_path = config.general.proxy_secret_path.as_deref();
+    let pool_size = config.general.middle_proxy_pool_size.max(1);
+    let proxy_secret = loop {
+        match crate::transport::middle_proxy::fetch_proxy_secret(
+            proxy_secret_path,
+            config.general.proxy_secret_len_max,
+        )
+        .await
+        {
+            Ok(proxy_secret) => break Some(proxy_secret),
+            Err(e) => {
+                startup_tracker.set_me_last_error(Some(e.to_string())).await;
+                if me2dc_fallback {
+                    error!(
+                        error = %e,
+                        "ME startup failed: proxy-secret is unavailable and no saved secret found; falling back to direct mode"
+                    );
+                    break None;
+                }
+
+                warn!(
+                    error = %e,
+                    retry_in_secs = 2,
+                    "ME startup failed: proxy-secret is unavailable and no saved secret found; retrying because me2dc_fallback=false"
+                );
+                tokio::time::sleep(Duration::from_secs(2)).await;
+            }
+        }
+    };
+    match proxy_secret {
+        Some(proxy_secret) => {
+            startup_tracker
+                .complete_component(
+                    COMPONENT_ME_SECRET_FETCH,
+                    Some("proxy-secret loaded".to_string()),
+                )
+                .await;
+            info!(
+                secret_len = proxy_secret.len(),
+                key_sig = format_args!(
+                    "0x{:08x}",
+                    if proxy_secret.len() >= 4 {
+                        u32::from_le_bytes([
+                            proxy_secret[0],
+                            proxy_secret[1],
+                            proxy_secret[2],
+                            proxy_secret[3],
+                        ])
+                    } else {
+                        0
+                    }
+                ),
+                "Proxy-secret loaded"
+            );
+
+            startup_tracker
+                .start_component(
+                    COMPONENT_ME_PROXY_CONFIG_V4,
+                    Some("load startup proxy-config v4".to_string()),
+                )
+                .await;
+            startup_tracker
+                .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_cache_path.as_deref(),
+                me2dc_fallback,
+                "getProxyConfig",
+            )
+            .await;
+            if cfg_v4.is_some() {
+                startup_tracker
+                    .complete_component(
+                        COMPONENT_ME_PROXY_CONFIG_V4,
+                        Some("proxy-config v4 loaded".to_string()),
+                    )
+                    .await;
+            } else {
+                startup_tracker
+                    .fail_component(
+                        COMPONENT_ME_PROXY_CONFIG_V4,
+                        Some("proxy-config v4 unavailable".to_string()),
+                    )
+                    .await;
+            }
+            startup_tracker
+                .start_component(
+                    COMPONENT_ME_PROXY_CONFIG_V6,
+                    Some("load startup proxy-config v6".to_string()),
+                )
+                .await;
+            startup_tracker
+                .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_cache_path.as_deref(),
+                me2dc_fallback,
+                "getProxyConfigV6",
+            )
+            .await;
+            if cfg_v6.is_some() {
+                startup_tracker
+                    .complete_component(
+                        COMPONENT_ME_PROXY_CONFIG_V6,
+                        Some("proxy-config v6 loaded".to_string()),
+                    )
+                    .await;
+            } else {
+                startup_tracker
+                    .fail_component(
+                        COMPONENT_ME_PROXY_CONFIG_V6,
+                        Some("proxy-config v6 unavailable".to_string()),
+                    )
+                    .await;
+            }
+
+            if let (Some(cfg_v4), Some(cfg_v6)) = (cfg_v4, cfg_v6) {
+                startup_tracker
+                    .start_component(
+                        COMPONENT_ME_POOL_CONSTRUCT,
+                        Some("construct ME pool".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_POOL_CONSTRUCT)
+                    .await;
+                let pool = MePool::new(
+                    proxy_tag.clone(),
+                    proxy_secret,
+                    config.general.middle_proxy_nat_ip,
+                    me_nat_probe,
+                    None,
+                    config.network.stun_servers.clone(),
+                    config.general.stun_nat_probe_concurrency,
+                    probe.detected_ipv6,
+                    config.timeouts.me_one_retry,
+                    config.timeouts.me_one_timeout_ms,
+                    cfg_v4.map.clone(),
+                    cfg_v6.map.clone(),
+                    cfg_v4.default_dc.or(cfg_v6.default_dc),
+                    decision.clone(),
+                    Some(upstream_manager.clone()),
+                    rng.clone(),
+                    stats.clone(),
+                    config.general.me_keepalive_enabled,
+                    config.general.me_keepalive_interval_secs,
+                    config.general.me_keepalive_jitter_secs,
+                    config.general.me_keepalive_payload_random,
+                    config.general.rpc_proxy_req_every,
+                    config.general.me_warmup_stagger_enabled,
+                    config.general.me_warmup_step_delay_ms,
+                    config.general.me_warmup_step_jitter_ms,
+                    config.general.me_reconnect_max_concurrent_per_dc,
+                    config.general.me_reconnect_backoff_base_ms,
+                    config.general.me_reconnect_backoff_cap_ms,
+                    config.general.me_reconnect_fast_retry_count,
+                    config.general.me_single_endpoint_shadow_writers,
+                    config.general.me_single_endpoint_outage_mode_enabled,
+                    config.general.me_single_endpoint_outage_disable_quarantine,
+                    config.general.me_single_endpoint_outage_backoff_min_ms,
+                    config.general.me_single_endpoint_outage_backoff_max_ms,
+                    config.general.me_single_endpoint_shadow_rotate_every_secs,
+                    config.general.me_floor_mode,
+                    config.general.me_adaptive_floor_idle_secs,
+                    config.general.me_adaptive_floor_min_writers_single_endpoint,
+                    config.general.me_adaptive_floor_min_writers_multi_endpoint,
+                    config.general.me_adaptive_floor_recover_grace_secs,
+                    config.general.me_adaptive_floor_writers_per_core_total,
+                    config.general.me_adaptive_floor_cpu_cores_override,
+                    config.general.me_adaptive_floor_max_extra_writers_single_per_core,
+                    config.general.me_adaptive_floor_max_extra_writers_multi_per_core,
+                    config.general.me_adaptive_floor_max_active_writers_per_core,
+                    config.general.me_adaptive_floor_max_warm_writers_per_core,
+                    config.general.me_adaptive_floor_max_active_writers_global,
+                    config.general.me_adaptive_floor_max_warm_writers_global,
+                    config.general.hardswap,
+                    config.general.me_pool_drain_ttl_secs,
+                    config.general.me_pool_drain_threshold,
+                    config.general.effective_me_pool_force_close_secs(),
+                    config.general.me_pool_min_fresh_ratio,
+                    config.general.me_hardswap_warmup_delay_min_ms,
+                    config.general.me_hardswap_warmup_delay_max_ms,
+                    config.general.me_hardswap_warmup_extra_passes,
+                    config.general.me_hardswap_warmup_pass_backoff_base_ms,
+                    config.general.me_bind_stale_mode,
+                    config.general.me_bind_stale_ttl_secs,
+                    config.general.me_secret_atomic_snapshot,
+                    config.general.me_deterministic_writer_sort,
+                    config.general.me_writer_pick_mode,
+                    config.general.me_writer_pick_sample_size,
+                    config.general.me_socks_kdf_policy,
+                    config.general.me_writer_cmd_channel_capacity,
+                    config.general.me_route_channel_capacity,
+                    config.general.me_route_backpressure_base_timeout_ms,
+                    config.general.me_route_backpressure_high_timeout_ms,
+                    config.general.me_route_backpressure_high_watermark_pct,
+                    config.general.me_reader_route_data_wait_ms,
+                    config.general.me_health_interval_ms_unhealthy,
+                    config.general.me_health_interval_ms_healthy,
+                    config.general.me_warn_rate_limit_ms,
+                    config.general.me_route_no_writer_mode,
+                    config.general.me_route_no_writer_wait_ms,
+                    config.general.me_route_inline_recovery_attempts,
+                    config.general.me_route_inline_recovery_wait_ms,
+                );
+                startup_tracker
+                    .complete_component(
+                        COMPONENT_ME_POOL_CONSTRUCT,
+                        Some("ME pool object created".to_string()),
+                    )
+                    .await;
+                *api_me_pool.write().await = Some(pool.clone());
+                startup_tracker
+                    .start_component(
+                        COMPONENT_ME_POOL_INIT_STAGE1,
+                        Some("initialize ME pool writers".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_POOL_INIT_STAGE1)
+                    .await;
+
+                if me2dc_fallback {
+                    let pool_bg = pool.clone();
+                    let rng_bg = rng.clone();
+                    let startup_tracker_bg = startup_tracker.clone();
+                    let retry_limit = if me_init_retry_attempts == 0 {
+                        String::from("unlimited")
+                    } else {
+                        me_init_retry_attempts.to_string()
+                    };
+                    std::thread::spawn(move || {
+                        let runtime = match tokio::runtime::Builder::new_current_thread()
+                            .enable_all()
+                            .build()
+                        {
+                            Ok(runtime) => runtime,
+                            Err(error) => {
+                                error!(error = %error, "Failed to build background runtime for ME initialization");
+                                return;
+                            }
+                        };
+                        runtime.block_on(async move {
+                            let mut init_attempt: u32 = 0;
+                            loop {
+                                init_attempt = init_attempt.saturating_add(1);
+                                startup_tracker_bg.set_me_init_attempt(init_attempt).await;
+                                match pool_bg.init(pool_size, &rng_bg).await {
+                                    Ok(()) => {
+                                        startup_tracker_bg.set_me_last_error(None).await;
+                                        startup_tracker_bg
+                                            .complete_component(
+                                                COMPONENT_ME_POOL_INIT_STAGE1,
+                                                Some("ME pool initialized".to_string()),
+                                            )
+                                            .await;
+                                        startup_tracker_bg
+                                            .set_me_status(StartupMeStatus::Ready, "ready")
+                                            .await;
+                                        info!(
+                                            attempt = init_attempt,
+                                            "Middle-End pool initialized successfully"
+                                        );
+
+                                        let pool_health = pool_bg.clone();
+                                        let rng_health = rng_bg.clone();
+                                        let min_conns = pool_size;
+                                        tokio::spawn(async move {
+                                            crate::transport::middle_proxy::me_health_monitor(
+                                                pool_health,
+                                                rng_health,
+                                                min_conns,
+                                            )
+                                            .await;
+                                        });
+                                        break;
+                                    }
+                                    Err(e) => {
+                                        startup_tracker_bg.set_me_last_error(Some(e.to_string())).await;
+                                        if init_attempt >= me_init_warn_after_attempts {
+                                            warn!(
+                                                error = %e,
+                                                attempt = init_attempt,
+                                                retry_limit = %retry_limit,
+                                                retry_in_secs = 2,
+                                                "ME pool is not ready yet; retrying background initialization"
+                                            );
+                                        } else {
+                                            info!(
+                                                error = %e,
+                                                attempt = init_attempt,
+                                                retry_limit = %retry_limit,
+                                                retry_in_secs = 2,
+                                                "ME pool startup warmup: retrying background initialization"
+                                            );
+                                        }
+                                        pool_bg.reset_stun_state();
+                                        tokio::time::sleep(Duration::from_secs(2)).await;
+                                    }
+                                }
+                            }
+                        });
+                    });
+                    startup_tracker
+                        .set_me_status(StartupMeStatus::Initializing, "background_init")
+                        .await;
+                    info!(
+                        startup_grace_secs = 80,
+                        "ME pool initialization continues in background; startup continues with conditional Direct fallback"
+                    );
+                    Some(pool)
+                } else {
+                    let mut init_attempt: u32 = 0;
+                    loop {
+                        init_attempt = init_attempt.saturating_add(1);
+                        startup_tracker.set_me_init_attempt(init_attempt).await;
+                        match pool.init(pool_size, &rng).await {
+                            Ok(()) => {
+                                startup_tracker.set_me_last_error(None).await;
+                                startup_tracker
+                                    .complete_component(
+                                        COMPONENT_ME_POOL_INIT_STAGE1,
+                                        Some("ME pool initialized".to_string()),
+                                    )
+                                    .await;
+                                startup_tracker
+                                    .set_me_status(StartupMeStatus::Ready, "ready")
+                                    .await;
+                                info!(
+                                    attempt = init_attempt,
+                                    "Middle-End pool initialized successfully"
+                                );
+
+                                let pool_clone = pool.clone();
+                                let rng_clone = rng.clone();
+                                let min_conns = pool_size;
+                                tokio::spawn(async move {
+                                    crate::transport::middle_proxy::me_health_monitor(
+                                        pool_clone, rng_clone, min_conns,
+                                    )
+                                    .await;
+                                });
+
+                                break Some(pool);
+                            }
+                            Err(e) => {
+                                startup_tracker.set_me_last_error(Some(e.to_string())).await;
+                                let retries_limited = me_init_retry_attempts > 0;
+                                if retries_limited && init_attempt >= me_init_retry_attempts {
+                                    startup_tracker
+                                        .fail_component(
+                                            COMPONENT_ME_POOL_INIT_STAGE1,
+                                            Some("ME init retry budget exhausted".to_string()),
+                                        )
+                                        .await;
+                                    startup_tracker
+                                        .set_me_status(StartupMeStatus::Failed, "failed")
+                                        .await;
+                                    error!(
+                                        error = %e,
+                                        attempt = init_attempt,
+                                        retry_limit = me_init_retry_attempts,
+                                        "ME pool init retries exhausted; startup cannot continue in middle-proxy mode"
+                                    );
+                                    break None;
+                                }
+
+                                let retry_limit = if me_init_retry_attempts == 0 {
+                                    String::from("unlimited")
+                                } else {
+                                    me_init_retry_attempts.to_string()
+                                };
+                                if init_attempt >= me_init_warn_after_attempts {
+                                    warn!(
+                                        error = %e,
+                                        attempt = init_attempt,
+                                        retry_limit = retry_limit,
+                                        me2dc_fallback = me2dc_fallback,
+                                        retry_in_secs = 2,
+                                        "ME pool is not ready yet; retrying startup initialization"
+                                    );
+                                } else {
+                                    info!(
+                                        error = %e,
+                                        attempt = init_attempt,
+                                        retry_limit = retry_limit,
+                                        me2dc_fallback = me2dc_fallback,
+                                        retry_in_secs = 2,
+                                        "ME pool startup warmup: retrying initialization"
+                                    );
+                                }
+                                pool.reset_stun_state();
+                                tokio::time::sleep(Duration::from_secs(2)).await;
+                            }
+                        }
+                    }
+                }
+            } else {
+                startup_tracker
+                    .skip_component(
+                        COMPONENT_ME_POOL_CONSTRUCT,
+                        Some("ME configs are incomplete".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .fail_component(
+                        COMPONENT_ME_POOL_INIT_STAGE1,
+                        Some("ME configs are incomplete".to_string()),
+                    )
+                    .await;
+                startup_tracker
+                    .set_me_status(StartupMeStatus::Failed, "failed")
+                    .await;
+                None
+            }
+        }
+        None => {
+            startup_tracker
+                .fail_component(
+                    COMPONENT_ME_SECRET_FETCH,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .skip_component(
+                    COMPONENT_ME_PROXY_CONFIG_V4,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .skip_component(
+                    COMPONENT_ME_PROXY_CONFIG_V6,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .skip_component(
+                    COMPONENT_ME_POOL_CONSTRUCT,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .fail_component(
+                    COMPONENT_ME_POOL_INIT_STAGE1,
+                    Some("proxy-secret unavailable".to_string()),
+                )
+                .await;
+            startup_tracker
+                .set_me_status(StartupMeStatus::Failed, "failed")
+                .await;
+            None
+        }
+    }
+}

src/maestro/mod.rs

@@ -0,0 +1,606 @@
+//! telemt — Telegram MTProto Proxy
+
+#![allow(unused_assignments)]
+
+// Runtime orchestration modules.
+// - helpers: CLI and shared startup/runtime helper routines.
+// - tls_bootstrap: TLS front cache bootstrap and refresh tasks.
+// - me_startup: Middle-End secret/config fetch and pool initialization.
+// - connectivity: startup ME/DC connectivity diagnostics.
+// - runtime_tasks: hot-reload and background task orchestration.
+// - admission: conditional-cast gate and route mode switching.
+// - listeners: TCP/Unix listener bind and accept-loop orchestration.
+// - shutdown: graceful shutdown sequence and uptime logging.
+mod helpers;
+mod admission;
+mod connectivity;
+mod listeners;
+mod me_startup;
+mod runtime_tasks;
+mod shutdown;
+mod tls_bootstrap;
+
+use std::net::{IpAddr, SocketAddr};
+use std::sync::Arc;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use tokio::sync::{RwLock, Semaphore, watch};
+use tracing::{error, info, warn};
+use tracing_subscriber::{EnvFilter, fmt, prelude::*, reload};
+
+use crate::api;
+use crate::config::{LogLevel, ProxyConfig};
+use crate::crypto::SecureRandom;
+use crate::ip_tracker::UserIpTracker;
+use crate::network::probe::{decide_network_capabilities, log_probe_result, run_probe};
+use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
+use crate::stats::beobachten::BeobachtenStore;
+use crate::stats::telemetry::TelemetryPolicy;
+use crate::stats::{ReplayChecker, Stats};
+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,
+};
+use crate::stream::BufferPool;
+use crate::transport::middle_proxy::MePool;
+use crate::transport::UpstreamManager;
+use helpers::{parse_cli, resolve_runtime_config_path};
+
+/// Runs the full telemt runtime startup pipeline and blocks until shutdown.
+pub async fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    let process_started_at = Instant::now();
+    let process_started_at_epoch_secs = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+    let startup_tracker = Arc::new(StartupTracker::new(process_started_at_epoch_secs));
+    startup_tracker
+        .start_component(COMPONENT_CONFIG_LOAD, Some("load and validate config".to_string()))
+        .await;
+    let (config_path_cli, data_path, cli_silent, cli_log_level) = parse_cli();
+    let startup_cwd = match std::env::current_dir() {
+        Ok(cwd) => cwd,
+        Err(e) => {
+            eprintln!("[telemt] Can't read current_dir: {}", e);
+            std::process::exit(1);
+        }
+    };
+    let config_path = resolve_runtime_config_path(&config_path_cli, &startup_cwd);
+
+    let mut config = match ProxyConfig::load(&config_path) {
+        Ok(c) => c,
+        Err(e) => {
+            if config_path.exists() {
+                eprintln!("[telemt] Error: {}", e);
+                std::process::exit(1);
+            } else {
+                let default = ProxyConfig::default();
+                std::fs::write(&config_path, toml::to_string_pretty(&default).unwrap()).unwrap();
+                eprintln!("[telemt] Created default config at {}", config_path.display());
+                default
+            }
+        }
+    };
+
+    if let Err(e) = config.validate() {
+        eprintln!("[telemt] Invalid config: {}", e);
+        std::process::exit(1);
+    }
+
+    if let Some(p) = data_path {
+        config.general.data_path = Some(p);
+    }
+
+    if let Some(ref data_path) = config.general.data_path {
+        if !data_path.is_absolute() {
+            eprintln!("[telemt] data_path must be absolute: {}", data_path.display());
+            std::process::exit(1);
+        }
+
+        if data_path.exists() {
+            if !data_path.is_dir() {
+                eprintln!("[telemt] data_path exists but is not a directory: {}", data_path.display());
+                std::process::exit(1);
+            }
+        } else {
+            if let Err(e) = std::fs::create_dir_all(data_path) {
+                eprintln!("[telemt] Can't create data_path {}: {}", data_path.display(), e);
+                std::process::exit(1);
+            }
+        }
+
+        if let Err(e) = std::env::set_current_dir(data_path) {
+            eprintln!("[telemt] Can't use data_path {}: {}", data_path.display(), e);
+            std::process::exit(1);
+        }
+    }
+
+    if let Err(e) = crate::network::dns_overrides::install_entries(&config.network.dns_overrides) {
+        eprintln!("[telemt] Invalid network.dns_overrides: {}", e);
+        std::process::exit(1);
+    }
+    startup_tracker
+        .complete_component(COMPONENT_CONFIG_LOAD, Some("config is ready".to_string()))
+        .await;
+
+    let has_rust_log = std::env::var("RUST_LOG").is_ok();
+    let effective_log_level = if cli_silent {
+        LogLevel::Silent
+    } else if let Some(ref s) = cli_log_level {
+        LogLevel::from_str_loose(s)
+    } else {
+        config.general.log_level.clone()
+    };
+
+    let (filter_layer, filter_handle) = reload::Layer::new(EnvFilter::new("info"));
+    startup_tracker
+        .start_component(COMPONENT_TRACING_INIT, Some("initialize tracing subscriber".to_string()))
+        .await;
+
+    // Configure color output based on config
+    let fmt_layer = if config.general.disable_colors {
+        fmt::Layer::default().with_ansi(false)
+    } else {
+        fmt::Layer::default().with_ansi(true)
+    };
+
+    tracing_subscriber::registry()
+        .with(filter_layer)
+        .with(fmt_layer)
+        .init();
+    startup_tracker
+        .complete_component(COMPONENT_TRACING_INIT, Some("tracing initialized".to_string()))
+        .await;
+
+    info!("Telemt MTProxy v{}", env!("CARGO_PKG_VERSION"));
+    info!("Log level: {}", effective_log_level);
+    if config.general.disable_colors {
+        info!("Colors: disabled");
+    }
+    info!(
+        "Modes: classic={} secure={} tls={}",
+        config.general.modes.classic, config.general.modes.secure, config.general.modes.tls
+    );
+    if config.general.modes.classic {
+        warn!("Classic mode is vulnerable to DPI detection; enable only for legacy clients");
+    }
+    info!("TLS domain: {}", config.censorship.tls_domain);
+    if let Some(ref sock) = config.censorship.mask_unix_sock {
+        info!("Mask: {} -> unix:{}", config.censorship.mask, sock);
+        if !std::path::Path::new(sock).exists() {
+            warn!(
+                "Unix socket '{}' does not exist yet. Masking will fail until it appears.",
+                sock
+            );
+        }
+    } else {
+        info!(
+            "Mask: {} -> {}:{}",
+            config.censorship.mask,
+            config
+                .censorship
+                .mask_host
+                .as_deref()
+                .unwrap_or(&config.censorship.tls_domain),
+            config.censorship.mask_port
+        );
+    }
+
+    if config.censorship.tls_domain == "www.google.com" {
+        warn!("Using default tls_domain. Consider setting a custom domain.");
+    }
+
+    let stats = Arc::new(Stats::new());
+    stats.apply_telemetry_policy(TelemetryPolicy::from_config(&config.general.telemetry));
+
+    let upstream_manager = Arc::new(UpstreamManager::new(
+        config.upstreams.clone(),
+        config.general.upstream_connect_retry_attempts,
+        config.general.upstream_connect_retry_backoff_ms,
+        config.general.upstream_connect_budget_ms,
+        config.general.upstream_unhealthy_fail_threshold,
+        config.general.upstream_connect_failfast_hard_errors,
+        stats.clone(),
+    ));
+    let ip_tracker = Arc::new(UserIpTracker::new());
+    ip_tracker
+        .load_limits(
+            config.access.user_max_unique_ips_global_each,
+            &config.access.user_max_unique_ips,
+        )
+        .await;
+    ip_tracker
+        .set_limit_policy(
+            config.access.user_max_unique_ips_mode,
+            config.access.user_max_unique_ips_window_secs,
+        )
+        .await;
+    if config.access.user_max_unique_ips_global_each > 0 || !config.access.user_max_unique_ips.is_empty()
+    {
+        info!(
+            global_each_limit = config.access.user_max_unique_ips_global_each,
+            explicit_user_limits = config.access.user_max_unique_ips.len(),
+            "User unique IP limits configured"
+        );
+    }
+    if !config.network.dns_overrides.is_empty() {
+        info!(
+            "Runtime DNS overrides configured: {} entries",
+            config.network.dns_overrides.len()
+        );
+    }
+
+    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 (admission_tx, admission_rx) = watch::channel(initial_admission_open);
+    let initial_route_mode = if config.general.use_middle_proxy {
+        RelayRouteMode::Middle
+    } else {
+        RelayRouteMode::Direct
+    };
+    let route_runtime = Arc::new(RouteRuntimeController::new(initial_route_mode));
+    let api_me_pool = Arc::new(RwLock::new(None::<Arc<MePool>>));
+    startup_tracker
+        .start_component(COMPONENT_API_BOOTSTRAP, Some("spawn API listener task".to_string()))
+        .await;
+
+    if config.server.api.enabled {
+        let listen = match config.server.api.listen.parse::<SocketAddr>() {
+            Ok(listen) => listen,
+            Err(error) => {
+                warn!(
+                    error = %error,
+                    listen = %config.server.api.listen,
+                    "Invalid server.api.listen; API is disabled"
+                );
+                SocketAddr::from(([127, 0, 0, 1], 0))
+            }
+        };
+        if listen.port() != 0 {
+            let stats_api = stats.clone();
+            let ip_tracker_api = ip_tracker.clone();
+            let me_pool_api = api_me_pool.clone();
+            let upstream_manager_api = upstream_manager.clone();
+            let route_runtime_api = route_runtime.clone();
+            let config_rx_api = api_config_rx.clone();
+            let admission_rx_api = admission_rx.clone();
+            let config_path_api = config_path.clone();
+            let startup_tracker_api = startup_tracker.clone();
+            let detected_ips_rx_api = detected_ips_rx.clone();
+            tokio::spawn(async move {
+                api::serve(
+                    listen,
+                    stats_api,
+                    ip_tracker_api,
+                    me_pool_api,
+                    route_runtime_api,
+                    upstream_manager_api,
+                    config_rx_api,
+                    admission_rx_api,
+                    config_path_api,
+                    detected_ips_rx_api,
+                    process_started_at_epoch_secs,
+                    startup_tracker_api,
+                )
+                .await;
+            });
+            startup_tracker
+                .complete_component(
+                    COMPONENT_API_BOOTSTRAP,
+                    Some(format!("api task spawned on {}", listen)),
+                )
+                .await;
+        } else {
+            startup_tracker
+                .skip_component(
+                    COMPONENT_API_BOOTSTRAP,
+                    Some("server.api.listen has zero port".to_string()),
+                )
+                .await;
+        }
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_API_BOOTSTRAP,
+                Some("server.api.enabled is false".to_string()),
+            )
+            .await;
+    }
+
+    let mut tls_domains = Vec::with_capacity(1 + config.censorship.tls_domains.len());
+    tls_domains.push(config.censorship.tls_domain.clone());
+    for d in &config.censorship.tls_domains {
+        if !tls_domains.contains(d) {
+            tls_domains.push(d.clone());
+        }
+    }
+
+    let tls_cache = tls_bootstrap::bootstrap_tls_front(
+        &config,
+        &tls_domains,
+        upstream_manager.clone(),
+        &startup_tracker,
+    )
+    .await;
+
+    startup_tracker
+        .start_component(COMPONENT_NETWORK_PROBE, Some("probe network capabilities".to_string()))
+        .await;
+    let probe = run_probe(
+        &config.network,
+        &config.upstreams,
+        config.general.middle_proxy_nat_probe,
+        config.general.stun_nat_probe_concurrency,
+    )
+    .await?;
+    detected_ips_tx.send_replace((
+        probe.detected_ipv4.map(IpAddr::V4),
+        probe.detected_ipv6.map(IpAddr::V6),
+    ));
+    let decision = decide_network_capabilities(
+        &config.network,
+        &probe,
+        config.general.middle_proxy_nat_ip,
+    );
+    log_probe_result(&probe, &decision);
+    startup_tracker
+        .complete_component(
+            COMPONENT_NETWORK_PROBE,
+            Some("network capabilities determined".to_string()),
+        )
+        .await;
+
+    let prefer_ipv6 = decision.prefer_ipv6();
+    let mut use_middle_proxy = config.general.use_middle_proxy;
+    let beobachten = Arc::new(BeobachtenStore::new());
+    let rng = Arc::new(SecureRandom::new());
+
+    // Connection concurrency limit (0 = unlimited)
+    let max_connections_limit = if config.server.max_connections == 0 {
+        Semaphore::MAX_PERMITS
+    } else {
+        config.server.max_connections as usize
+    };
+    let max_connections = Arc::new(Semaphore::new(max_connections_limit));
+
+    let me2dc_fallback = config.general.me2dc_fallback;
+    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;
+        } else {
+            warn!(
+                "No usable IP family for Middle Proxy detected; me2dc_fallback=false, ME init retries stay active"
+            );
+        }
+    }
+
+    if use_middle_proxy {
+        startup_tracker
+            .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_SECRET_FETCH)
+            .await;
+        startup_tracker
+            .start_component(
+                COMPONENT_ME_SECRET_FETCH,
+                Some("fetch proxy-secret from source/cache".to_string()),
+            )
+            .await;
+        startup_tracker
+            .set_me_retry_limit(if !me2dc_fallback || me_init_retry_attempts == 0 {
+                "unlimited".to_string()
+            } else {
+                me_init_retry_attempts.to_string()
+            })
+            .await;
+    } else {
+        startup_tracker
+            .set_me_status(StartupMeStatus::Skipped, "skipped")
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_SECRET_FETCH,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_PROXY_CONFIG_V4,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_PROXY_CONFIG_V6,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_POOL_CONSTRUCT,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_POOL_INIT_STAGE1,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .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;
+
+    // If ME failed to initialize, force direct-only mode.
+    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");
+    } else {
+        let _ = use_middle_proxy;
+        use_middle_proxy = false;
+        // Make runtime config reflect direct-only mode for handlers.
+        config.general.use_middle_proxy = false;
+        startup_tracker
+            .set_transport_mode("direct")
+            .await;
+        startup_tracker
+            .set_degraded(true)
+            .await;
+        if me2dc_fallback {
+            startup_tracker
+                .set_me_status(StartupMeStatus::Failed, "fallback_to_direct")
+                .await;
+        } else {
+            startup_tracker
+                .set_me_status(StartupMeStatus::Skipped, "skipped")
+                .await;
+        }
+        info!("Transport: Direct DC - TCP - standard DC-over-TCP");
+    }
+
+    // Freeze config after possible fallback decision
+    let config = Arc::new(config);
+
+    let replay_checker = Arc::new(ReplayChecker::new(
+        config.access.replay_check_len,
+        Duration::from_secs(config.access.replay_window_secs),
+    ));
+
+    let buffer_pool = Arc::new(BufferPool::with_config(16 * 1024, 4096));
+
+    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,
+        &config_path,
+        &probe,
+        prefer_ipv6,
+        decision.ipv4_dc,
+        decision.ipv6_dc,
+        &startup_tracker,
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        me_pool.clone(),
+        rng.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        api_config_tx.clone(),
+        me_pool.clone(),
+    )
+    .await;
+    let config_rx = runtime_watches.config_rx;
+    let log_level_rx = runtime_watches.log_level_rx;
+    let detected_ip_v4 = runtime_watches.detected_ip_v4;
+    let detected_ip_v6 = runtime_watches.detected_ip_v6;
+
+    admission::configure_admission_gate(
+        &config,
+        me_pool.clone(),
+        route_runtime.clone(),
+        &admission_tx,
+        config_rx.clone(),
+    )
+    .await;
+    let _admission_tx_hold = admission_tx;
+
+    let bound = listeners::bind_listeners(
+        &config,
+        decision.ipv4_dc,
+        decision.ipv6_dc,
+        detected_ip_v4,
+        detected_ip_v6,
+        &startup_tracker,
+        config_rx.clone(),
+        admission_rx.clone(),
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        buffer_pool.clone(),
+        rng.clone(),
+        me_pool.clone(),
+        route_runtime.clone(),
+        tls_cache.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        max_connections.clone(),
+    )
+    .await?;
+    let listeners = bound.listeners;
+    let has_unix_listener = bound.has_unix_listener;
+
+    if listeners.is_empty() && !has_unix_listener {
+        error!("No listeners. Exiting.");
+        std::process::exit(1);
+    }
+
+    runtime_tasks::apply_runtime_log_filter(
+        has_rust_log,
+        &effective_log_level,
+        filter_handle,
+        log_level_rx,
+    )
+    .await;
+
+    runtime_tasks::spawn_metrics_if_configured(
+        &config,
+        &startup_tracker,
+        stats.clone(),
+        beobachten.clone(),
+        ip_tracker.clone(),
+        config_rx.clone(),
+    )
+    .await;
+
+    runtime_tasks::mark_runtime_ready(&startup_tracker).await;
+
+    listeners::spawn_tcp_accept_loops(
+        listeners,
+        config_rx.clone(),
+        admission_rx.clone(),
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        buffer_pool.clone(),
+        rng.clone(),
+        me_pool.clone(),
+        route_runtime.clone(),
+        tls_cache.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        max_connections.clone(),
+    );
+
+    shutdown::wait_for_shutdown(process_started_at, me_pool).await;
+
+    Ok(())
+}

src/maestro/runtime_tasks.rs

@@ -0,0 +1,329 @@
+use std::net::IpAddr;
+use std::path::Path;
+use std::sync::Arc;
+
+use tokio::sync::{mpsc, watch};
+use tracing::{debug, warn};
+use tracing_subscriber::reload;
+use tracing_subscriber::EnvFilter;
+
+use crate::config::{LogLevel, ProxyConfig};
+use crate::config::hot_reload::spawn_config_watcher;
+use crate::crypto::SecureRandom;
+use crate::ip_tracker::UserIpTracker;
+use crate::metrics;
+use crate::network::probe::NetworkProbe;
+use crate::startup::{COMPONENT_CONFIG_WATCHER_START, COMPONENT_METRICS_START, COMPONENT_RUNTIME_READY, StartupTracker};
+use crate::stats::beobachten::BeobachtenStore;
+use crate::stats::telemetry::TelemetryPolicy;
+use crate::stats::{ReplayChecker, Stats};
+use crate::transport::middle_proxy::{MePool, MeReinitTrigger};
+use crate::transport::UpstreamManager;
+
+use super::helpers::write_beobachten_snapshot;
+
+pub(crate) struct RuntimeWatches {
+    pub(crate) config_rx: watch::Receiver<Arc<ProxyConfig>>,
+    pub(crate) log_level_rx: watch::Receiver<LogLevel>,
+    pub(crate) detected_ip_v4: Option<IpAddr>,
+    pub(crate) detected_ip_v6: Option<IpAddr>,
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn spawn_runtime_tasks(
+    config: &Arc<ProxyConfig>,
+    config_path: &Path,
+    probe: &NetworkProbe,
+    prefer_ipv6: bool,
+    decision_ipv4_dc: bool,
+    decision_ipv6_dc: bool,
+    startup_tracker: &Arc<StartupTracker>,
+    stats: Arc<Stats>,
+    upstream_manager: Arc<UpstreamManager>,
+    replay_checker: Arc<ReplayChecker>,
+    me_pool: Option<Arc<MePool>>,
+    rng: Arc<SecureRandom>,
+    ip_tracker: Arc<UserIpTracker>,
+    beobachten: Arc<BeobachtenStore>,
+    api_config_tx: watch::Sender<Arc<ProxyConfig>>,
+    me_pool_for_policy: Option<Arc<MePool>>,
+) -> RuntimeWatches {
+    let um_clone = upstream_manager.clone();
+    let dc_overrides_for_health = config.dc_overrides.clone();
+    tokio::spawn(async move {
+        um_clone
+            .run_health_checks(
+                prefer_ipv6,
+                decision_ipv4_dc,
+                decision_ipv6_dc,
+                dc_overrides_for_health,
+            )
+            .await;
+    });
+
+    let rc_clone = replay_checker.clone();
+    tokio::spawn(async move {
+        rc_clone.run_periodic_cleanup().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!(
+        "Detected IPs: v4={:?} v6={:?}",
+        detected_ip_v4, detected_ip_v6
+    );
+
+    startup_tracker
+        .start_component(
+            COMPONENT_CONFIG_WATCHER_START,
+            Some("spawn config hot-reload watcher".to_string()),
+        )
+        .await;
+    let (config_rx, log_level_rx): (
+        watch::Receiver<Arc<ProxyConfig>>,
+        watch::Receiver<LogLevel>,
+    ) = spawn_config_watcher(
+        config_path.to_path_buf(),
+        config.clone(),
+        detected_ip_v4,
+        detected_ip_v6,
+    );
+    startup_tracker
+        .complete_component(
+            COMPONENT_CONFIG_WATCHER_START,
+            Some("config hot-reload watcher started".to_string()),
+        )
+        .await;
+    let mut config_rx_api_bridge = config_rx.clone();
+    let api_config_tx_bridge = api_config_tx.clone();
+    tokio::spawn(async move {
+        loop {
+            if config_rx_api_bridge.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_api_bridge.borrow_and_update().clone();
+            api_config_tx_bridge.send_replace(cfg);
+        }
+    });
+
+    let stats_policy = stats.clone();
+    let mut config_rx_policy = config_rx.clone();
+    tokio::spawn(async move {
+        loop {
+            if config_rx_policy.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_policy.borrow_and_update().clone();
+            stats_policy.apply_telemetry_policy(TelemetryPolicy::from_config(&cfg.general.telemetry));
+            if let Some(pool) = &me_pool_for_policy {
+                pool.update_runtime_transport_policy(
+                    cfg.general.me_socks_kdf_policy,
+                    cfg.general.me_route_backpressure_base_timeout_ms,
+                    cfg.general.me_route_backpressure_high_timeout_ms,
+                    cfg.general.me_route_backpressure_high_watermark_pct,
+                    cfg.general.me_reader_route_data_wait_ms,
+                );
+            }
+        }
+    });
+
+    let ip_tracker_policy = ip_tracker.clone();
+    let mut config_rx_ip_limits = config_rx.clone();
+    tokio::spawn(async move {
+        let mut prev_limits = config_rx_ip_limits.borrow().access.user_max_unique_ips.clone();
+        let mut prev_global_each = config_rx_ip_limits
+            .borrow()
+            .access
+            .user_max_unique_ips_global_each;
+        let mut prev_mode = config_rx_ip_limits.borrow().access.user_max_unique_ips_mode;
+        let mut prev_window = config_rx_ip_limits
+            .borrow()
+            .access
+            .user_max_unique_ips_window_secs;
+
+        loop {
+            if config_rx_ip_limits.changed().await.is_err() {
+                break;
+            }
+            let cfg = config_rx_ip_limits.borrow_and_update().clone();
+
+            if prev_limits != cfg.access.user_max_unique_ips
+                || prev_global_each != cfg.access.user_max_unique_ips_global_each
+            {
+                ip_tracker_policy
+                    .load_limits(
+                        cfg.access.user_max_unique_ips_global_each,
+                        &cfg.access.user_max_unique_ips,
+                    )
+                    .await;
+                prev_limits = cfg.access.user_max_unique_ips.clone();
+                prev_global_each = cfg.access.user_max_unique_ips_global_each;
+            }
+
+            if prev_mode != cfg.access.user_max_unique_ips_mode
+                || prev_window != cfg.access.user_max_unique_ips_window_secs
+            {
+                ip_tracker_policy
+                    .set_limit_policy(
+                        cfg.access.user_max_unique_ips_mode,
+                        cfg.access.user_max_unique_ips_window_secs,
+                    )
+                    .await;
+                prev_mode = cfg.access.user_max_unique_ips_mode;
+                prev_window = cfg.access.user_max_unique_ips_window_secs;
+            }
+        }
+    });
+
+    let beobachten_writer = beobachten.clone();
+    let config_rx_beobachten = config_rx.clone();
+    tokio::spawn(async move {
+        loop {
+            let cfg = config_rx_beobachten.borrow().clone();
+            let sleep_secs = cfg.general.beobachten_flush_secs.max(1);
+
+            if cfg.general.beobachten {
+                let ttl = std::time::Duration::from_secs(cfg.general.beobachten_minutes.saturating_mul(60));
+                let path = cfg.general.beobachten_file.clone();
+                let snapshot = beobachten_writer.snapshot_text(ttl);
+                if let Err(e) = write_beobachten_snapshot(&path, &snapshot).await {
+                    warn!(error = %e, path = %path, "Failed to flush beobachten snapshot");
+                }
+            }
+
+            tokio::time::sleep(std::time::Duration::from_secs(sleep_secs)).await;
+        }
+    });
+
+    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;
+        });
+    }
+
+    RuntimeWatches {
+        config_rx,
+        log_level_rx,
+        detected_ip_v4,
+        detected_ip_v6,
+    }
+}
+
+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())
+    };
+    filter_handle
+        .reload(runtime_filter)
+        .expect("Failed to switch log filter");
+
+    tokio::spawn(async move {
+        loop {
+            if log_level_rx.changed().await.is_err() {
+                break;
+            }
+            let level = log_level_rx.borrow_and_update().clone();
+            let new_filter = tracing_subscriber::EnvFilter::new(level.to_filter_str());
+            if let Err(e) = filter_handle.reload(new_filter) {
+                tracing::error!("config reload: failed to update log filter: {}", e);
+            }
+        }
+    });
+}
+
+pub(crate) async fn spawn_metrics_if_configured(
+    config: &Arc<ProxyConfig>,
+    startup_tracker: &Arc<StartupTracker>,
+    stats: Arc<Stats>,
+    beobachten: Arc<BeobachtenStore>,
+    ip_tracker: Arc<UserIpTracker>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+) {
+    if let Some(port) = config.server.metrics_port {
+        startup_tracker
+            .start_component(
+                COMPONENT_METRICS_START,
+                Some(format!("spawn metrics endpoint on {}", port)),
+            )
+            .await;
+        let stats = stats.clone();
+        let beobachten = beobachten.clone();
+        let config_rx_metrics = config_rx.clone();
+        let ip_tracker_metrics = ip_tracker.clone();
+        let whitelist = config.server.metrics_whitelist.clone();
+        tokio::spawn(async move {
+            metrics::serve(
+                port,
+                stats,
+                beobachten,
+                ip_tracker_metrics,
+                config_rx_metrics,
+                whitelist,
+            )
+            .await;
+        });
+        startup_tracker
+            .complete_component(
+                COMPONENT_METRICS_START,
+                Some("metrics task spawned".to_string()),
+            )
+            .await;
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_METRICS_START,
+                Some("server.metrics_port is not configured".to_string()),
+            )
+            .await;
+    }
+}
+
+pub(crate) async fn mark_runtime_ready(startup_tracker: &Arc<StartupTracker>) {
+    startup_tracker
+        .complete_component(
+            COMPONENT_RUNTIME_READY,
+            Some("startup pipeline is fully initialized".to_string()),
+        )
+        .await;
+    startup_tracker.mark_ready().await;
+}

src/maestro/shutdown.rs

@@ -0,0 +1,42 @@
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::signal;
+use tracing::{error, info, warn};
+
+use crate::transport::middle_proxy::MePool;
+
+use super::helpers::{format_uptime, unit_label};
+
+pub(crate) async fn wait_for_shutdown(process_started_at: Instant, me_pool: Option<Arc<MePool>>) {
+    match signal::ctrl_c().await {
+        Ok(()) => {
+            let shutdown_started_at = Instant::now();
+            info!("Shutting down...");
+            let uptime_secs = process_started_at.elapsed().as_secs();
+            info!("Uptime: {}", format_uptime(uptime_secs));
+            if let Some(pool) = &me_pool {
+                match tokio::time::timeout(Duration::from_secs(2), pool.shutdown_send_close_conn_all())
+                    .await
+                {
+                    Ok(total) => {
+                        info!(
+                            close_conn_sent = total,
+                            "ME shutdown: RPC_CLOSE_CONN broadcast completed"
+                        );
+                    }
+                    Err(_) => {
+                        warn!("ME shutdown: RPC_CLOSE_CONN broadcast timed out");
+                    }
+                }
+            }
+            let shutdown_secs = shutdown_started_at.elapsed().as_secs();
+            info!(
+                "Shutdown completed successfully in {} {}.",
+                shutdown_secs,
+                unit_label(shutdown_secs, "second", "seconds")
+            );
+        }
+        Err(e) => error!("Signal error: {}", e),
+    }
+}

src/maestro/tls_bootstrap.rs

@@ -0,0 +1,165 @@
+use std::sync::Arc;
+use std::time::Duration;
+
+use rand::Rng;
+use tracing::warn;
+
+use crate::config::ProxyConfig;
+use crate::startup::{COMPONENT_TLS_FRONT_BOOTSTRAP, StartupTracker};
+use crate::tls_front::TlsFrontCache;
+use crate::transport::UpstreamManager;
+
+pub(crate) async fn bootstrap_tls_front(
+    config: &ProxyConfig,
+    tls_domains: &[String],
+    upstream_manager: Arc<UpstreamManager>,
+    startup_tracker: &Arc<StartupTracker>,
+) -> Option<Arc<TlsFrontCache>> {
+    startup_tracker
+        .start_component(
+            COMPONENT_TLS_FRONT_BOOTSTRAP,
+            Some("initialize TLS front cache/bootstrap tasks".to_string()),
+        )
+        .await;
+
+    let tls_cache: Option<Arc<TlsFrontCache>> = if config.censorship.tls_emulation {
+        let cache = Arc::new(TlsFrontCache::new(
+            tls_domains,
+            config.censorship.fake_cert_len,
+            &config.censorship.tls_front_dir,
+        ));
+        cache.load_from_disk().await;
+
+        let port = config.censorship.mask_port;
+        let proxy_protocol = config.censorship.mask_proxy_protocol;
+        let mask_host = config
+            .censorship
+            .mask_host
+            .clone()
+            .unwrap_or_else(|| config.censorship.tls_domain.clone());
+        let mask_unix_sock = config.censorship.mask_unix_sock.clone();
+        let fetch_timeout = Duration::from_secs(5);
+
+        let cache_initial = cache.clone();
+        let domains_initial = tls_domains.to_vec();
+        let host_initial = mask_host.clone();
+        let unix_sock_initial = mask_unix_sock.clone();
+        let upstream_initial = upstream_manager.clone();
+        tokio::spawn(async move {
+            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 unix_sock_domain = unix_sock_initial.clone();
+                let upstream_domain = upstream_initial.clone();
+                join.spawn(async move {
+                    match crate::tls_front::fetcher::fetch_real_tls(
+                        &host_domain,
+                        port,
+                        &domain,
+                        fetch_timeout,
+                        Some(upstream_domain),
+                        proxy_protocol,
+                        unix_sock_domain.as_deref(),
+                    )
+                    .await
+                    {
+                        Ok(res) => cache_domain.update_from_fetch(&domain, res).await,
+                        Err(e) => {
+                            warn!(domain = %domain, error = %e, "TLS emulation initial fetch failed")
+                        }
+                    }
+                });
+            }
+            while let Some(res) = join.join_next().await {
+                if let Err(e) = res {
+                    warn!(error = %e, "TLS emulation initial fetch task join failed");
+                }
+            }
+        });
+
+        let cache_timeout = cache.clone();
+        let domains_timeout = tls_domains.to_vec();
+        let fake_cert_len = config.censorship.fake_cert_len;
+        tokio::spawn(async move {
+            tokio::time::sleep(fetch_timeout).await;
+            for domain in domains_timeout {
+                let cached = cache_timeout.get(&domain).await;
+                if cached.domain == "default" {
+                    warn!(
+                        domain = %domain,
+                        timeout_secs = fetch_timeout.as_secs(),
+                        fake_cert_len,
+                        "TLS-front fetch not ready within timeout; using cache/default fake cert fallback"
+                    );
+                }
+            }
+        });
+
+        let cache_refresh = cache.clone();
+        let domains_refresh = tls_domains.to_vec();
+        let host_refresh = mask_host.clone();
+        let unix_sock_refresh = mask_unix_sock.clone();
+        let upstream_refresh = upstream_manager.clone();
+        tokio::spawn(async move {
+            loop {
+                let base_secs = rand::rng().random_range(4 * 3600..=6 * 3600);
+                let jitter_secs = rand::rng().random_range(0..=7200);
+                tokio::time::sleep(Duration::from_secs(base_secs + jitter_secs)).await;
+
+                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 unix_sock_domain = unix_sock_refresh.clone();
+                    let upstream_domain = upstream_refresh.clone();
+                    join.spawn(async move {
+                        match crate::tls_front::fetcher::fetch_real_tls(
+                            &host_domain,
+                            port,
+                            &domain,
+                            fetch_timeout,
+                            Some(upstream_domain),
+                            proxy_protocol,
+                            unix_sock_domain.as_deref(),
+                        )
+                        .await
+                        {
+                            Ok(res) => cache_domain.update_from_fetch(&domain, res).await,
+                            Err(e) => {
+                                warn!(domain = %domain, error = %e, "TLS emulation refresh failed")
+                            }
+                        }
+                    });
+                }
+
+                while let Some(res) = join.join_next().await {
+                    if let Err(e) = res {
+                        warn!(error = %e, "TLS emulation refresh task join failed");
+                    }
+                }
+            }
+        });
+
+        Some(cache)
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_TLS_FRONT_BOOTSTRAP,
+                Some("censorship.tls_emulation is false".to_string()),
+            )
+            .await;
+        None
+    };
+
+    if tls_cache.is_some() {
+        startup_tracker
+            .complete_component(
+                COMPONENT_TLS_FRONT_BOOTSTRAP,
+                Some("tls front cache is initialized".to_string()),
+            )
+            .await;
+    }
+
+    tls_cache
+}

src/network/probe.rs

@@ -8,9 +8,10 @@ use tokio::task::JoinSet;
 use tokio::time::timeout;
 use tracing::{debug, info, warn};
 
-use crate::config::NetworkConfig;
+use crate::config::{NetworkConfig, UpstreamConfig, UpstreamType};
 use crate::error::Result;
-use crate::network::stun::{stun_probe_dual, DualStunResult, IpFamily, StunProbeResult};
+use crate::network::stun::{stun_probe_family_with_bind, DualStunResult, IpFamily, StunProbeResult};
+use crate::transport::UpstreamManager;
 
 #[derive(Debug, Clone, Default)]
 pub struct NetworkProbe {
@@ -57,19 +58,22 @@ const STUN_BATCH_TIMEOUT: Duration = Duration::from_secs(5);
 
 pub async fn run_probe(
     config: &NetworkConfig,
+    upstreams: &[UpstreamConfig],
     nat_probe: bool,
     stun_nat_probe_concurrency: usize,
 ) -> Result<NetworkProbe> {
     let mut probe = NetworkProbe::default();
+    let servers = collect_stun_servers(config);
+    let mut detected_ipv4 = detect_local_ip_v4();
+    let mut detected_ipv6 = detect_local_ip_v6();
+    let mut explicit_detected_ipv4 = false;
+    let mut explicit_detected_ipv6 = false;
+    let mut explicit_reflected_ipv4 = false;
+    let mut explicit_reflected_ipv6 = false;
+    let mut strict_bind_ipv4_requested = false;
+    let mut strict_bind_ipv6_requested = false;
 
-    probe.detected_ipv4 = detect_local_ip_v4();
-    probe.detected_ipv6 = detect_local_ip_v6();
-
-    probe.ipv4_is_bogon = probe.detected_ipv4.map(is_bogon_v4).unwrap_or(false);
-    probe.ipv6_is_bogon = probe.detected_ipv6.map(is_bogon_v6).unwrap_or(false);
-
-    let stun_res = if nat_probe && config.stun_use {
-        let servers = collect_stun_servers(config);
+    let global_stun_res = if nat_probe && config.stun_use {
         if servers.is_empty() {
             warn!("STUN probe is enabled but network.stun_servers is empty");
             DualStunResult::default()
@@ -77,6 +81,8 @@ pub async fn run_probe(
             probe_stun_servers_parallel(
                 &servers,
                 stun_nat_probe_concurrency.max(1),
+                None,
+                None,
             )
             .await
         }
@@ -86,8 +92,108 @@ pub async fn run_probe(
     } else {
         DualStunResult::default()
     };
-    probe.reflected_ipv4 = stun_res.v4.map(|r| r.reflected_addr);
-    probe.reflected_ipv6 = stun_res.v6.map(|r| r.reflected_addr);
+    let mut reflected_ipv4 = global_stun_res.v4.map(|r| r.reflected_addr);
+    let mut reflected_ipv6 = global_stun_res.v6.map(|r| r.reflected_addr);
+
+    for upstream in upstreams.iter().filter(|upstream| upstream.enabled) {
+        let UpstreamType::Direct {
+            interface,
+            bind_addresses,
+        } = &upstream.upstream_type else {
+            continue;
+        };
+        if let Some(addrs) = bind_addresses.as_ref().filter(|v| !v.is_empty()) {
+            let mut saw_parsed_ip = false;
+            for value in addrs {
+                if let Ok(ip) = value.parse::<IpAddr>() {
+                    saw_parsed_ip = true;
+                    if ip.is_ipv4() {
+                        strict_bind_ipv4_requested = true;
+                    } else {
+                        strict_bind_ipv6_requested = true;
+                    }
+                }
+            }
+            if !saw_parsed_ip {
+                strict_bind_ipv4_requested = true;
+                strict_bind_ipv6_requested = true;
+            }
+        }
+
+        let bind_v4 = UpstreamManager::resolve_bind_address(
+            interface,
+            bind_addresses,
+            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(198, 51, 100, 1)), 443),
+            None,
+            true,
+        );
+        let bind_v6 = UpstreamManager::resolve_bind_address(
+            interface,
+            bind_addresses,
+            SocketAddr::new(
+                IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1)),
+                443,
+            ),
+            None,
+            true,
+        );
+
+        if let Some(IpAddr::V4(ip)) = bind_v4
+            && !explicit_detected_ipv4
+        {
+            detected_ipv4 = Some(ip);
+            explicit_detected_ipv4 = true;
+        }
+        if let Some(IpAddr::V6(ip)) = bind_v6
+            && !explicit_detected_ipv6
+        {
+            detected_ipv6 = Some(ip);
+            explicit_detected_ipv6 = true;
+        }
+        if bind_v4.is_none() && bind_v6.is_none() {
+            continue;
+        }
+
+        if !(nat_probe && config.stun_use) || servers.is_empty() {
+            continue;
+        }
+
+        let direct_stun_res = probe_stun_servers_parallel(
+            &servers,
+            stun_nat_probe_concurrency.max(1),
+            bind_v4,
+            bind_v6,
+        )
+        .await;
+        if let Some(reflected) = direct_stun_res.v4.map(|r| r.reflected_addr) {
+            reflected_ipv4 = Some(reflected);
+            explicit_reflected_ipv4 = true;
+        }
+        if let Some(reflected) = direct_stun_res.v6.map(|r| r.reflected_addr) {
+            reflected_ipv6 = Some(reflected);
+            explicit_reflected_ipv6 = true;
+        }
+    }
+
+    if strict_bind_ipv4_requested && !explicit_detected_ipv4 {
+        detected_ipv4 = None;
+        reflected_ipv4 = None;
+    } else if strict_bind_ipv4_requested && !explicit_reflected_ipv4 {
+        reflected_ipv4 = None;
+    }
+    if strict_bind_ipv6_requested && !explicit_detected_ipv6 {
+        detected_ipv6 = None;
+        reflected_ipv6 = None;
+    } else if strict_bind_ipv6_requested && !explicit_reflected_ipv6 {
+        reflected_ipv6 = None;
+    }
+
+    probe.detected_ipv4 = detected_ipv4;
+    probe.detected_ipv6 = detected_ipv6;
+    probe.reflected_ipv4 = reflected_ipv4;
+    probe.reflected_ipv6 = reflected_ipv6;
+    probe.ipv4_is_bogon = probe.detected_ipv4.map(is_bogon_v4).unwrap_or(false);
+    probe.ipv6_is_bogon = probe.detected_ipv6.map(is_bogon_v6).unwrap_or(false);
 
     // If STUN is blocked but IPv4 is private, try HTTP public-IP fallback.
     if nat_probe
@@ -162,6 +268,8 @@ fn collect_stun_servers(config: &NetworkConfig) -> Vec<String> {
 async fn probe_stun_servers_parallel(
     servers: &[String],
     concurrency: usize,
+    bind_v4: Option<IpAddr>,
+    bind_v6: Option<IpAddr>,
 ) -> DualStunResult {
     let mut join_set = JoinSet::new();
     let mut next_idx = 0usize;
@@ -172,8 +280,15 @@ async fn probe_stun_servers_parallel(
         while next_idx < servers.len() && join_set.len() < concurrency {
             let stun_addr = servers[next_idx].clone();
             next_idx += 1;
+            let bind_v4 = bind_v4;
+            let bind_v6 = bind_v6;
             join_set.spawn(async move {
-                let res = timeout(STUN_BATCH_TIMEOUT, stun_probe_dual(&stun_addr)).await;
+                let res = timeout(STUN_BATCH_TIMEOUT, async {
+                    let v4 = stun_probe_family_with_bind(&stun_addr, IpFamily::V4, bind_v4).await?;
+                    let v6 = stun_probe_family_with_bind(&stun_addr, IpFamily::V6, bind_v6).await?;
+                    Ok::<DualStunResult, crate::error::ProxyError>(DualStunResult { v4, v6 })
+                })
+                .await;
                 (stun_addr, res)
             });
         }
@@ -226,18 +341,24 @@ async fn probe_stun_servers_parallel(
     out
 }
 
-pub fn decide_network_capabilities(config: &NetworkConfig, probe: &NetworkProbe) -> NetworkDecision {
+pub fn decide_network_capabilities(
+    config: &NetworkConfig,
+    probe: &NetworkProbe,
+    middle_proxy_nat_ip: Option<IpAddr>,
+) -> NetworkDecision {
     let ipv4_dc = config.ipv4 && probe.detected_ipv4.is_some();
     let ipv6_dc = config.ipv6.unwrap_or(probe.detected_ipv6.is_some()) && probe.detected_ipv6.is_some();
+    let nat_ip_v4 = matches!(middle_proxy_nat_ip, Some(IpAddr::V4(_)));
+    let nat_ip_v6 = matches!(middle_proxy_nat_ip, Some(IpAddr::V6(_)));
 
     let ipv4_me = config.ipv4
         && probe.detected_ipv4.is_some()
-        && (!probe.ipv4_is_bogon || probe.reflected_ipv4.is_some());
+        && (!probe.ipv4_is_bogon || probe.reflected_ipv4.is_some() || nat_ip_v4);
 
     let ipv6_enabled = config.ipv6.unwrap_or(probe.detected_ipv6.is_some());
     let ipv6_me = ipv6_enabled
         && probe.detected_ipv6.is_some()
-        && (!probe.ipv6_is_bogon || probe.reflected_ipv6.is_some());
+        && (!probe.ipv6_is_bogon || probe.reflected_ipv6.is_some() || nat_ip_v6);
 
     let effective_prefer = match config.prefer {
         6 if ipv6_me || ipv6_dc => 6,
@@ -262,6 +383,58 @@ pub fn decide_network_capabilities(config: &NetworkConfig, probe: &NetworkProbe)
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::NetworkConfig;
+
+    #[test]
+    fn manual_nat_ip_enables_ipv4_me_without_reflection() {
+        let config = NetworkConfig {
+            ipv4: true,
+            ..Default::default()
+        };
+        let probe = NetworkProbe {
+            detected_ipv4: Some(Ipv4Addr::new(10, 0, 0, 10)),
+            ipv4_is_bogon: true,
+            ..Default::default()
+        };
+
+        let decision = decide_network_capabilities(
+            &config,
+            &probe,
+            Some(IpAddr::V4(Ipv4Addr::new(1, 2, 3, 4))),
+        );
+
+        assert!(decision.ipv4_me);
+    }
+
+    #[test]
+    fn manual_nat_ip_does_not_enable_other_family() {
+        let config = NetworkConfig {
+            ipv4: true,
+            ipv6: Some(true),
+            ..Default::default()
+        };
+        let probe = NetworkProbe {
+            detected_ipv4: Some(Ipv4Addr::new(10, 0, 0, 10)),
+            detected_ipv6: Some(Ipv6Addr::LOCALHOST),
+            ipv4_is_bogon: true,
+            ipv6_is_bogon: true,
+            ..Default::default()
+        };
+
+        let decision = decide_network_capabilities(
+            &config,
+            &probe,
+            Some(IpAddr::V4(Ipv4Addr::new(1, 2, 3, 4))),
+        );
+
+        assert!(decision.ipv4_me);
+        assert!(!decision.ipv6_me);
+    }
+}
+
 fn detect_local_ip_v4() -> Option<Ipv4Addr> {
     let socket = UdpSocket::bind("0.0.0.0:0").ok()?;
     socket.connect("8.8.8.8:80").ok()?;
@@ -280,6 +453,14 @@ fn detect_local_ip_v6() -> Option<Ipv6Addr> {
     }
 }
 
+pub fn detect_interface_ipv4() -> Option<Ipv4Addr> {
+    detect_local_ip_v4()
+}
+
+pub fn detect_interface_ipv6() -> Option<Ipv6Addr> {
+    detect_local_ip_v6()
+}
+
 pub fn is_bogon(ip: IpAddr) -> bool {
     match ip {
         IpAddr::V4(v4) => is_bogon_v4(v4),

src/protocol/tls.rs

@@ -13,6 +13,7 @@ use super::constants::*;
 use std::time::{SystemTime, UNIX_EPOCH};
 use num_bigint::BigUint;
 use num_traits::One;
+use subtle::ConstantTimeEq;
 
 // ============= Public Constants =============
 
@@ -28,6 +29,8 @@ pub const TLS_DIGEST_HALF_LEN: usize = 16;
 /// Time skew limits for anti-replay (in seconds)
 pub const TIME_SKEW_MIN: i64 = -20 * 60; // 20 minutes before
 pub const TIME_SKEW_MAX: i64 = 10 * 60;  // 10 minutes after
+/// Maximum accepted boot-time timestamp (seconds) before skew checks are enforced.
+pub const BOOT_TIME_MAX_SECS: u32 = 7 * 24 * 60 * 60;
 
 // ============= Private Constants =============
 
@@ -125,7 +128,7 @@ impl TlsExtensionBuilder {
         //     protocol name length (1 byte)
         //     protocol name bytes
         let proto_len = proto.len() as u8;
-        let list_len: u16 = 1 + proto_len as u16;
+        let list_len: u16 = 1 + u16::from(proto_len);
         let ext_len: u16 = 2 + list_len;
 
         self.extensions.extend_from_slice(&ext_len.to_be_bytes());
@@ -273,13 +276,86 @@ impl ServerHelloBuilder {
 
 // ============= Public Functions =============
 
-/// Validate TLS ClientHello against user secrets
+/// Validate TLS ClientHello against user secrets.
 ///
 /// Returns validation result if a matching user is found.
+/// The result **must** be used — ignoring it silently bypasses authentication.
+#[must_use]
 pub fn validate_tls_handshake(
     handshake: &[u8],
     secrets: &[(String, Vec<u8>)],
     ignore_time_skew: bool,
+) -> Option<TlsValidation> {
+    validate_tls_handshake_with_replay_window(
+        handshake,
+        secrets,
+        ignore_time_skew,
+        u64::from(BOOT_TIME_MAX_SECS),
+    )
+}
+
+/// Validate TLS ClientHello and cap the boot-time bypass by replay-cache TTL.
+///
+/// A boot-time timestamp is only accepted when it falls below both
+/// `BOOT_TIME_MAX_SECS` and the configured replay window, preventing timestamp
+/// reuse outside replay cache coverage.
+#[must_use]
+pub fn validate_tls_handshake_with_replay_window(
+    handshake: &[u8],
+    secrets: &[(String, Vec<u8>)],
+    ignore_time_skew: bool,
+    replay_window_secs: u64,
+) -> Option<TlsValidation> {
+    // Only pay the clock syscall when we will actually compare against it.
+    // If `ignore_time_skew` is set, a broken or unavailable system clock
+    // must not block legitimate clients — that would be a DoS via clock failure.
+    let now = if !ignore_time_skew {
+        system_time_to_unix_secs(SystemTime::now())?
+    } else {
+        0_i64
+    };
+
+    let replay_window_u32 = u32::try_from(replay_window_secs).unwrap_or(u32::MAX);
+    let boot_time_cap_secs = BOOT_TIME_MAX_SECS.min(replay_window_u32);
+
+    validate_tls_handshake_at_time_with_boot_cap(
+        handshake,
+        secrets,
+        ignore_time_skew,
+        now,
+        boot_time_cap_secs,
+    )
+}
+
+fn system_time_to_unix_secs(now: SystemTime) -> Option<i64> {
+    // `try_from` rejects values that overflow i64 (> ~292 billion years CE),
+    // whereas `as i64` would silently wrap to a negative timestamp and corrupt
+    // every subsequent time-skew comparison.
+    let d = now.duration_since(UNIX_EPOCH).ok()?;
+    i64::try_from(d.as_secs()).ok()
+}
+
+fn validate_tls_handshake_at_time(
+    handshake: &[u8],
+    secrets: &[(String, Vec<u8>)],
+    ignore_time_skew: bool,
+    now: i64,
+) -> Option<TlsValidation> {
+    validate_tls_handshake_at_time_with_boot_cap(
+        handshake,
+        secrets,
+        ignore_time_skew,
+        now,
+        BOOT_TIME_MAX_SECS,
+    )
+}
+
+fn validate_tls_handshake_at_time_with_boot_cap(
+    handshake: &[u8],
+    secrets: &[(String, Vec<u8>)],
+    ignore_time_skew: bool,
+    now: i64,
+    boot_time_cap_secs: u32,
 ) -> Option<TlsValidation> {
     if handshake.len() < TLS_DIGEST_POS + TLS_DIGEST_LEN + 1 {
         return None;
@@ -305,50 +381,56 @@ pub fn validate_tls_handshake(
     let mut msg = handshake.to_vec();
     msg[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN].fill(0);
     
-    // Get current time
-    let now = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .unwrap()
-        .as_secs() as i64;
-    
+    let mut first_match: Option<(&String, u32)> = None;
+
     for (user, secret) in secrets {
         let computed = sha256_hmac(secret, &msg);
-        
-        // XOR digests
-        let xored: Vec<u8> = digest.iter()
-            .zip(computed.iter())
-            .map(|(a, b)| a ^ b)
-            .collect();
-        
-        // Check that first 28 bytes are zeros (timestamp in last 4)
-        if !xored[..28].iter().all(|&b| b == 0) {
+
+        // Constant-time equality check on the 28-byte HMAC window.
+        // A variable-time short-circuit here lets an active censor measure how many
+        // bytes matched, enabling secret brute-force via timing side-channels.
+        // Direct comparison on the original arrays avoids a heap allocation and
+        // removes the `try_into().unwrap()` that the intermediate Vec would require.
+        if !bool::from(digest[..28].ct_eq(&computed[..28])) {
             continue;
         }
-        
-        // Extract timestamp
-        let timestamp = u32::from_le_bytes(xored[28..32].try_into().unwrap());
-        let time_diff = now - timestamp as i64;
-        
-        // Check time skew
+
+        // The last 4 bytes encode the timestamp as XOR(digest[28..32], computed[28..32]).
+        // Inline array construction is infallible: both slices are [u8; 32] by construction.
+        let timestamp = u32::from_le_bytes([
+            digest[28] ^ computed[28],
+            digest[29] ^ computed[29],
+            digest[30] ^ computed[30],
+            digest[31] ^ computed[31],
+        ]);
+
+        // time_diff is only meaningful (and `now` is only valid) when we are
+        // actually checking the window.  Keep both inside the guard to make
+        // the dead-code path explicit and prevent accidental future use of
+        // a sentinel `now` value outside its intended scope.
         if !ignore_time_skew {
             // Allow very small timestamps (boot time instead of unix time)
             // This is a quirk in some clients that use uptime instead of real time
-            let is_boot_time = timestamp < 60 * 60 * 24 * 1000; // < ~2.7 years in seconds
-            
-            if !is_boot_time && !(TIME_SKEW_MIN..=TIME_SKEW_MAX).contains(&time_diff) {
-                continue;
+            let is_boot_time = timestamp < boot_time_cap_secs;
+            if !is_boot_time {
+                let time_diff = now - i64::from(timestamp);
+                if !(TIME_SKEW_MIN..=TIME_SKEW_MAX).contains(&time_diff) {
+                    continue;
+                }
             }
         }
         
-        return Some(TlsValidation {
-            user: user.clone(),
-            session_id,
-            digest,
-            timestamp,
-        });
+        if first_match.is_none() {
+            first_match = Some((user, timestamp));
+        }
     }
-    
-    None
+
+    first_match.map(|(user, timestamp)| TlsValidation {
+        user: user.clone(),
+        session_id,
+        digest,
+        timestamp,
+    })
 }
 
 fn curve25519_prime() -> BigUint {
@@ -528,7 +610,9 @@ pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
                 if name_type == 0 && name_len > 0
                     && let Ok(host) = std::str::from_utf8(&handshake[sn_pos..sn_pos + name_len])
                 {
-                    return Some(host.to_string());
+                    if is_valid_sni_hostname(host) {
+                        return Some(host.to_string());
+                    }
                 }
                 sn_pos += name_len;
             }
@@ -539,6 +623,35 @@ pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
     None
 }
 
+fn is_valid_sni_hostname(host: &str) -> bool {
+    if host.is_empty() || host.len() > 253 {
+        return false;
+    }
+    if host.starts_with('.') || host.ends_with('.') {
+        return false;
+    }
+    if host.parse::<std::net::IpAddr>().is_ok() {
+        return false;
+    }
+
+    for label in host.split('.') {
+        if label.is_empty() || label.len() > 63 {
+            return false;
+        }
+        if label.starts_with('-') || label.ends_with('-') {
+            return false;
+        }
+        if !label
+            .bytes()
+            .all(|b| b.is_ascii_alphanumeric() || b == b'-')
+        {
+            return false;
+        }
+    }
+
+    true
+}
+
 /// Extract ALPN protocol list from ClientHello, return in offered order.
 pub fn extract_alpn_from_client_hello(handshake: &[u8]) -> Vec<Vec<u8>> {
     let mut pos = 5; // after record header
@@ -667,291 +780,29 @@ fn validate_server_hello_structure(data: &[u8]) -> Result<(), ProxyError> {
     Ok(())
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-    
-    #[test]
-    fn test_is_tls_handshake() {
-        assert!(is_tls_handshake(&[0x16, 0x03, 0x01]));
-        assert!(is_tls_handshake(&[0x16, 0x03, 0x01, 0x02, 0x00]));
-        assert!(!is_tls_handshake(&[0x17, 0x03, 0x01])); // Application data
-        assert!(!is_tls_handshake(&[0x16, 0x03, 0x02])); // Wrong version
-        assert!(!is_tls_handshake(&[0x16, 0x03])); // Too short
-    }
-    
-    #[test]
-    fn test_parse_tls_record_header() {
-        let header = [0x16, 0x03, 0x01, 0x02, 0x00];
-        let result = parse_tls_record_header(&header).unwrap();
-        assert_eq!(result.0, TLS_RECORD_HANDSHAKE);
-        assert_eq!(result.1, 512);
-        
-        let header = [0x17, 0x03, 0x03, 0x40, 0x00];
-        let result = parse_tls_record_header(&header).unwrap();
-        assert_eq!(result.0, TLS_RECORD_APPLICATION);
-        assert_eq!(result.1, 16384);
-    }
-    
-    #[test]
-    fn test_gen_fake_x25519_key() {
-        let rng = SecureRandom::new();
-        let key1 = gen_fake_x25519_key(&rng);
-        let key2 = gen_fake_x25519_key(&rng);
-        
-        assert_eq!(key1.len(), 32);
-        assert_eq!(key2.len(), 32);
-        assert_ne!(key1, key2); // Should be random
-    }
+// ============= Compile-time Security Invariants =============
 
-    #[test]
-    fn test_fake_x25519_key_is_quadratic_residue() {
-        let rng = SecureRandom::new();
-        let key = gen_fake_x25519_key(&rng);
-        let p = curve25519_prime();
-        let k_num = BigUint::from_bytes_le(&key);
-        let exponent = (&p - BigUint::one()) >> 1;
-        let legendre = k_num.modpow(&exponent, &p);
-        assert_eq!(legendre, BigUint::one());
-    }
-    
-    #[test]
-    fn test_tls_extension_builder() {
-        let key = [0x42u8; 32];
-        
-        let mut builder = TlsExtensionBuilder::new();
-        builder.add_key_share(&key);
-        builder.add_supported_versions(0x0304);
-        
-        let result = builder.build();
-        
-        // Check length prefix
-        let len = u16::from_be_bytes([result[0], result[1]]) as usize;
-        assert_eq!(len, result.len() - 2);
-        
-        // Check key_share extension is present
-        assert!(result.len() > 40); // At least key share
-    }
-    
-    #[test]
-    fn test_server_hello_builder() {
-        let session_id = vec![0x01, 0x02, 0x03, 0x04];
-        let key = [0x55u8; 32];
-        
-        let builder = ServerHelloBuilder::new(session_id.clone())
-            .with_x25519_key(&key)
-            .with_tls13_version();
-        
-        let record = builder.build_record();
-        
-        // Validate structure
-        validate_server_hello_structure(&record).expect("Invalid ServerHello structure");
-        
-        // Check record type
-        assert_eq!(record[0], TLS_RECORD_HANDSHAKE);
-        
-        // Check version
-        assert_eq!(&record[1..3], &TLS_VERSION);
-        
-        // Check message type (ServerHello = 0x02)
-        assert_eq!(record[5], 0x02);
-    }
-    
-    #[test]
-    fn test_build_server_hello_structure() {
-        let secret = b"test secret";
-        let client_digest = [0x42u8; 32];
-        let session_id = vec![0xAA; 32];
-        
-        let rng = SecureRandom::new();
-        let response = build_server_hello(secret, &client_digest, &session_id, 2048, &rng, None, 0);
-        
-        // Should have at least 3 records
-        assert!(response.len() > 100);
-        
-        // First record should be ServerHello
-        assert_eq!(response[0], TLS_RECORD_HANDSHAKE);
-        
-        // Validate ServerHello structure
-        validate_server_hello_structure(&response).expect("Invalid ServerHello");
-        
-        // Find Change Cipher Spec
-        let server_hello_len = 5 + u16::from_be_bytes([response[3], response[4]]) as usize;
-        let ccs_start = server_hello_len;
-        
-        assert!(response.len() > ccs_start + 6);
-        assert_eq!(response[ccs_start], TLS_RECORD_CHANGE_CIPHER);
-        
-        // Find Application Data
-        let ccs_len = 5 + u16::from_be_bytes([response[ccs_start + 3], response[ccs_start + 4]]) as usize;
-        let app_start = ccs_start + ccs_len;
-        
-        assert!(response.len() > app_start + 5);
-        assert_eq!(response[app_start], TLS_RECORD_APPLICATION);
-    }
-    
-    #[test]
-    fn test_build_server_hello_digest() {
-        let secret = b"test secret key here";
-        let client_digest = [0x42u8; 32];
-        let session_id = vec![0xAA; 32];
-        
-        let rng = SecureRandom::new();
-        let response1 = build_server_hello(secret, &client_digest, &session_id, 1024, &rng, None, 0);
-        let response2 = build_server_hello(secret, &client_digest, &session_id, 1024, &rng, None, 0);
-        
-        // Digest position should have non-zero data
-        let digest1 = &response1[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN];
-        assert!(!digest1.iter().all(|&b| b == 0));
-        
-        // Different calls should have different digests (due to random cert)
-        let digest2 = &response2[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN];
-        assert_ne!(digest1, digest2);
-    }
-    
-    #[test]
-    fn test_server_hello_extensions_length() {
-        let session_id = vec![0x01; 32];
-        let key = [0x55u8; 32];
-        
-        let builder = ServerHelloBuilder::new(session_id)
-            .with_x25519_key(&key)
-            .with_tls13_version();
-        
-        let record = builder.build_record();
-        
-        // Parse to find extensions
-        let msg_start = 5; // After record header
-        let msg_len = u32::from_be_bytes([0, record[6], record[7], record[8]]) as usize;
-        
-        // Skip to session ID
-        let session_id_pos = msg_start + 4 + 2 + 32; // header(4) + version(2) + random(32)
-        let session_id_len = record[session_id_pos] as usize;
-        
-        // Skip to extensions
-        let ext_len_pos = session_id_pos + 1 + session_id_len + 2 + 1; // session_id + cipher(2) + compression(1)
-        let ext_len = u16::from_be_bytes([record[ext_len_pos], record[ext_len_pos + 1]]) as usize;
-        
-        // Verify extensions length matches actual data
-        let extensions_data = &record[ext_len_pos + 2..msg_start + 4 + msg_len];
-        assert_eq!(ext_len, extensions_data.len(), 
-            "Extension length mismatch: declared {}, actual {}", ext_len, extensions_data.len());
-    }
-    
-    #[test]
-    fn test_validate_tls_handshake_format() {
-        // Build a minimal ClientHello-like structure
-        let mut handshake = vec![0u8; 100];
-        
-        // Put a valid-looking digest at position 11
-        handshake[TLS_DIGEST_POS..TLS_DIGEST_POS + TLS_DIGEST_LEN]
-            .copy_from_slice(&[0x42; 32]);
-        
-        // Session ID length
-        handshake[TLS_DIGEST_POS + TLS_DIGEST_LEN] = 32;
-        
-        // This won't validate (wrong HMAC) but shouldn't panic
-        let secrets = vec![("test".to_string(), b"secret".to_vec())];
-        let result = validate_tls_handshake(&handshake, &secrets, true);
-        
-        // Should return None (no match) but not panic
-        assert!(result.is_none());
-    }
+/// Compile-time checks that enforce invariants the rest of the code relies on.
+/// Using `static_assertions` ensures these can never silently break across
+/// refactors without a compile error.
+mod compile_time_security_checks {
+    use super::{TLS_DIGEST_LEN, TLS_DIGEST_HALF_LEN};
+    use static_assertions::const_assert;
 
-    fn build_client_hello_with_exts(exts: Vec<(u16, Vec<u8>)>, host: &str) -> Vec<u8> {
-        let mut body = Vec::new();
-        body.extend_from_slice(&TLS_VERSION); // legacy version
-        body.extend_from_slice(&[0u8; 32]); // random
-        body.push(0); // session id len
-        body.extend_from_slice(&2u16.to_be_bytes()); // cipher suites len
-        body.extend_from_slice(&[0x13, 0x01]); // TLS_AES_128_GCM_SHA256
-        body.push(1); // compression len
-        body.push(0); // null compression
+    // The digest must be exactly one SHA-256 output.
+    const_assert!(TLS_DIGEST_LEN == 32);
 
-        // Build SNI extension
-        let host_bytes = host.as_bytes();
-        let mut sni_ext = Vec::new();
-        sni_ext.extend_from_slice(&(host_bytes.len() as u16 + 3).to_be_bytes());
-        sni_ext.push(0);
-        sni_ext.extend_from_slice(&(host_bytes.len() as u16).to_be_bytes());
-        sni_ext.extend_from_slice(host_bytes);
+    // Replay-dedup stores the first half; verify it is literally half.
+    const_assert!(TLS_DIGEST_HALF_LEN * 2 == TLS_DIGEST_LEN);
 
-        let mut ext_blob = Vec::new();
-        for (typ, data) in exts {
-            ext_blob.extend_from_slice(&typ.to_be_bytes());
-            ext_blob.extend_from_slice(&(data.len() as u16).to_be_bytes());
-            ext_blob.extend_from_slice(&data);
-        }
-        // SNI last
-        ext_blob.extend_from_slice(&0x0000u16.to_be_bytes());
-        ext_blob.extend_from_slice(&(sni_ext.len() as u16).to_be_bytes());
-        ext_blob.extend_from_slice(&sni_ext);
-
-        body.extend_from_slice(&(ext_blob.len() as u16).to_be_bytes());
-        body.extend_from_slice(&ext_blob);
-
-        let mut handshake = Vec::new();
-        handshake.push(0x01); // ClientHello
-        let len_bytes = (body.len() as u32).to_be_bytes();
-        handshake.extend_from_slice(&len_bytes[1..4]);
-        handshake.extend_from_slice(&body);
-
-        let mut record = Vec::new();
-        record.push(TLS_RECORD_HANDSHAKE);
-        record.extend_from_slice(&[0x03, 0x01]);
-        record.extend_from_slice(&(handshake.len() as u16).to_be_bytes());
-        record.extend_from_slice(&handshake);
-        record
-    }
-
-    #[test]
-    fn test_extract_sni_with_grease_extension() {
-        // GREASE type 0x0a0a with zero length before SNI
-        let ch = build_client_hello_with_exts(vec![(0x0a0a, Vec::new())], "example.com");
-        let sni = extract_sni_from_client_hello(&ch);
-        assert_eq!(sni.as_deref(), Some("example.com"));
-    }
-
-    #[test]
-    fn test_extract_sni_tolerates_empty_unknown_extension() {
-        let ch = build_client_hello_with_exts(vec![(0x1234, Vec::new())], "test.local");
-        let sni = extract_sni_from_client_hello(&ch);
-        assert_eq!(sni.as_deref(), Some("test.local"));
-    }
-
-    #[test]
-    fn test_extract_alpn_single() {
-        let mut alpn_data = Vec::new();
-        // list length = 3 (1 length byte + "h2")
-        alpn_data.extend_from_slice(&3u16.to_be_bytes());
-        alpn_data.push(2);
-        alpn_data.extend_from_slice(b"h2");
-        let ch = build_client_hello_with_exts(vec![(0x0010, alpn_data)], "alpn.test");
-        let alpn = extract_alpn_from_client_hello(&ch);
-        let alpn_str: Vec<String> = alpn
-            .iter()
-            .map(|p| std::str::from_utf8(p).unwrap().to_string())
-            .collect();
-        assert_eq!(alpn_str, vec!["h2"]);
-    }
-
-    #[test]
-    fn test_extract_alpn_multiple() {
-        let mut alpn_data = Vec::new();
-        // list length = 11 (sum of per-proto lengths including length bytes)
-        alpn_data.extend_from_slice(&11u16.to_be_bytes());
-        alpn_data.push(2);
-        alpn_data.extend_from_slice(b"h2");
-        alpn_data.push(4);
-        alpn_data.extend_from_slice(b"spdy");
-        alpn_data.push(2);
-        alpn_data.extend_from_slice(b"h3");
-        let ch = build_client_hello_with_exts(vec![(0x0010, alpn_data)], "alpn.test");
-        let alpn = extract_alpn_from_client_hello(&ch);
-        let alpn_str: Vec<String> = alpn
-            .iter()
-            .map(|p| std::str::from_utf8(p).unwrap().to_string())
-            .collect();
-        assert_eq!(alpn_str, vec!["h2", "spdy", "h3"]);
-    }
+    // The HMAC check window (28 bytes) plus the embedded timestamp (4 bytes)
+    // must exactly fill the digest.  If TLS_DIGEST_LEN ever changes, these
+    // assertions will catch the mismatch before any timing-oracle fix is broke.
+    const_assert!(28 + 4 == TLS_DIGEST_LEN);
 }
+
+// ============= Security-focused regression tests =============
+
+#[cfg(test)]
+#[path = "tls_security_tests.rs"]
+mod security_tests;

src/proxy/client.rs

@@ -4,7 +4,10 @@ use std::future::Future;
 use std::net::{IpAddr, SocketAddr};
 use std::pin::Pin;
 use std::sync::Arc;
+use std::sync::OnceLock;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
+use ipnetwork::IpNetwork;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite};
 use tokio::net::TcpStream;
 use tokio::time::timeout;
@@ -23,7 +26,7 @@ enum HandshakeOutcome {
 
 use crate::config::ProxyConfig;
 use crate::crypto::SecureRandom;
-use crate::error::{HandshakeResult, ProxyError, Result};
+use crate::error::{HandshakeResult, ProxyError, Result, StreamError};
 use crate::ip_tracker::UserIpTracker;
 use crate::protocol::constants::*;
 use crate::protocol::tls;
@@ -39,6 +42,7 @@ use crate::proxy::direct_relay::handle_via_direct;
 use crate::proxy::handshake::{HandshakeSuccess, handle_mtproto_handshake, handle_tls_handshake};
 use crate::proxy::masking::handle_bad_client;
 use crate::proxy::middle_relay::handle_via_middle_proxy;
+use crate::proxy::route_mode::{RelayRouteMode, RouteRuntimeController};
 
 fn beobachten_ttl(config: &ProxyConfig) -> Duration {
     Duration::from_secs(config.general.beobachten_minutes.saturating_mul(60))
@@ -62,14 +66,30 @@ fn record_handshake_failure_class(
     peer_ip: IpAddr,
     error: &ProxyError,
 ) {
-    let class = if error.to_string().contains("expected 64 bytes, got 0") {
-        "expected_64_got_0"
-    } else {
-        "other"
+    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",
+        _ => "other",
     };
     record_beobachten_class(beobachten, config, peer_ip, class);
 }
 
+fn is_trusted_proxy_source(peer_ip: IpAddr, trusted: &[IpNetwork]) -> bool {
+    if trusted.is_empty() {
+        static EMPTY_PROXY_TRUST_WARNED: OnceLock<AtomicBool> = OnceLock::new();
+        let warned = EMPTY_PROXY_TRUST_WARNED.get_or_init(|| AtomicBool::new(false));
+        if !warned.swap(true, Ordering::Relaxed) {
+            warn!(
+                "PROXY protocol enabled but server.proxy_protocol_trusted_cidrs is empty; rejecting all PROXY headers by default"
+            );
+        }
+        return false;
+    }
+    trusted.iter().any(|cidr| cidr.contains(peer_ip))
+}
+
 pub async fn handle_client_stream<S>(
     mut stream: S,
     peer: SocketAddr,
@@ -80,6 +100,7 @@ pub async fn handle_client_stream<S>(
     buffer_pool: Arc<BufferPool>,
     rng: Arc<SecureRandom>,
     me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
     tls_cache: Option<Arc<TlsFrontCache>>,
     ip_tracker: Arc<UserIpTracker>,
     beobachten: Arc<BeobachtenStore>,
@@ -97,8 +118,22 @@ where
         .unwrap_or_else(|_| "0.0.0.0:443".parse().unwrap());
 
     if proxy_protocol_enabled {
-        match parse_proxy_protocol(&mut stream, peer).await {
-            Ok(info) => {
+        let proxy_header_timeout = Duration::from_millis(
+            config.server.proxy_protocol_header_timeout_ms.max(1),
+        );
+        match timeout(proxy_header_timeout, parse_proxy_protocol(&mut stream, peer)).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,
@@ -110,12 +145,18 @@ where
                     local_addr = dst;
                 }
             }
-            Err(e) => {
+            Ok(Err(e)) => {
                 stats.increment_connects_bad();
                 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();
+                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);
+            }
         }
     }
 
@@ -138,8 +179,13 @@ where
         if is_tls {
             let tls_len = u16::from_be_bytes([first_bytes[3], first_bytes[4]]) as usize;
 
-            if tls_len < 512 {
-                debug!(peer = %real_peer, tls_len = tls_len, "TLS handshake too short");
+// RFC 8446 §5.1 mandates that TLSPlaintext records must not exceed 2^14
+        // bytes (16_384). A client claiming a larger record is non-compliant and
+        // may be an active probe attempting to force large allocations.
+        //
+        // Also enforce a minimum record size to avoid trivial/garbage probes.
+        if !(512..=MAX_TLS_RECORD_SIZE).contains(&tls_len) {
+                debug!(peer = %real_peer, tls_len = tls_len, max_tls_len = MAX_TLS_RECORD_SIZE, "TLS handshake length out of bounds");
                 stats.increment_connects_bad();
                 let (reader, writer) = tokio::io::split(stream);
                 handle_bad_client(
@@ -161,7 +207,7 @@ where
 
             let (read_half, write_half) = tokio::io::split(stream);
 
-            let (mut tls_reader, tls_writer, _tls_user) = match handle_tls_handshake(
+            let (mut tls_reader, tls_writer, tls_user) = match handle_tls_handshake(
                 &handshake, read_half, write_half, real_peer,
                 &config, &replay_checker, &rng, tls_cache.clone(),
             ).await {
@@ -190,12 +236,22 @@ where
 
             let (crypto_reader, crypto_writer, success) = match handle_mtproto_handshake(
                 &mtproto_handshake, tls_reader, tls_writer, real_peer,
-                &config, &replay_checker, true,
+                &config, &replay_checker, true, Some(tls_user.as_str()),
             ).await {
                 HandshakeResult::Success(result) => result,
-                HandshakeResult::BadClient { reader: _, writer: _ } => {
+                HandshakeResult::BadClient { reader, writer } => {
                     stats.increment_connects_bad();
                     debug!(peer = %peer, "Valid TLS but invalid MTProto handshake");
+                    handle_bad_client(
+                        reader,
+                        writer,
+                        &mtproto_handshake,
+                        real_peer,
+                        local_addr,
+                        &config,
+                        &beobachten,
+                    )
+                    .await;
                     return Ok(HandshakeOutcome::Handled);
                 }
                 HandshakeResult::Error(e) => return Err(e),
@@ -205,6 +261,7 @@ where
                 RunningClientHandler::handle_authenticated_static(
                     crypto_reader, crypto_writer, success,
                     upstream_manager, stats, config, buffer_pool, rng, me_pool,
+                    route_runtime.clone(),
                     local_addr, real_peer, ip_tracker.clone(),
                 ),
             )))
@@ -234,7 +291,7 @@ where
 
             let (crypto_reader, crypto_writer, success) = match handle_mtproto_handshake(
                 &handshake, read_half, write_half, real_peer,
-                &config, &replay_checker, false,
+                &config, &replay_checker, false, None,
             ).await {
                 HandshakeResult::Success(result) => result,
                 HandshakeResult::BadClient { reader, writer } => {
@@ -265,6 +322,7 @@ where
                     buffer_pool,
                     rng,
                     me_pool,
+                    route_runtime.clone(),
                     local_addr,
                     real_peer,
                     ip_tracker.clone(),
@@ -308,6 +366,8 @@ pub struct ClientHandler;
 pub struct RunningClientHandler {
     stream: TcpStream,
     peer: SocketAddr,
+    real_peer_from_proxy: Option<SocketAddr>,
+    real_peer_report: Arc<std::sync::Mutex<Option<SocketAddr>>>,
     config: Arc<ProxyConfig>,
     stats: Arc<Stats>,
     replay_checker: Arc<ReplayChecker>,
@@ -315,6 +375,7 @@ pub struct RunningClientHandler {
     buffer_pool: Arc<BufferPool>,
     rng: Arc<SecureRandom>,
     me_pool: Option<Arc<MePool>>,
+    route_runtime: Arc<RouteRuntimeController>,
     tls_cache: Option<Arc<TlsFrontCache>>,
     ip_tracker: Arc<UserIpTracker>,
     beobachten: Arc<BeobachtenStore>,
@@ -332,14 +393,19 @@ impl ClientHandler {
         buffer_pool: Arc<BufferPool>,
         rng: Arc<SecureRandom>,
         me_pool: Option<Arc<MePool>>,
+        route_runtime: Arc<RouteRuntimeController>,
         tls_cache: Option<Arc<TlsFrontCache>>,
         ip_tracker: Arc<UserIpTracker>,
         beobachten: Arc<BeobachtenStore>,
         proxy_protocol_enabled: bool,
+        real_peer_report: Arc<std::sync::Mutex<Option<SocketAddr>>>,
     ) -> RunningClientHandler {
+        let normalized_peer = normalize_ip(peer);
         RunningClientHandler {
             stream,
-            peer,
+            peer: normalized_peer,
+            real_peer_from_proxy: None,
+            real_peer_report,
             config,
             stats,
             replay_checker,
@@ -347,6 +413,7 @@ impl ClientHandler {
             buffer_pool,
             rng,
             me_pool,
+            route_runtime,
             tls_cache,
             ip_tracker,
             beobachten,
@@ -356,10 +423,8 @@ impl ClientHandler {
 }
 
 impl RunningClientHandler {
-    pub async fn run(mut self) -> Result<()> {
+    pub async fn run(self) -> Result<()> {
         self.stats.increment_connects_all();
-
-        self.peer = normalize_ip(self.peer);
         let peer = self.peer;
         let _ip_tracker = self.ip_tracker.clone();
         debug!(peer = %peer, "New connection");
@@ -415,8 +480,34 @@ impl RunningClientHandler {
         let mut local_addr = self.stream.local_addr().map_err(ProxyError::Io)?;
 
         if self.proxy_protocol_enabled {
-            match parse_proxy_protocol(&mut self.stream, self.peer).await {
-                Ok(info) => {
+            let proxy_header_timeout = Duration::from_millis(
+                self.config.server.proxy_protocol_header_timeout_ms.max(1),
+            );
+            match timeout(
+                proxy_header_timeout,
+                parse_proxy_protocol(&mut self.stream, self.peer),
+            )
+            .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,
@@ -424,11 +515,15 @@ impl RunningClientHandler {
                         "PROXY protocol header parsed"
                     );
                     self.peer = normalize_ip(info.src_addr);
+                    self.real_peer_from_proxy = Some(self.peer);
+                    if let Ok(mut slot) = self.real_peer_report.lock() {
+                        *slot = Some(self.peer);
+                    }
                     if let Some(dst) = info.dst_addr {
                         local_addr = dst;
                     }
                 }
-                Err(e) => {
+                Ok(Err(e)) => {
                     self.stats.increment_connects_bad();
                     warn!(peer = %self.peer, error = %e, "Invalid PROXY protocol header");
                     record_beobachten_class(
@@ -439,6 +534,21 @@ impl RunningClientHandler {
                     );
                     return Err(e);
                 }
+                Err(_) => {
+                    self.stats.increment_connects_bad();
+                    warn!(
+                        peer = %self.peer,
+                        timeout_ms = proxy_header_timeout.as_millis(),
+                        "PROXY protocol header timeout"
+                    );
+                    record_beobachten_class(
+                        &self.beobachten,
+                        &self.config,
+                        self.peer.ip(),
+                        "other",
+                    );
+                    return Err(ProxyError::InvalidProxyProtocol);
+                }
             }
         }
 
@@ -466,8 +576,10 @@ impl RunningClientHandler {
 
         debug!(peer = %peer, tls_len = tls_len, "Reading TLS handshake");
 
-        if tls_len < 512 {
-            debug!(peer = %peer, tls_len = tls_len, "TLS handshake too short");
+        // See RFC 8446 §5.1: TLSPlaintext records must not exceed 16_384 bytes.
+        // Treat too-small or too-large lengths as active probes and mask them.
+        if !(512..=MAX_TLS_RECORD_SIZE).contains(&tls_len) {
+            debug!(peer = %peer, tls_len = tls_len, max_tls_len = MAX_TLS_RECORD_SIZE, "TLS handshake length out of bounds");
             self.stats.increment_connects_bad();
             let (reader, writer) = self.stream.into_split();
             handle_bad_client(
@@ -494,7 +606,7 @@ impl RunningClientHandler {
 
         let (read_half, write_half) = self.stream.into_split();
 
-        let (mut tls_reader, tls_writer, _tls_user) = match handle_tls_handshake(
+        let (mut tls_reader, tls_writer, tls_user) = match handle_tls_handshake(
             &handshake,
             read_half,
             write_half,
@@ -538,16 +650,24 @@ impl RunningClientHandler {
             &config,
             &replay_checker,
             true,
+            Some(tls_user.as_str()),
         )
         .await
         {
             HandshakeResult::Success(result) => result,
-            HandshakeResult::BadClient {
-                reader: _,
-                writer: _,
-            } => {
+            HandshakeResult::BadClient { reader, writer } => {
                 stats.increment_connects_bad();
                 debug!(peer = %peer, "Valid TLS but invalid MTProto handshake");
+                handle_bad_client(
+                    reader,
+                    writer,
+                    &mtproto_handshake,
+                    peer,
+                    local_addr,
+                    &config,
+                    &self.beobachten,
+                )
+                .await;
                 return Ok(HandshakeOutcome::Handled);
             }
             HandshakeResult::Error(e) => return Err(e),
@@ -564,6 +684,7 @@ impl RunningClientHandler {
                 buffer_pool,
                 self.rng,
                 self.me_pool,
+                self.route_runtime.clone(),
                 local_addr,
                 peer,
                 self.ip_tracker,
@@ -611,6 +732,7 @@ impl RunningClientHandler {
             &config,
             &replay_checker,
             false,
+            None,
         )
         .await
         {
@@ -643,6 +765,7 @@ impl RunningClientHandler {
                 buffer_pool,
                 self.rng,
                 self.me_pool,
+                self.route_runtime.clone(),
                 local_addr,
                 peer,
                 self.ip_tracker,
@@ -664,6 +787,7 @@ impl RunningClientHandler {
         buffer_pool: Arc<BufferPool>,
         rng: Arc<SecureRandom>,
         me_pool: Option<Arc<MePool>>,
+        route_runtime: Arc<RouteRuntimeController>,
         local_addr: SocketAddr,
         peer_addr: SocketAddr,
         ip_tracker: Arc<UserIpTracker>,
@@ -672,69 +796,72 @@ impl RunningClientHandler {
         R: AsyncRead + Unpin + Send + 'static,
         W: AsyncWrite + Unpin + Send + 'static,
     {
-        let user = &success.user;
+        let user = success.user.clone();
 
-        if let Err(e) = Self::check_user_limits_static(user, &config, &stats, peer_addr, &ip_tracker).await {
+        if let Err(e) = Self::check_user_limits_static(&user, &config, &stats, peer_addr, &ip_tracker).await {
             warn!(user = %user, error = %e, "User limit exceeded");
             return Err(e);
         }
 
-        // IP Cleanup Guard: автоматически удаляет IP при выходе из scope
-        struct IpCleanupGuard {
-            tracker: Arc<UserIpTracker>,
-            user: String,
-            ip: std::net::IpAddr,
-        }
-        
-        impl Drop for IpCleanupGuard {
-            fn drop(&mut self) {
-                let tracker = self.tracker.clone();
-                let user = self.user.clone();
-                let ip = self.ip;
-                tokio::spawn(async move {
-                    tracker.remove_ip(&user, ip).await;
-                    debug!(user = %user, ip = %ip, "IP cleaned up on disconnect");
-                });
-            }
-        }
-        
-        let _cleanup = IpCleanupGuard {
-            tracker: ip_tracker,
-            user: user.clone(),
-            ip: peer_addr.ip(),
-        };
-
-        // Decide: middle proxy or direct
-        if config.general.use_middle_proxy {
+        let route_snapshot = route_runtime.snapshot();
+        let session_id = rng.u64();
+        let relay_result = if config.general.use_middle_proxy
+            && matches!(route_snapshot.mode, RelayRouteMode::Middle)
+        {
             if let Some(ref pool) = me_pool {
-                return handle_via_middle_proxy(
+                handle_via_middle_proxy(
                     client_reader,
                     client_writer,
                     success,
                     pool.clone(),
-                    stats,
+                    stats.clone(),
                     config,
                     buffer_pool,
                     local_addr,
                     rng,
+                    route_runtime.subscribe(),
+                    route_snapshot,
+                    session_id,
                 )
-                .await;
+                .await
+            } else {
+                warn!("use_middle_proxy=true but MePool not initialized, falling back to direct");
+                handle_via_direct(
+                    client_reader,
+                    client_writer,
+                    success,
+                    upstream_manager,
+                    stats.clone(),
+                    config,
+                    buffer_pool,
+                    rng,
+                    route_runtime.subscribe(),
+                    route_snapshot,
+                    session_id,
+                )
+                .await
             }
-            warn!("use_middle_proxy=true but MePool not initialized, falling back to direct");
-        }
+        } else {
+            // Direct mode (original behavior)
+            handle_via_direct(
+                client_reader,
+                client_writer,
+                success,
+                upstream_manager,
+                stats.clone(),
+                config,
+                buffer_pool,
+                rng,
+                route_runtime.subscribe(),
+                route_snapshot,
+                session_id,
+            )
+            .await
+        };
 
-        // Direct mode (original behavior)
-        handle_via_direct(
-            client_reader,
-            client_writer,
-            success,
-            upstream_manager,
-            stats,
-            config,
-            buffer_pool,
-            rng,
-        )
-        .await
+        stats.decrement_user_curr_connects(&user);
+        ip_tracker.remove_ip(&user, peer_addr.ip()).await;
+        relay_result
     }
 
     async fn check_user_limits_static(
@@ -752,27 +879,6 @@ impl RunningClientHandler {
             });
         }
 
-        // IP limit check
-        if let Err(reason) = ip_tracker.check_and_add(user, peer_addr.ip()).await {
-            warn!(
-                user = %user,
-                ip = %peer_addr.ip(),
-                reason = %reason,
-                "IP limit exceeded"
-            );
-            return Err(ProxyError::ConnectionLimitExceeded {
-                user: user.to_string(),
-            });
-        }
-
-        if let Some(limit) = config.access.user_max_tcp_conns.get(user)
-            && stats.get_user_curr_connects(user) >= *limit as u64
-        {
-            return Err(ProxyError::ConnectionLimitExceeded {
-                user: user.to_string(),
-            });
-        }
-
         if let Some(quota) = config.access.user_data_quota.get(user)
             && stats.get_user_total_octets(user) >= *quota
         {
@@ -781,6 +887,37 @@ impl RunningClientHandler {
             });
         }
 
+        let limit = config
+            .access
+            .user_max_tcp_conns
+            .get(user)
+            .map(|v| *v as u64);
+        if !stats.try_acquire_user_curr_connects(user, limit) {
+            return Err(ProxyError::ConnectionLimitExceeded {
+                user: user.to_string(),
+            });
+        }
+
+        match ip_tracker.check_and_add(user, peer_addr.ip()).await {
+            Ok(()) => {}
+            Err(reason) => {
+                stats.decrement_user_curr_connects(user);
+                warn!(
+                    user = %user,
+                    ip = %peer_addr.ip(),
+                    reason = %reason,
+                    "IP limit exceeded"
+                );
+                return Err(ProxyError::ConnectionLimitExceeded {
+                    user: user.to_string(),
+                });
+            }
+        }
+
         Ok(())
     }
 }
+
+#[cfg(test)]
+#[path = "client_security_tests.rs"]
+mod security_tests;

src/proxy/direct_relay.rs

@@ -2,21 +2,67 @@ use std::fs::OpenOptions;
 use std::io::Write;
 use std::net::SocketAddr;
 use std::sync::Arc;
+use std::collections::HashSet;
+use std::sync::{Mutex, OnceLock};
 
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
 use tokio::net::TcpStream;
+use tokio::sync::watch;
 use tracing::{debug, info, warn};
 
 use crate::config::ProxyConfig;
 use crate::crypto::SecureRandom;
-use crate::error::Result;
+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::relay::relay_bidirectional;
+use crate::proxy::route_mode::{
+    RelayRouteMode, RouteCutoverState, ROUTE_SWITCH_ERROR_MSG, affected_cutover_state,
+    cutover_stagger_delay,
+};
 use crate::stats::Stats;
 use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
 use crate::transport::UpstreamManager;
 
+const UNKNOWN_DC_LOG_DISTINCT_LIMIT: usize = 1024;
+static LOGGED_UNKNOWN_DCS: OnceLock<Mutex<HashSet<i16>>> = OnceLock::new();
+
+// In tests, this function shares global mutable state. Callers that also use
+// cache-reset helpers must hold `unknown_dc_test_lock()` to keep assertions
+// deterministic under parallel execution.
+fn should_log_unknown_dc(dc_idx: i16) -> bool {
+    let set = LOGGED_UNKNOWN_DCS.get_or_init(|| Mutex::new(HashSet::new()));
+    match set.lock() {
+        Ok(mut guard) => {
+            if guard.contains(&dc_idx) {
+                return false;
+            }
+            if guard.len() >= UNKNOWN_DC_LOG_DISTINCT_LIMIT {
+                return false;
+            }
+            guard.insert(dc_idx)
+        }
+        // If the lock is poisoned, keep logging rather than silently dropping
+        // operator-visible diagnostics.
+        Err(_) => true,
+    }
+}
+
+#[cfg(test)]
+fn clear_unknown_dc_log_cache_for_testing() {
+    if let Some(set) = LOGGED_UNKNOWN_DCS.get()
+        && let Ok(mut guard) = set.lock()
+    {
+        guard.clear();
+    }
+}
+
+#[cfg(test)]
+fn unknown_dc_test_lock() -> &'static Mutex<()> {
+    static TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    TEST_LOCK.get_or_init(|| Mutex::new(()))
+}
+
 pub(crate) async fn handle_via_direct<R, W>(
     client_reader: CryptoReader<R>,
     client_writer: CryptoWriter<W>,
@@ -26,6 +72,9 @@ pub(crate) async fn handle_via_direct<R, W>(
     config: Arc<ProxyConfig>,
     buffer_pool: Arc<BufferPool>,
     rng: Arc<SecureRandom>,
+    mut route_rx: watch::Receiver<RouteCutoverState>,
+    route_snapshot: RouteCutoverState,
+    session_id: u64,
 ) -> Result<()>
 where
     R: AsyncRead + Unpin + Send + 'static,
@@ -34,7 +83,7 @@ where
     let user = &success.user;
     let dc_addr = get_dc_addr_static(success.dc_idx, &config)?;
 
-    info!(
+    debug!(
         user = %user,
         peer = %success.peer,
         dc = success.dc_idx,
@@ -56,20 +105,50 @@ where
     debug!(peer = %success.peer, "TG handshake complete, starting relay");
 
     stats.increment_user_connects(user);
-    stats.increment_user_curr_connects(user);
+    stats.increment_current_connections_direct();
 
     let relay_result = relay_bidirectional(
         client_reader,
         client_writer,
         tg_reader,
         tg_writer,
+        config.general.direct_relay_copy_buf_c2s_bytes,
+        config.general.direct_relay_copy_buf_s2c_bytes,
         user,
         Arc::clone(&stats),
         buffer_pool,
-    )
-    .await;
+    );
+    tokio::pin!(relay_result);
+    let relay_result = loop {
+        if let Some(cutover) = affected_cutover_state(
+            &route_rx,
+            RelayRouteMode::Direct,
+            route_snapshot.generation,
+        ) {
+            let delay = cutover_stagger_delay(session_id, cutover.generation);
+            warn!(
+                user = %user,
+                target_mode = cutover.mode.as_str(),
+                cutover_generation = cutover.generation,
+                delay_ms = delay.as_millis() as u64,
+                "Cutover affected direct session, closing client connection"
+            );
+            tokio::time::sleep(delay).await;
+            break Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+        }
+        tokio::select! {
+            result = &mut relay_result => {
+                break result;
+            }
+            changed = route_rx.changed() => {
+                if changed.is_err() {
+                    break relay_result.await;
+                }
+            }
+        }
+    };
 
-    stats.decrement_user_curr_connects(user);
+    stats.decrement_current_connections_direct();
 
     match &relay_result {
         Ok(()) => debug!(user = %user, "Direct relay completed"),
@@ -118,10 +197,17 @@ fn get_dc_addr_static(dc_idx: i16, config: &ProxyConfig) -> Result<SocketAddr> {
     // Unknown DC requested by client without override: log and fall back.
     if !config.dc_overrides.contains_key(&dc_key) {
         warn!(dc_idx = dc_idx, "Requested non-standard DC with no override; falling back to default cluster");
-        if let Some(path) = &config.general.unknown_dc_log_path
-            && let Ok(mut file) = OpenOptions::new().create(true).append(true).open(path)
+        if config.general.unknown_dc_file_log_enabled
+            && let Some(path) = &config.general.unknown_dc_log_path
+            && should_log_unknown_dc(dc_idx)
+            && let Ok(handle) = tokio::runtime::Handle::try_current()
         {
-            let _ = writeln!(file, "dc_idx={dc_idx}");
+            let path = path.clone();
+            handle.spawn_blocking(move || {
+                if let Ok(mut file) = OpenOptions::new().create(true).append(true).open(path) {
+                    let _ = writeln!(file, "dc_idx={dc_idx}");
+                }
+            });
         }
     }
 
@@ -129,7 +215,7 @@ fn get_dc_addr_static(dc_idx: i16, config: &ProxyConfig) -> Result<SocketAddr> {
     let fallback_idx = if default_dc >= 1 && default_dc <= num_dcs {
         default_dc - 1
     } else {
-        1
+        0
     };
 
     info!(
@@ -157,8 +243,6 @@ async fn do_tg_handshake_static(
     let (nonce, _tg_enc_key, _tg_enc_iv, _tg_dec_key, _tg_dec_iv) = generate_tg_nonce(
         success.proto_tag,
         success.dc_idx,
-        &success.dec_key,
-        success.dec_iv,
         &success.enc_key,
         success.enc_iv,
         rng,
@@ -184,3 +268,7 @@ async fn do_tg_handshake_static(
         CryptoWriter::new(write_half, tg_encryptor, max_pending),
     ))
 }
+
+#[cfg(test)]
+#[path = "direct_relay_security_tests.rs"]
+mod security_tests;

src/proxy/direct_relay_security_tests.rs

@@ -0,0 +1,51 @@
+use super::*;
+
+#[test]
+fn unknown_dc_log_is_deduplicated_per_dc_idx() {
+    let _guard = unknown_dc_test_lock()
+        .lock()
+        .expect("unknown dc test lock must be available");
+    clear_unknown_dc_log_cache_for_testing();
+
+    assert!(should_log_unknown_dc(777));
+    assert!(
+        !should_log_unknown_dc(777),
+        "same unknown dc_idx must not be logged repeatedly"
+    );
+    assert!(
+        should_log_unknown_dc(778),
+        "different unknown dc_idx must still be loggable"
+    );
+}
+
+#[test]
+fn unknown_dc_log_respects_distinct_limit() {
+    let _guard = unknown_dc_test_lock()
+        .lock()
+        .expect("unknown dc test lock must be available");
+    clear_unknown_dc_log_cache_for_testing();
+
+    for dc in 1..=UNKNOWN_DC_LOG_DISTINCT_LIMIT {
+        assert!(
+            should_log_unknown_dc(dc as i16),
+            "expected first-time unknown dc_idx to be loggable"
+        );
+    }
+
+    assert!(
+        !should_log_unknown_dc(i16::MAX),
+        "distinct unknown dc_idx entries above limit must not be logged"
+    );
+}
+
+#[test]
+fn fallback_dc_never_panics_with_single_dc_list() {
+    let mut cfg = ProxyConfig::default();
+    cfg.network.prefer = 6;
+    cfg.network.ipv6 = Some(true);
+    cfg.default_dc = Some(42);
+
+    let addr = get_dc_addr_static(999, &cfg).expect("fallback dc must resolve safely");
+    let expected = SocketAddr::new(TG_DATACENTERS_V6[0], TG_DATACENTER_PORT);
+    assert_eq!(addr, expected);
+}

src/proxy/handshake.rs

@@ -3,10 +3,17 @@
 #![allow(dead_code)]
 
 use std::net::SocketAddr;
+use std::collections::HashSet;
+use std::net::{IpAddr, Ipv6Addr};
 use std::sync::Arc;
-use std::time::Duration;
+use std::sync::{Mutex, OnceLock};
+use std::collections::hash_map::DefaultHasher;
+use std::hash::{Hash, Hasher};
+use std::time::{Duration, Instant};
+use dashmap::DashMap;
+use dashmap::mapref::entry::Entry;
 use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
-use tracing::{debug, warn, trace, info};
+use tracing::{debug, warn, trace};
 use zeroize::Zeroize;
 
 use crate::crypto::{sha256, AesCtr, SecureRandom};
@@ -19,11 +26,302 @@ use crate::stats::ReplayChecker;
 use crate::config::ProxyConfig;
 use crate::tls_front::{TlsFrontCache, emulator};
 
+const ACCESS_SECRET_BYTES: usize = 16;
+static INVALID_SECRET_WARNED: OnceLock<Mutex<HashSet<(String, String)>>> = OnceLock::new();
+
+const AUTH_PROBE_TRACK_RETENTION_SECS: u64 = 10 * 60;
+#[cfg(test)]
+const AUTH_PROBE_TRACK_MAX_ENTRIES: usize = 256;
+#[cfg(not(test))]
+const AUTH_PROBE_TRACK_MAX_ENTRIES: usize = 65_536;
+const AUTH_PROBE_PRUNE_SCAN_LIMIT: usize = 1_024;
+const AUTH_PROBE_BACKOFF_START_FAILS: u32 = 4;
+
+#[cfg(test)]
+const AUTH_PROBE_BACKOFF_BASE_MS: u64 = 1;
+#[cfg(not(test))]
+const AUTH_PROBE_BACKOFF_BASE_MS: u64 = 25;
+
+#[cfg(test)]
+const AUTH_PROBE_BACKOFF_MAX_MS: u64 = 16;
+#[cfg(not(test))]
+const AUTH_PROBE_BACKOFF_MAX_MS: u64 = 1_000;
+
+#[derive(Clone, Copy)]
+struct AuthProbeState {
+    fail_streak: u32,
+    blocked_until: Instant,
+    last_seen: Instant,
+}
+
+static AUTH_PROBE_STATE: OnceLock<DashMap<IpAddr, AuthProbeState>> = OnceLock::new();
+
+fn auth_probe_state_map() -> &'static DashMap<IpAddr, AuthProbeState> {
+    AUTH_PROBE_STATE.get_or_init(DashMap::new)
+}
+
+fn normalize_auth_probe_ip(peer_ip: IpAddr) -> IpAddr {
+    match peer_ip {
+        IpAddr::V4(ip) => IpAddr::V4(ip),
+        IpAddr::V6(ip) => {
+            let [a, b, c, d, _, _, _, _] = ip.segments();
+            IpAddr::V6(Ipv6Addr::new(a, b, c, d, 0, 0, 0, 0))
+        }
+    }
+}
+
+fn auth_probe_backoff(fail_streak: u32) -> Duration {
+    if fail_streak < AUTH_PROBE_BACKOFF_START_FAILS {
+        return Duration::ZERO;
+    }
+    let shift = (fail_streak - AUTH_PROBE_BACKOFF_START_FAILS).min(10);
+    let multiplier = 1u64.checked_shl(shift).unwrap_or(u64::MAX);
+    let ms = AUTH_PROBE_BACKOFF_BASE_MS
+        .saturating_mul(multiplier)
+        .min(AUTH_PROBE_BACKOFF_MAX_MS);
+    Duration::from_millis(ms)
+}
+
+fn auth_probe_state_expired(state: &AuthProbeState, now: Instant) -> bool {
+    let retention = Duration::from_secs(AUTH_PROBE_TRACK_RETENTION_SECS);
+    now.duration_since(state.last_seen) > retention
+}
+
+fn auth_probe_eviction_offset(peer_ip: IpAddr, now: Instant) -> usize {
+    let mut hasher = DefaultHasher::new();
+    peer_ip.hash(&mut hasher);
+    now.hash(&mut hasher);
+    hasher.finish() as usize
+}
+
+fn auth_probe_is_throttled(peer_ip: IpAddr, now: Instant) -> bool {
+    let peer_ip = normalize_auth_probe_ip(peer_ip);
+    let state = auth_probe_state_map();
+    let Some(entry) = state.get(&peer_ip) else {
+        return false;
+    };
+    if auth_probe_state_expired(&entry, now) {
+        drop(entry);
+        state.remove(&peer_ip);
+        return false;
+    }
+    now < entry.blocked_until
+}
+
+fn auth_probe_record_failure(peer_ip: IpAddr, now: Instant) {
+    let peer_ip = normalize_auth_probe_ip(peer_ip);
+    let state = auth_probe_state_map();
+    auth_probe_record_failure_with_state(state, peer_ip, now);
+}
+
+fn auth_probe_record_failure_with_state(
+    state: &DashMap<IpAddr, AuthProbeState>,
+    peer_ip: IpAddr,
+    now: Instant,
+) {
+    let make_new_state = || AuthProbeState {
+        fail_streak: 1,
+        blocked_until: now + auth_probe_backoff(1),
+        last_seen: now,
+    };
+
+    let update_existing = |entry: &mut AuthProbeState| {
+        if auth_probe_state_expired(entry, now) {
+            *entry = make_new_state();
+        } else {
+            entry.fail_streak = entry.fail_streak.saturating_add(1);
+            entry.last_seen = now;
+            entry.blocked_until = now + auth_probe_backoff(entry.fail_streak);
+        }
+    };
+
+    match state.entry(peer_ip) {
+        Entry::Occupied(mut entry) => {
+            update_existing(entry.get_mut());
+            return;
+        }
+        Entry::Vacant(_) => {}
+    }
+
+    if state.len() >= AUTH_PROBE_TRACK_MAX_ENTRIES {
+        let mut stale_keys = Vec::new();
+        let mut eviction_candidates = Vec::new();
+        for entry in state.iter().take(AUTH_PROBE_PRUNE_SCAN_LIMIT) {
+            eviction_candidates.push(*entry.key());
+            if auth_probe_state_expired(entry.value(), now) {
+                stale_keys.push(*entry.key());
+            }
+        }
+        for stale_key in stale_keys {
+            state.remove(&stale_key);
+        }
+        if state.len() >= AUTH_PROBE_TRACK_MAX_ENTRIES {
+            if eviction_candidates.is_empty() {
+                return;
+            }
+            let idx = auth_probe_eviction_offset(peer_ip, now) % eviction_candidates.len();
+            let evict_key = eviction_candidates[idx];
+            state.remove(&evict_key);
+        }
+    }
+
+    match state.entry(peer_ip) {
+        Entry::Occupied(mut entry) => {
+            update_existing(entry.get_mut());
+        }
+        Entry::Vacant(entry) => {
+            entry.insert(make_new_state());
+        }
+    }
+}
+
+fn auth_probe_record_success(peer_ip: IpAddr) {
+    let peer_ip = normalize_auth_probe_ip(peer_ip);
+    let state = auth_probe_state_map();
+    state.remove(&peer_ip);
+}
+
+#[cfg(test)]
+fn clear_auth_probe_state_for_testing() {
+    if let Some(state) = AUTH_PROBE_STATE.get() {
+        state.clear();
+    }
+}
+
+#[cfg(test)]
+fn auth_probe_fail_streak_for_testing(peer_ip: IpAddr) -> Option<u32> {
+    let peer_ip = normalize_auth_probe_ip(peer_ip);
+    let state = AUTH_PROBE_STATE.get()?;
+    state.get(&peer_ip).map(|entry| entry.fail_streak)
+}
+
+#[cfg(test)]
+fn auth_probe_is_throttled_for_testing(peer_ip: IpAddr) -> bool {
+    auth_probe_is_throttled(peer_ip, Instant::now())
+}
+
+#[cfg(test)]
+fn auth_probe_test_lock() -> &'static Mutex<()> {
+    static TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    TEST_LOCK.get_or_init(|| Mutex::new(()))
+}
+
+#[cfg(test)]
+fn clear_warned_secrets_for_testing() {
+    if let Some(warned) = INVALID_SECRET_WARNED.get()
+        && let Ok(mut guard) = warned.lock()
+    {
+        guard.clear();
+    }
+}
+
+#[cfg(test)]
+fn warned_secrets_test_lock() -> &'static Mutex<()> {
+    static TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    TEST_LOCK.get_or_init(|| Mutex::new(()))
+}
+
+fn warn_invalid_secret_once(name: &str, reason: &str, expected: usize, got: Option<usize>) {
+    let key = (name.to_string(), reason.to_string());
+    let warned = INVALID_SECRET_WARNED.get_or_init(|| Mutex::new(HashSet::new()));
+    let should_warn = match warned.lock() {
+        Ok(mut guard) => guard.insert(key),
+        Err(_) => true,
+    };
+
+    if !should_warn {
+        return;
+    }
+
+    match got {
+        Some(actual) => {
+            warn!(
+                user = %name,
+                expected = expected,
+                got = actual,
+                "Skipping user: access secret has unexpected length"
+            );
+        }
+        None => {
+            warn!(
+                user = %name,
+                "Skipping user: access secret is not valid hex"
+            );
+        }
+    }
+}
+
+fn decode_user_secret(name: &str, secret_hex: &str) -> Option<Vec<u8>> {
+    match hex::decode(secret_hex) {
+        Ok(bytes) if bytes.len() == ACCESS_SECRET_BYTES => Some(bytes),
+        Ok(bytes) => {
+            warn_invalid_secret_once(
+                name,
+                "invalid_length",
+                ACCESS_SECRET_BYTES,
+                Some(bytes.len()),
+            );
+            None
+        }
+        Err(_) => {
+            warn_invalid_secret_once(name, "invalid_hex", ACCESS_SECRET_BYTES, None);
+            None
+        }
+    }
+}
+
+// Decide whether a client-supplied proto tag is allowed given the configured
+// proxy modes and the transport that carried the handshake.
+//
+// A common mistake is to treat `modes.tls` and `modes.secure` as interchangeable
+// even though they correspond to different transport profiles: `modes.tls` is
+// for the TLS-fronted (EE-TLS) path, while `modes.secure` is for direct MTProto
+// over TCP (DD). Enforcing this separation prevents an attacker from using a
+// TLS-capable client to bypass the operator intent for the direct MTProto mode,
+// and vice versa.
+fn mode_enabled_for_proto(config: &ProxyConfig, proto_tag: ProtoTag, is_tls: bool) -> bool {
+    match proto_tag {
+        ProtoTag::Secure => {
+            if is_tls {
+                config.general.modes.tls
+            } else {
+                config.general.modes.secure
+            }
+        }
+        ProtoTag::Intermediate | ProtoTag::Abridged => config.general.modes.classic,
+    }
+}
+
+fn decode_user_secrets(
+    config: &ProxyConfig,
+    preferred_user: Option<&str>,
+) -> Vec<(String, Vec<u8>)> {
+    let mut secrets = Vec::with_capacity(config.access.users.len());
+
+    if let Some(preferred) = preferred_user
+        && let Some(secret_hex) = config.access.users.get(preferred)
+        && let Some(bytes) = decode_user_secret(preferred, secret_hex)
+    {
+        secrets.push((preferred.to_string(), bytes));
+    }
+
+    for (name, secret_hex) in &config.access.users {
+        if preferred_user.is_some_and(|preferred| preferred == name.as_str()) {
+            continue;
+        }
+        if let Some(bytes) = decode_user_secret(name, secret_hex) {
+            secrets.push((name.clone(), bytes));
+        }
+    }
+
+    secrets
+}
+
 /// Result of successful handshake
 ///
 /// Key material (`dec_key`, `dec_iv`, `enc_key`, `enc_iv`) is
 /// zeroized on drop.
-#[derive(Debug, Clone)]
+#[derive(Debug)]
 pub struct HandshakeSuccess {
     /// Authenticated user name
     pub user: String,
@@ -69,32 +367,27 @@ where
 {
     debug!(peer = %peer, handshake_len = handshake.len(), "Processing TLS handshake");
 
+    if auth_probe_is_throttled(peer.ip(), Instant::now()) {
+        debug!(peer = %peer, "TLS handshake rejected by pre-auth probe throttle");
+        return HandshakeResult::BadClient { reader, writer };
+    }
+
     if handshake.len() < tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 {
         debug!(peer = %peer, "TLS handshake too short");
         return HandshakeResult::BadClient { reader, writer };
     }
 
-    let digest = &handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN];
-    let digest_half = &digest[..tls::TLS_DIGEST_HALF_LEN];
+    let secrets = decode_user_secrets(config, None);
 
-    if replay_checker.check_and_add_tls_digest(digest_half) {
-        warn!(peer = %peer, "TLS replay attack detected (duplicate digest)");
-        return HandshakeResult::BadClient { reader, writer };
-    }
-
-    let secrets: Vec<(String, Vec<u8>)> = config.access.users.iter()
-        .filter_map(|(name, hex)| {
-            hex::decode(hex).ok().map(|bytes| (name.clone(), bytes))
-        })
-        .collect();
-
-    let validation = match tls::validate_tls_handshake(
+    let validation = match tls::validate_tls_handshake_with_replay_window(
         handshake,
         &secrets,
         config.access.ignore_time_skew,
+        config.access.replay_window_secs,
     ) {
         Some(v) => v,
         None => {
+            auth_probe_record_failure(peer.ip(), Instant::now());
             debug!(
                 peer = %peer, 
                 ignore_time_skew = config.access.ignore_time_skew,
@@ -104,6 +397,15 @@ where
         }
     };
 
+    // Replay tracking is applied only after successful authentication to avoid
+    // letting unauthenticated probes evict valid entries from the replay cache.
+    let digest_half = &validation.digest[..tls::TLS_DIGEST_HALF_LEN];
+    if replay_checker.check_and_add_tls_digest(digest_half) {
+        auth_probe_record_failure(peer.ip(), Instant::now());
+        warn!(peer = %peer, "TLS replay attack detected (duplicate digest)");
+        return HandshakeResult::BadClient { reader, writer };
+    }
+
     let secret = match secrets.iter().find(|(name, _)| *name == validation.user) {
         Some((_, s)) => s,
         None => return HandshakeResult::BadClient { reader, writer },
@@ -145,6 +447,9 @@ where
             Some(b"h2".to_vec())
         } else if alpn_list.iter().any(|p| p == b"http/1.1") {
             Some(b"http/1.1".to_vec())
+        } else if !alpn_list.is_empty() {
+            debug!(peer = %peer, "Client ALPN list has no supported protocol; using masking fallback");
+            return HandshakeResult::BadClient { reader, writer };
         } else {
             None
         }
@@ -201,12 +506,14 @@ where
         return HandshakeResult::Error(ProxyError::Io(e));
     }
 
-    info!(
+    debug!(
         peer = %peer,
         user = %validation.user,
         "TLS handshake successful"
     );
 
+    auth_probe_record_success(peer.ip());
+
     HandshakeResult::Success((
         FakeTlsReader::new(reader),
         FakeTlsWriter::new(writer),
@@ -223,6 +530,7 @@ pub async fn handle_mtproto_handshake<R, W>(
     config: &ProxyConfig,
     replay_checker: &ReplayChecker,
     is_tls: bool,
+    preferred_user: Option<&str>,
 ) -> HandshakeResult<(CryptoReader<R>, CryptoWriter<W>, HandshakeSuccess), R, W>
 where
     R: AsyncRead + Unpin + Send,
@@ -230,20 +538,18 @@ where
 {
     trace!(peer = %peer, handshake = ?hex::encode(handshake), "MTProto handshake bytes");
 
-    let dec_prekey_iv = &handshake[SKIP_LEN..SKIP_LEN + PREKEY_LEN + IV_LEN];
-
-    if replay_checker.check_and_add_handshake(dec_prekey_iv) {
-        warn!(peer = %peer, "MTProto replay attack detected");
+    if auth_probe_is_throttled(peer.ip(), Instant::now()) {
+        debug!(peer = %peer, "MTProto handshake rejected by pre-auth probe throttle");
         return HandshakeResult::BadClient { reader, writer };
     }
 
+    let dec_prekey_iv = &handshake[SKIP_LEN..SKIP_LEN + PREKEY_LEN + IV_LEN];
+
     let enc_prekey_iv: Vec<u8> = dec_prekey_iv.iter().rev().copied().collect();
 
-    for (user, secret_hex) in &config.access.users {
-        let secret = match hex::decode(secret_hex) {
-            Ok(s) => s,
-            Err(_) => continue,
-        };
+    let decoded_users = decode_user_secrets(config, preferred_user);
+
+    for (user, secret) in decoded_users {
 
         let dec_prekey = &dec_prekey_iv[..PREKEY_LEN];
         let dec_iv_bytes = &dec_prekey_iv[PREKEY_LEN..];
@@ -253,39 +559,33 @@ where
         dec_key_input.extend_from_slice(&secret);
         let dec_key = sha256(&dec_key_input);
 
-        let dec_iv = u128::from_be_bytes(dec_iv_bytes.try_into().unwrap());
+        let mut dec_iv_arr = [0u8; IV_LEN];
+        dec_iv_arr.copy_from_slice(dec_iv_bytes);
+        let dec_iv = u128::from_be_bytes(dec_iv_arr);
 
         let mut decryptor = AesCtr::new(&dec_key, dec_iv);
         let decrypted = decryptor.decrypt(handshake);
 
-        let tag_bytes: [u8; 4] = decrypted[PROTO_TAG_POS..PROTO_TAG_POS + 4]
-            .try_into()
-            .unwrap();
+        let tag_bytes: [u8; 4] = [
+            decrypted[PROTO_TAG_POS],
+            decrypted[PROTO_TAG_POS + 1],
+            decrypted[PROTO_TAG_POS + 2],
+            decrypted[PROTO_TAG_POS + 3],
+        ];
 
         let proto_tag = match ProtoTag::from_bytes(tag_bytes) {
             Some(tag) => tag,
             None => continue,
         };
 
-        let mode_ok = match proto_tag {
-            ProtoTag::Secure => {
-                if is_tls {
-                    config.general.modes.tls || config.general.modes.secure
-                } else {
-                    config.general.modes.secure || config.general.modes.tls
-                }
-            }
-            ProtoTag::Intermediate | ProtoTag::Abridged => config.general.modes.classic,
-        };
+        let mode_ok = mode_enabled_for_proto(config, proto_tag, is_tls);
 
         if !mode_ok {
             debug!(peer = %peer, user = %user, proto = ?proto_tag, "Mode not enabled");
             continue;
         }
 
-        let dc_idx = i16::from_le_bytes(
-            decrypted[DC_IDX_POS..DC_IDX_POS + 2].try_into().unwrap()
-        );
+        let dc_idx = i16::from_le_bytes([decrypted[DC_IDX_POS], decrypted[DC_IDX_POS + 1]]);
 
         let enc_prekey = &enc_prekey_iv[..PREKEY_LEN];
         let enc_iv_bytes = &enc_prekey_iv[PREKEY_LEN..];
@@ -295,10 +595,24 @@ where
         enc_key_input.extend_from_slice(&secret);
         let enc_key = sha256(&enc_key_input);
 
-        let enc_iv = u128::from_be_bytes(enc_iv_bytes.try_into().unwrap());
+        let mut enc_iv_arr = [0u8; IV_LEN];
+        enc_iv_arr.copy_from_slice(enc_iv_bytes);
+        let enc_iv = u128::from_be_bytes(enc_iv_arr);
 
         let encryptor = AesCtr::new(&enc_key, enc_iv);
 
+// Apply replay tracking only after successful authentication.
+    //
+    // This ordering prevents an attacker from producing invalid handshakes that
+    // still collide with a valid handshake's replay slot and thus evict a valid
+    // entry from the cache. We accept the cost of performing the full
+    // authentication check first to avoid poisoning the replay cache.
+        if replay_checker.check_and_add_handshake(dec_prekey_iv) {
+            auth_probe_record_failure(peer.ip(), Instant::now());
+            warn!(peer = %peer, user = %user, "MTProto replay attack detected");
+            return HandshakeResult::BadClient { reader, writer };
+        }
+
         let success = HandshakeSuccess {
             user: user.clone(),
             dc_idx,
@@ -311,7 +625,7 @@ where
             is_tls,
         };
 
-        info!(
+        debug!(
             peer = %peer,
             user = %user,
             dc = dc_idx,
@@ -320,6 +634,8 @@ where
             "MTProto handshake successful"
         );
 
+        auth_probe_record_success(peer.ip());
+
         let max_pending = config.general.crypto_pending_buffer;
         return HandshakeResult::Success((
             CryptoReader::new(reader, decryptor),
@@ -328,6 +644,7 @@ where
         ));
     }
 
+    auth_probe_record_failure(peer.ip(), Instant::now());
     debug!(peer = %peer, "MTProto handshake: no matching user found");
     HandshakeResult::BadClient { reader, writer }
 }
@@ -336,8 +653,6 @@ where
 pub fn generate_tg_nonce(
     proto_tag: ProtoTag, 
     dc_idx: i16,
-    _client_dec_key: &[u8; 32],
-    _client_dec_iv: u128,
     client_enc_key: &[u8; 32],
     client_enc_iv: u128,
     rng: &SecureRandom,
@@ -345,14 +660,16 @@ pub fn generate_tg_nonce(
 ) -> ([u8; HANDSHAKE_LEN], [u8; 32], u128, [u8; 32], u128) {
     loop {
         let bytes = rng.bytes(HANDSHAKE_LEN);
-        let mut nonce: [u8; HANDSHAKE_LEN] = bytes.try_into().unwrap();
+        let Ok(mut nonce): Result<[u8; HANDSHAKE_LEN], _> = bytes.try_into() else {
+            continue;
+        };
 
         if RESERVED_NONCE_FIRST_BYTES.contains(&nonce[0]) { continue; }
 
-        let first_four: [u8; 4] = nonce[..4].try_into().unwrap();
+        let first_four: [u8; 4] = [nonce[0], nonce[1], nonce[2], nonce[3]];
         if RESERVED_NONCE_BEGINNINGS.contains(&first_four) { continue; }
 
-        let continue_four: [u8; 4] = nonce[4..8].try_into().unwrap();
+        let continue_four: [u8; 4] = [nonce[4], nonce[5], nonce[6], nonce[7]];
         if RESERVED_NONCE_CONTINUES.contains(&continue_four) { continue; }
 
         nonce[PROTO_TAG_POS..PROTO_TAG_POS + 4].copy_from_slice(&proto_tag.to_bytes());
@@ -370,11 +687,17 @@ pub fn generate_tg_nonce(
         let enc_key_iv = &nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN];
         let dec_key_iv: Vec<u8> = enc_key_iv.iter().rev().copied().collect();
 
-        let tg_enc_key: [u8; 32] = enc_key_iv[..KEY_LEN].try_into().unwrap();
-        let tg_enc_iv = u128::from_be_bytes(enc_key_iv[KEY_LEN..].try_into().unwrap());
+        let mut tg_enc_key = [0u8; 32];
+        tg_enc_key.copy_from_slice(&enc_key_iv[..KEY_LEN]);
+        let mut tg_enc_iv_arr = [0u8; IV_LEN];
+        tg_enc_iv_arr.copy_from_slice(&enc_key_iv[KEY_LEN..]);
+        let tg_enc_iv = u128::from_be_bytes(tg_enc_iv_arr);
 
-        let tg_dec_key: [u8; 32] = dec_key_iv[..KEY_LEN].try_into().unwrap();
-        let tg_dec_iv = u128::from_be_bytes(dec_key_iv[KEY_LEN..].try_into().unwrap());
+        let mut tg_dec_key = [0u8; 32];
+        tg_dec_key.copy_from_slice(&dec_key_iv[..KEY_LEN]);
+        let mut tg_dec_iv_arr = [0u8; IV_LEN];
+        tg_dec_iv_arr.copy_from_slice(&dec_key_iv[KEY_LEN..]);
+        let tg_dec_iv = u128::from_be_bytes(tg_dec_iv_arr);
 
         return (nonce, tg_enc_key, tg_enc_iv, tg_dec_key, tg_dec_iv);
     }
@@ -385,11 +708,17 @@ pub fn encrypt_tg_nonce_with_ciphers(nonce: &[u8; HANDSHAKE_LEN]) -> (Vec<u8>, A
     let enc_key_iv = &nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN];
     let dec_key_iv: Vec<u8> = enc_key_iv.iter().rev().copied().collect();
 
-    let enc_key: [u8; 32] = enc_key_iv[..KEY_LEN].try_into().unwrap();
-    let enc_iv = u128::from_be_bytes(enc_key_iv[KEY_LEN..].try_into().unwrap());
+    let mut enc_key = [0u8; 32];
+    enc_key.copy_from_slice(&enc_key_iv[..KEY_LEN]);
+    let mut enc_iv_arr = [0u8; IV_LEN];
+    enc_iv_arr.copy_from_slice(&enc_key_iv[KEY_LEN..]);
+    let enc_iv = u128::from_be_bytes(enc_iv_arr);
 
-    let dec_key: [u8; 32] = dec_key_iv[..KEY_LEN].try_into().unwrap();
-    let dec_iv = u128::from_be_bytes(dec_key_iv[KEY_LEN..].try_into().unwrap());
+    let mut dec_key = [0u8; 32];
+    dec_key.copy_from_slice(&dec_key_iv[..KEY_LEN]);
+    let mut dec_iv_arr = [0u8; IV_LEN];
+    dec_iv_arr.copy_from_slice(&dec_key_iv[KEY_LEN..]);
+    let dec_iv = u128::from_be_bytes(dec_iv_arr);
 
     let mut encryptor = AesCtr::new(&enc_key, enc_iv);
     let encrypted_full = encryptor.encrypt(nonce);  // counter: 0 → 4
@@ -409,80 +738,15 @@ pub fn encrypt_tg_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> Vec<u8> {
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
+#[path = "handshake_security_tests.rs"]
+mod security_tests;
 
-    #[test]
-    fn test_generate_tg_nonce() {
-        let client_dec_key = [0x42u8; 32];
-        let client_dec_iv = 12345u128;
-        let client_enc_key = [0x24u8; 32];
-        let client_enc_iv = 54321u128;
+/// Compile-time guard: HandshakeSuccess holds cryptographic key material and
+/// must never be Copy.  A Copy impl would allow silent key duplication,
+/// undermining the zeroize-on-drop guarantee.
+mod compile_time_security_checks {
+    use super::HandshakeSuccess;
+    use static_assertions::assert_not_impl_all;
 
-        let rng = SecureRandom::new();
-        let (nonce, _tg_enc_key, _tg_enc_iv, _tg_dec_key, _tg_dec_iv) = 
-            generate_tg_nonce(
-                ProtoTag::Secure,
-                2,
-                &client_dec_key,
-                client_dec_iv,
-                &client_enc_key,
-                client_enc_iv,
-                &rng,
-                false,
-            );
-
-        assert_eq!(nonce.len(), HANDSHAKE_LEN);
-
-        let tag_bytes: [u8; 4] = nonce[PROTO_TAG_POS..PROTO_TAG_POS + 4].try_into().unwrap();
-        assert_eq!(ProtoTag::from_bytes(tag_bytes), Some(ProtoTag::Secure));
-    }
-
-    #[test]
-    fn test_encrypt_tg_nonce() {
-        let client_dec_key = [0x42u8; 32];
-        let client_dec_iv = 12345u128;
-        let client_enc_key = [0x24u8; 32];
-        let client_enc_iv = 54321u128;
-
-        let rng = SecureRandom::new();
-        let (nonce, _, _, _, _) = 
-            generate_tg_nonce(
-                ProtoTag::Secure,
-                2,
-                &client_dec_key,
-                client_dec_iv,
-                &client_enc_key,
-                client_enc_iv,
-                &rng,
-                false,
-            );
-
-        let encrypted = encrypt_tg_nonce(&nonce);
-
-        assert_eq!(encrypted.len(), HANDSHAKE_LEN);
-        assert_eq!(&encrypted[..PROTO_TAG_POS], &nonce[..PROTO_TAG_POS]);
-        assert_ne!(&encrypted[PROTO_TAG_POS..], &nonce[PROTO_TAG_POS..]);
-    }
-
-    #[test]
-    fn test_handshake_success_zeroize_on_drop() {
-        let success = HandshakeSuccess {
-            user: "test".to_string(),
-            dc_idx: 2,
-            proto_tag: ProtoTag::Secure,
-            dec_key: [0xAA; 32],
-            dec_iv: 0xBBBBBBBB,
-            enc_key: [0xCC; 32],
-            enc_iv: 0xDDDDDDDD,
-            peer: "127.0.0.1:1234".parse().unwrap(),
-            is_tls: true,
-        };
-
-        assert_eq!(success.dec_key, [0xAA; 32]);
-        assert_eq!(success.enc_key, [0xCC; 32]);
-
-        drop(success);
-        // Drop impl zeroizes key material without panic
-    }
+    assert_not_impl_all!(HandshakeSuccess: Copy, Clone);
 }

src/proxy/masking.rs

@@ -14,12 +14,41 @@ use crate::network::dns_overrides::resolve_socket_addr;
 use crate::stats::beobachten::BeobachtenStore;
 use crate::transport::proxy_protocol::{ProxyProtocolV1Builder, ProxyProtocolV2Builder};
 
+#[cfg(not(test))]
 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);
+#[cfg(test)]
+const MASK_RELAY_TIMEOUT: Duration = Duration::from_millis(200);
 const MASK_BUFFER_SIZE: usize = 8192;
 
+async fn write_proxy_header_with_timeout<W>(mask_write: &mut W, header: &[u8]) -> bool
+where
+    W: AsyncWrite + Unpin,
+{
+    match timeout(MASK_TIMEOUT, mask_write.write_all(header)).await {
+        Ok(Ok(())) => true,
+        Ok(Err(_)) => false,
+        Err(_) => {
+            debug!("Timeout writing proxy protocol header to mask backend");
+            false
+        }
+    }
+}
+
+async fn consume_client_data_with_timeout<R>(reader: R)
+where
+    R: AsyncRead + Unpin,
+{
+    if timeout(MASK_RELAY_TIMEOUT, consume_client_data(reader)).await.is_err() {
+        debug!("Timed out while consuming client data on masking fallback path");
+    }
+}
+
 /// Detect client type based on initial data
 fn detect_client_type(data: &[u8]) -> &'static str {
     // Check for HTTP request
@@ -71,7 +100,7 @@ where
 
     if !config.censorship.mask {
         // Masking disabled, just consume data
-        consume_client_data(reader).await;
+        consume_client_data_with_timeout(reader).await;
         return;
     }
 
@@ -107,7 +136,7 @@ where
                     }
                 };
                 if let Some(header) = proxy_header {
-                    if mask_write.write_all(&header).await.is_err() {
+                    if !write_proxy_header_with_timeout(&mut mask_write, &header).await {
                         return;
                     }
                 }
@@ -117,11 +146,11 @@ where
             }
             Ok(Err(e)) => {
                 debug!(error = %e, "Failed to connect to mask unix socket");
-                consume_client_data(reader).await;
+                consume_client_data_with_timeout(reader).await;
             }
             Err(_) => {
                 debug!("Timeout connecting to mask unix socket");
-                consume_client_data(reader).await;
+                consume_client_data_with_timeout(reader).await;
             }
         }
         return;
@@ -166,7 +195,7 @@ where
 
             let (mask_read, mut mask_write) = stream.into_split();
             if let Some(header) = proxy_header {
-                if mask_write.write_all(&header).await.is_err() {
+                if !write_proxy_header_with_timeout(&mut mask_write, &header).await {
                     return;
                 }
             }
@@ -176,11 +205,11 @@ where
         }
         Ok(Err(e)) => {
             debug!(error = %e, "Failed to connect to mask host");
-            consume_client_data(reader).await;
+            consume_client_data_with_timeout(reader).await;
         }
         Err(_) => {
             debug!("Timeout connecting to mask host");
-            consume_client_data(reader).await;
+            consume_client_data_with_timeout(reader).await;
         }
     }
 }
@@ -203,47 +232,20 @@ where
     if mask_write.write_all(initial_data).await.is_err() {
         return;
     }
-
-    // Relay traffic
-    let c2m = tokio::spawn(async move {
-        let mut buf = vec![0u8; MASK_BUFFER_SIZE];
-        loop {
-            match reader.read(&mut buf).await {
-                Ok(0) | Err(_) => {
-                    let _ = mask_write.shutdown().await;
-                    break;
-                }
-                Ok(n) => {
-                    if mask_write.write_all(&buf[..n]).await.is_err() {
-                        break;
-                    }
-                }
-            }
-        }
-    });
-
-    let m2c = tokio::spawn(async move {
-        let mut buf = vec![0u8; MASK_BUFFER_SIZE];
-        loop {
-            match mask_read.read(&mut buf).await {
-                Ok(0) | Err(_) => {
-                    let _ = writer.shutdown().await;
-                    break;
-                }
-                Ok(n) => {
-                    if writer.write_all(&buf[..n]).await.is_err() {
-                        break;
-                    }
-                }
-            }
-        }
-    });
-
-    // Wait for either to complete
-    tokio::select! {
-        _ = c2m => {}
-        _ = m2c => {}
+    if mask_write.flush().await.is_err() {
+        return;
     }
+
+    let _ = tokio::join!(
+        async {
+            let _ = tokio::io::copy(&mut reader, &mut mask_write).await;
+            let _ = mask_write.shutdown().await;
+        },
+        async {
+            let _ = tokio::io::copy(&mut mask_read, &mut writer).await;
+            let _ = writer.shutdown().await;
+        }
+    );
 }
 
 /// Just consume all data from client without responding
@@ -255,3 +257,7 @@ async fn consume_client_data<R: AsyncRead + Unpin>(mut reader: R) {
         }
     }
 }
+
+#[cfg(test)]
+#[path = "masking_security_tests.rs"]
+mod security_tests;

src/proxy/masking_security_tests.rs

@@ -0,0 +1,731 @@
+use super::*;
+use crate::config::ProxyConfig;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::io::{duplex, AsyncBufReadExt, BufReader};
+use tokio::net::TcpListener;
+#[cfg(unix)]
+use tokio::net::UnixListener;
+use tokio::time::{sleep, timeout, Duration};
+
+#[tokio::test]
+async fn bad_client_probe_is_forwarded_verbatim_to_mask_backend() {
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let backend_addr = listener.local_addr().unwrap();
+    let probe = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
+    let backend_reply = b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK".to_vec();
+
+    let accept_task = tokio::spawn({
+        let probe = probe.clone();
+        let backend_reply = backend_reply.clone();
+        async move {
+            let (mut stream, _) = listener.accept().await.unwrap();
+            let mut received = vec![0u8; probe.len()];
+            stream.read_exact(&mut received).await.unwrap();
+            assert_eq!(received, probe);
+            stream.write_all(&backend_reply).await.unwrap();
+        }
+    });
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = true;
+    config.censorship.mask_host = Some("127.0.0.1".to_string());
+    config.censorship.mask_port = backend_addr.port();
+    config.censorship.mask_unix_sock = None;
+    config.censorship.mask_proxy_protocol = 0;
+
+    let peer: SocketAddr = "203.0.113.10:42424".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    let (client_reader, _client_writer) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
+
+    let beobachten = BeobachtenStore::new();
+    handle_bad_client(
+        client_reader,
+        client_visible_writer,
+        &probe,
+        peer,
+        local_addr,
+        &config,
+        &beobachten,
+    )
+    .await;
+
+    let mut observed = vec![0u8; backend_reply.len()];
+    client_visible_reader.read_exact(&mut observed).await.unwrap();
+    assert_eq!(observed, backend_reply);
+    accept_task.await.unwrap();
+}
+
+#[tokio::test]
+async fn tls_scanner_probe_keeps_http_like_fallback_surface() {
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let backend_addr = listener.local_addr().unwrap();
+    let probe = vec![0x16, 0x03, 0x01, 0x00, 0x10, 0x01, 0x02, 0x03, 0x04];
+    let backend_reply = b"HTTP/1.1 400 Bad Request\r\nContent-Length: 0\r\n\r\n".to_vec();
+
+    let accept_task = tokio::spawn({
+        let probe = probe.clone();
+        let backend_reply = backend_reply.clone();
+        async move {
+            let (mut stream, _) = listener.accept().await.unwrap();
+            let mut received = vec![0u8; probe.len()];
+            stream.read_exact(&mut received).await.unwrap();
+            assert_eq!(received, probe);
+            stream.write_all(&backend_reply).await.unwrap();
+        }
+    });
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = 1;
+    config.censorship.mask = true;
+    config.censorship.mask_host = Some("127.0.0.1".to_string());
+    config.censorship.mask_port = backend_addr.port();
+    config.censorship.mask_unix_sock = None;
+    config.censorship.mask_proxy_protocol = 0;
+
+    let peer: SocketAddr = "198.51.100.44:55221".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    let (client_reader, _client_writer) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
+
+    let beobachten = BeobachtenStore::new();
+    handle_bad_client(
+        client_reader,
+        client_visible_writer,
+        &probe,
+        peer,
+        local_addr,
+        &config,
+        &beobachten,
+    )
+    .await;
+
+    let mut observed = vec![0u8; backend_reply.len()];
+    client_visible_reader.read_exact(&mut observed).await.unwrap();
+    assert_eq!(observed, backend_reply);
+
+    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
+    assert!(snapshot.contains("[TLS-scanner]"));
+    assert!(snapshot.contains("198.51.100.44-1"));
+    accept_task.await.unwrap();
+}
+
+#[test]
+fn detect_client_type_covers_ssh_port_scanner_and_unknown() {
+    assert_eq!(detect_client_type(b"SSH-2.0-OpenSSH_9.7"), "SSH");
+    assert_eq!(detect_client_type(b"\x01\x02\x03"), "port-scanner");
+    assert_eq!(detect_client_type(b"random-binary-payload"), "unknown");
+}
+
+#[test]
+fn detect_client_type_len_boundary_9_vs_10_bytes() {
+    assert_eq!(detect_client_type(b"123456789"), "port-scanner");
+    assert_eq!(detect_client_type(b"1234567890"), "unknown");
+}
+
+#[tokio::test]
+async fn beobachten_records_scanner_class_when_mask_is_disabled() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = true;
+    config.general.beobachten_minutes = 1;
+    config.censorship.mask = false;
+
+    let peer: SocketAddr = "203.0.113.99:41234".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+    let initial = b"SSH-2.0-probe";
+
+    let (mut client_reader_side, client_reader) = duplex(256);
+    let (_client_visible_reader, client_visible_writer) = duplex(256);
+    let beobachten = BeobachtenStore::new();
+
+    let task = tokio::spawn(async move {
+        handle_bad_client(
+            client_reader,
+            client_visible_writer,
+            initial,
+            peer,
+            local_addr,
+            &config,
+            &beobachten,
+        )
+        .await;
+        beobachten
+    });
+
+    client_reader_side.write_all(b"noise").await.unwrap();
+    drop(client_reader_side);
+
+    let beobachten = timeout(Duration::from_secs(3), task).await.unwrap().unwrap();
+    let snapshot = beobachten.snapshot_text(Duration::from_secs(60));
+    assert!(snapshot.contains("[SSH]"));
+    assert!(snapshot.contains("203.0.113.99-1"));
+}
+
+#[tokio::test]
+async fn backend_unavailable_falls_back_to_silent_consume() {
+    let temp_listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let unused_port = temp_listener.local_addr().unwrap().port();
+    drop(temp_listener);
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = true;
+    config.censorship.mask_host = Some("127.0.0.1".to_string());
+    config.censorship.mask_port = unused_port;
+    config.censorship.mask_unix_sock = None;
+    config.censorship.mask_proxy_protocol = 0;
+
+    let peer: SocketAddr = "203.0.113.11:42425".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+    let probe = b"GET /probe HTTP/1.1\r\nHost: x\r\n\r\n";
+
+    let (mut client_reader_side, client_reader) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(256);
+    let beobachten = BeobachtenStore::new();
+
+    let task = tokio::spawn(async move {
+        handle_bad_client(
+            client_reader,
+            client_visible_writer,
+            probe,
+            peer,
+            local_addr,
+            &config,
+            &beobachten,
+        )
+        .await;
+    });
+
+    client_reader_side.write_all(b"noise").await.unwrap();
+    drop(client_reader_side);
+
+    timeout(Duration::from_secs(3), task).await.unwrap().unwrap();
+
+    let mut buf = [0u8; 1];
+    let n = timeout(Duration::from_secs(1), client_visible_reader.read(&mut buf))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(n, 0);
+}
+
+#[tokio::test]
+async fn mask_disabled_consumes_client_data_without_response() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = false;
+
+    let peer: SocketAddr = "198.51.100.12:45454".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+    let initial = b"scanner";
+
+    let (mut client_reader_side, client_reader) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(256);
+    let beobachten = BeobachtenStore::new();
+
+    let task = tokio::spawn(async move {
+        handle_bad_client(
+            client_reader,
+            client_visible_writer,
+            initial,
+            peer,
+            local_addr,
+            &config,
+            &beobachten,
+        )
+        .await;
+    });
+
+    client_reader_side.write_all(b"untrusted payload").await.unwrap();
+    drop(client_reader_side);
+
+    timeout(Duration::from_secs(3), task).await.unwrap().unwrap();
+
+    let mut buf = [0u8; 1];
+    let n = timeout(Duration::from_secs(1), client_visible_reader.read(&mut buf))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(n, 0);
+}
+
+#[tokio::test]
+async fn proxy_protocol_v1_header_is_sent_before_probe() {
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let backend_addr = listener.local_addr().unwrap();
+    let probe = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
+    let backend_reply = b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n".to_vec();
+
+    let accept_task = tokio::spawn({
+        let probe = probe.clone();
+        let backend_reply = backend_reply.clone();
+        async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut reader = BufReader::new(stream);
+
+            let mut header_line = Vec::new();
+            reader.read_until(b'\n', &mut header_line).await.unwrap();
+            let header_text = String::from_utf8(header_line.clone()).unwrap();
+            assert!(header_text.starts_with("PROXY TCP4 "));
+            assert!(header_text.ends_with("\r\n"));
+
+            let mut received_probe = vec![0u8; probe.len()];
+            reader.read_exact(&mut received_probe).await.unwrap();
+            assert_eq!(received_probe, probe);
+
+            let mut stream = reader.into_inner();
+            stream.write_all(&backend_reply).await.unwrap();
+        }
+    });
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = true;
+    config.censorship.mask_host = Some("127.0.0.1".to_string());
+    config.censorship.mask_port = backend_addr.port();
+    config.censorship.mask_unix_sock = None;
+    config.censorship.mask_proxy_protocol = 1;
+
+    let peer: SocketAddr = "203.0.113.15:50001".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    let (client_reader, _client_writer) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
+
+    let beobachten = BeobachtenStore::new();
+    handle_bad_client(
+        client_reader,
+        client_visible_writer,
+        &probe,
+        peer,
+        local_addr,
+        &config,
+        &beobachten,
+    )
+    .await;
+
+    let mut observed = vec![0u8; backend_reply.len()];
+    client_visible_reader.read_exact(&mut observed).await.unwrap();
+    assert_eq!(observed, backend_reply);
+    accept_task.await.unwrap();
+}
+
+#[tokio::test]
+async fn proxy_protocol_v2_header_is_sent_before_probe() {
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let backend_addr = listener.local_addr().unwrap();
+    let probe = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
+    let backend_reply = b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n".to_vec();
+
+    let accept_task = tokio::spawn({
+        let probe = probe.clone();
+        let backend_reply = backend_reply.clone();
+        async move {
+            let (mut stream, _) = listener.accept().await.unwrap();
+
+            let mut sig = [0u8; 12];
+            stream.read_exact(&mut sig).await.unwrap();
+            assert_eq!(&sig, b"\r\n\r\n\0\r\nQUIT\n");
+
+            let mut fixed = [0u8; 4];
+            stream.read_exact(&mut fixed).await.unwrap();
+            let addr_len = u16::from_be_bytes([fixed[2], fixed[3]]) as usize;
+
+            let mut addr_block = vec![0u8; addr_len];
+            stream.read_exact(&mut addr_block).await.unwrap();
+
+            let mut received_probe = vec![0u8; probe.len()];
+            stream.read_exact(&mut received_probe).await.unwrap();
+            assert_eq!(received_probe, probe);
+
+            stream.write_all(&backend_reply).await.unwrap();
+        }
+    });
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = true;
+    config.censorship.mask_host = Some("127.0.0.1".to_string());
+    config.censorship.mask_port = backend_addr.port();
+    config.censorship.mask_unix_sock = None;
+    config.censorship.mask_proxy_protocol = 2;
+
+    let peer: SocketAddr = "203.0.113.18:50004".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    let (client_reader, _client_writer) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
+
+    let beobachten = BeobachtenStore::new();
+    handle_bad_client(
+        client_reader,
+        client_visible_writer,
+        &probe,
+        peer,
+        local_addr,
+        &config,
+        &beobachten,
+    )
+    .await;
+
+    let mut observed = vec![0u8; backend_reply.len()];
+    client_visible_reader.read_exact(&mut observed).await.unwrap();
+    assert_eq!(observed, backend_reply);
+    accept_task.await.unwrap();
+}
+
+#[tokio::test]
+async fn proxy_protocol_v1_mixed_family_falls_back_to_unknown_header() {
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let backend_addr = listener.local_addr().unwrap();
+    let probe = b"GET /mix HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
+    let backend_reply = b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n".to_vec();
+
+    let accept_task = tokio::spawn({
+        let probe = probe.clone();
+        let backend_reply = backend_reply.clone();
+        async move {
+            let (stream, _) = listener.accept().await.unwrap();
+            let mut reader = BufReader::new(stream);
+
+            let mut header_line = Vec::new();
+            reader.read_until(b'\n', &mut header_line).await.unwrap();
+            let header_text = String::from_utf8(header_line).unwrap();
+            assert_eq!(header_text, "PROXY UNKNOWN\r\n");
+
+            let mut received_probe = vec![0u8; probe.len()];
+            reader.read_exact(&mut received_probe).await.unwrap();
+            assert_eq!(received_probe, probe);
+
+            let mut stream = reader.into_inner();
+            stream.write_all(&backend_reply).await.unwrap();
+        }
+    });
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = true;
+    config.censorship.mask_host = Some("127.0.0.1".to_string());
+    config.censorship.mask_port = backend_addr.port();
+    config.censorship.mask_unix_sock = None;
+    config.censorship.mask_proxy_protocol = 1;
+
+    let peer: SocketAddr = "203.0.113.20:50006".parse().unwrap();
+    let local_addr: SocketAddr = "[::1]:443".parse().unwrap();
+
+    let (client_reader, _client_writer) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
+
+    let beobachten = BeobachtenStore::new();
+    handle_bad_client(
+        client_reader,
+        client_visible_writer,
+        &probe,
+        peer,
+        local_addr,
+        &config,
+        &beobachten,
+    )
+    .await;
+
+    let mut observed = vec![0u8; backend_reply.len()];
+    client_visible_reader.read_exact(&mut observed).await.unwrap();
+    assert_eq!(observed, backend_reply);
+    accept_task.await.unwrap();
+}
+
+#[cfg(unix)]
+#[tokio::test]
+async fn unix_socket_mask_path_forwards_probe_and_response() {
+    let sock_path = format!("/tmp/telemt-mask-test-{}-{}.sock", std::process::id(), rand::random::<u64>());
+    let _ = std::fs::remove_file(&sock_path);
+
+    let listener = UnixListener::bind(&sock_path).unwrap();
+    let probe = b"GET /unix HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
+    let backend_reply = b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK".to_vec();
+
+    let accept_task = tokio::spawn({
+        let probe = probe.clone();
+        let backend_reply = backend_reply.clone();
+        async move {
+            let (mut stream, _) = listener.accept().await.unwrap();
+            let mut received = vec![0u8; probe.len()];
+            stream.read_exact(&mut received).await.unwrap();
+            assert_eq!(received, probe);
+            stream.write_all(&backend_reply).await.unwrap();
+        }
+    });
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = true;
+    config.censorship.mask_unix_sock = Some(sock_path.clone());
+    config.censorship.mask_proxy_protocol = 0;
+
+    let peer: SocketAddr = "203.0.113.30:50010".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    let (client_reader, _client_writer) = duplex(256);
+    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
+
+    let beobachten = BeobachtenStore::new();
+    handle_bad_client(
+        client_reader,
+        client_visible_writer,
+        &probe,
+        peer,
+        local_addr,
+        &config,
+        &beobachten,
+    )
+    .await;
+
+    let mut observed = vec![0u8; backend_reply.len()];
+    client_visible_reader.read_exact(&mut observed).await.unwrap();
+    assert_eq!(observed, backend_reply);
+
+    accept_task.await.unwrap();
+    let _ = std::fs::remove_file(sock_path);
+}
+
+#[tokio::test]
+async fn mask_disabled_slowloris_connection_is_closed_by_consume_timeout() {
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = false;
+
+    let peer: SocketAddr = "198.51.100.33:45455".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    let (_client_reader_side, client_reader) = duplex(256);
+    let (_client_visible_reader, client_visible_writer) = duplex(256);
+    let beobachten = BeobachtenStore::new();
+
+    let task = tokio::spawn(async move {
+        handle_bad_client(
+            client_reader,
+            client_visible_writer,
+            b"slowloris",
+            peer,
+            local_addr,
+            &config,
+            &beobachten,
+        )
+        .await;
+    });
+
+    timeout(Duration::from_secs(1), task).await.unwrap().unwrap();
+}
+
+struct PendingWriter;
+
+impl tokio::io::AsyncWrite for PendingWriter {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        _buf: &[u8],
+    ) -> Poll<std::io::Result<usize>> {
+        Poll::Pending
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Poll::Ready(Ok(()))
+    }
+
+    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Poll::Ready(Ok(()))
+    }
+}
+
+struct DropTrackedPendingReader {
+    dropped: Arc<AtomicBool>,
+}
+
+impl tokio::io::AsyncRead for DropTrackedPendingReader {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        _buf: &mut tokio::io::ReadBuf<'_>,
+    ) -> Poll<std::io::Result<()>> {
+        Poll::Pending
+    }
+}
+
+impl Drop for DropTrackedPendingReader {
+    fn drop(&mut self) {
+        self.dropped.store(true, Ordering::SeqCst);
+    }
+}
+
+struct DropTrackedPendingWriter {
+    dropped: Arc<AtomicBool>,
+}
+
+impl tokio::io::AsyncWrite for DropTrackedPendingWriter {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+        _buf: &[u8],
+    ) -> Poll<std::io::Result<usize>> {
+        Poll::Pending
+    }
+
+    fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Poll::Ready(Ok(()))
+    }
+
+    fn poll_shutdown(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<std::io::Result<()>> {
+        Poll::Ready(Ok(()))
+    }
+}
+
+impl Drop for DropTrackedPendingWriter {
+    fn drop(&mut self) {
+        self.dropped.store(true, Ordering::SeqCst);
+    }
+}
+
+#[tokio::test]
+async fn proxy_header_write_timeout_returns_false() {
+    let mut writer = PendingWriter;
+    let ok = write_proxy_header_with_timeout(&mut writer, b"PROXY UNKNOWN\r\n").await;
+    assert!(!ok, "Proxy header writes that never complete must time out");
+}
+
+#[tokio::test]
+async fn relay_to_mask_keeps_backend_to_client_flow_when_client_to_backend_stalls() {
+    let (mut client_feed_writer, client_feed_reader) = duplex(64);
+    let (mut client_visible_reader, client_visible_writer) = duplex(64);
+    let (mut backend_feed_writer, backend_feed_reader) = duplex(64);
+
+    // Make client->mask direction immediately active so the c2m path blocks on PendingWriter.
+    client_feed_writer.write_all(b"X").await.unwrap();
+
+    let relay = tokio::spawn(async move {
+        relay_to_mask(
+            client_feed_reader,
+            client_visible_writer,
+            backend_feed_reader,
+            PendingWriter,
+            b"",
+        )
+        .await;
+    });
+
+    // Allow relay tasks to start, then emulate mask backend response.
+    sleep(Duration::from_millis(20)).await;
+    backend_feed_writer.write_all(b"HTTP/1.1 200 OK\r\n\r\n").await.unwrap();
+    backend_feed_writer.shutdown().await.unwrap();
+
+    let mut observed = vec![0u8; 19];
+    timeout(Duration::from_secs(1), client_visible_reader.read_exact(&mut observed))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(observed, b"HTTP/1.1 200 OK\r\n\r\n");
+
+    relay.abort();
+    let _ = relay.await;
+}
+
+#[tokio::test]
+async fn relay_to_mask_preserves_backend_response_after_client_half_close() {
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let backend_addr = listener.local_addr().unwrap();
+    let request = b"GET / HTTP/1.1\r\nHost: front.example\r\n\r\n".to_vec();
+    let response = b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK".to_vec();
+
+    let backend_task = tokio::spawn({
+        let request = request.clone();
+        let response = response.clone();
+        async move {
+            let (mut stream, _) = listener.accept().await.unwrap();
+            let mut observed_req = vec![0u8; request.len()];
+            stream.read_exact(&mut observed_req).await.unwrap();
+            assert_eq!(observed_req, request);
+            stream.write_all(&response).await.unwrap();
+            stream.shutdown().await.unwrap();
+        }
+    });
+
+    let mut config = ProxyConfig::default();
+    config.general.beobachten = false;
+    config.censorship.mask = true;
+    config.censorship.mask_host = Some("127.0.0.1".to_string());
+    config.censorship.mask_port = backend_addr.port();
+    config.censorship.mask_unix_sock = None;
+    config.censorship.mask_proxy_protocol = 0;
+
+    let peer: SocketAddr = "203.0.113.77:55001".parse().unwrap();
+    let local_addr: SocketAddr = "127.0.0.1:443".parse().unwrap();
+
+    let (mut client_write, client_read) = duplex(1024);
+    let (mut client_visible_reader, client_visible_writer) = duplex(2048);
+    let beobachten = BeobachtenStore::new();
+
+    let fallback_task = tokio::spawn(async move {
+        handle_bad_client(
+            client_read,
+            client_visible_writer,
+            &request,
+            peer,
+            local_addr,
+            &config,
+            &beobachten,
+        )
+        .await;
+    });
+
+    client_write.shutdown().await.unwrap();
+
+    let mut observed_resp = vec![0u8; response.len()];
+    timeout(Duration::from_secs(1), client_visible_reader.read_exact(&mut observed_resp))
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(observed_resp, response);
+
+    timeout(Duration::from_secs(1), fallback_task).await.unwrap().unwrap();
+    timeout(Duration::from_secs(1), backend_task).await.unwrap().unwrap();
+}
+
+#[tokio::test]
+async fn relay_to_mask_timeout_cancels_and_drops_all_io_endpoints() {
+    let reader_dropped = Arc::new(AtomicBool::new(false));
+    let writer_dropped = Arc::new(AtomicBool::new(false));
+    let mask_reader_dropped = Arc::new(AtomicBool::new(false));
+    let mask_writer_dropped = Arc::new(AtomicBool::new(false));
+
+    let reader = DropTrackedPendingReader {
+        dropped: reader_dropped.clone(),
+    };
+    let writer = DropTrackedPendingWriter {
+        dropped: writer_dropped.clone(),
+    };
+    let mask_read = DropTrackedPendingReader {
+        dropped: mask_reader_dropped.clone(),
+    };
+    let mask_write = DropTrackedPendingWriter {
+        dropped: mask_writer_dropped.clone(),
+    };
+
+    let timed = timeout(
+        Duration::from_millis(40),
+        relay_to_mask(reader, writer, mask_read, mask_write, b""),
+    )
+    .await;
+
+    assert!(timed.is_err(), "stalled relay must be bounded by timeout");
+
+    assert!(reader_dropped.load(Ordering::SeqCst));
+    assert!(writer_dropped.load(Ordering::SeqCst));
+    assert!(mask_reader_dropped.load(Ordering::SeqCst));
+    assert!(mask_writer_dropped.load(Ordering::SeqCst));
+}

src/proxy/middle_relay.rs

@@ -1,35 +1,46 @@
-use std::collections::HashMap;
 use std::collections::hash_map::DefaultHasher;
 use std::hash::{Hash, Hasher};
 use std::net::{IpAddr, SocketAddr};
 use std::sync::atomic::{AtomicU64, Ordering};
-use std::sync::{Arc, Mutex, OnceLock};
+use std::sync::{Arc, OnceLock};
 use std::time::{Duration, Instant};
+#[cfg(test)]
+use std::sync::Mutex;
 
+use dashmap::DashMap;
 use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
-use tokio::sync::{mpsc, oneshot};
-use tracing::{debug, info, trace, warn};
+use tokio::sync::{mpsc, oneshot, watch};
+use tokio::time::timeout;
+use tracing::{debug, trace, warn};
 
 use crate::config::ProxyConfig;
 use crate::crypto::SecureRandom;
 use crate::error::{ProxyError, Result};
 use crate::protocol::constants::{*, secure_padding_len};
 use crate::proxy::handshake::HandshakeSuccess;
+use crate::proxy::route_mode::{
+    RelayRouteMode, RouteCutoverState, ROUTE_SWITCH_ERROR_MSG, affected_cutover_state,
+    cutover_stagger_delay,
+};
 use crate::stats::Stats;
-use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
+use crate::stream::{BufferPool, CryptoReader, CryptoWriter, PooledBuffer};
 use crate::transport::middle_proxy::{MePool, MeResponse, proto_flags_for_tag};
 
 enum C2MeCommand {
-    Data { payload: Vec<u8>, flags: u32 },
+    Data { payload: PooledBuffer, flags: u32 },
     Close,
 }
 
 const DESYNC_DEDUP_WINDOW: Duration = Duration::from_secs(60);
+const DESYNC_DEDUP_MAX_ENTRIES: usize = 65_536;
+const DESYNC_DEDUP_PRUNE_SCAN_LIMIT: usize = 1024;
 const DESYNC_ERROR_CLASS: &str = "frame_too_large_crypto_desync";
-const C2ME_CHANNEL_CAPACITY: usize = 1024;
+const C2ME_CHANNEL_CAPACITY_FALLBACK: usize = 128;
 const C2ME_SOFT_PRESSURE_MIN_FREE_SLOTS: usize = 64;
 const C2ME_SENDER_FAIRNESS_BUDGET: usize = 32;
-static DESYNC_DEDUP: OnceLock<Mutex<HashMap<u64, Instant>>> = OnceLock::new();
+const ME_D2C_FLUSH_BATCH_MAX_FRAMES_MIN: usize = 1;
+const ME_D2C_FLUSH_BATCH_MAX_BYTES_MIN: usize = 4096;
+static DESYNC_DEDUP: OnceLock<DashMap<u64, Instant>> = OnceLock::new();
 
 struct RelayForensicsState {
     trace_id: u64,
@@ -43,6 +54,31 @@ struct RelayForensicsState {
     desync_all_full: bool,
 }
 
+#[derive(Clone, Copy)]
+struct MeD2cFlushPolicy {
+    max_frames: usize,
+    max_bytes: usize,
+    max_delay: Duration,
+    ack_flush_immediate: bool,
+}
+
+impl MeD2cFlushPolicy {
+    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,
+        }
+    }
+}
+
 fn hash_value<T: Hash>(value: &T) -> u64 {
     let mut hasher = DefaultHasher::new();
     value.hash(&mut hasher);
@@ -58,24 +94,55 @@ fn should_emit_full_desync(key: u64, all_full: bool, now: Instant) -> bool {
         return true;
     }
 
-    let dedup = DESYNC_DEDUP.get_or_init(|| Mutex::new(HashMap::new()));
-    let mut guard = dedup.lock().expect("desync dedup mutex poisoned");
-    guard.retain(|_, seen_at| now.duration_since(*seen_at) < DESYNC_DEDUP_WINDOW);
+    let dedup = DESYNC_DEDUP.get_or_init(DashMap::new);
 
-    match guard.get_mut(&key) {
-        Some(seen_at) => {
-            if now.duration_since(*seen_at) >= DESYNC_DEDUP_WINDOW {
-                *seen_at = now;
-                true
-            } else {
-                false
+    if let Some(mut seen_at) = dedup.get_mut(&key) {
+        if now.duration_since(*seen_at) >= DESYNC_DEDUP_WINDOW {
+            *seen_at = now;
+            return true;
+        }
+        return false;
+    }
+
+    if dedup.len() >= DESYNC_DEDUP_MAX_ENTRIES {
+        let mut stale_keys = Vec::new();
+        let mut eviction_candidate = None;
+        for entry in dedup.iter().take(DESYNC_DEDUP_PRUNE_SCAN_LIMIT) {
+            if eviction_candidate.is_none() {
+                eviction_candidate = Some(*entry.key());
+            }
+            if now.duration_since(*entry.value()) >= DESYNC_DEDUP_WINDOW {
+                stale_keys.push(*entry.key());
             }
         }
-        None => {
-            guard.insert(key, now);
-            true
+        for stale_key in stale_keys {
+            dedup.remove(&stale_key);
+        }
+        if dedup.len() >= DESYNC_DEDUP_MAX_ENTRIES {
+            let Some(evict_key) = eviction_candidate else {
+                return false;
+            };
+            dedup.remove(&evict_key);
+            dedup.insert(key, now);
+            return false;
         }
     }
+
+    dedup.insert(key, now);
+    true
+}
+
+#[cfg(test)]
+fn clear_desync_dedup_for_testing() {
+    if let Some(dedup) = DESYNC_DEDUP.get() {
+        dedup.clear();
+    }
+}
+
+#[cfg(test)]
+fn desync_dedup_test_lock() -> &'static Mutex<()> {
+    static TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    TEST_LOCK.get_or_init(|| Mutex::new(()))
 }
 
 fn report_desync_frame_too_large(
@@ -197,9 +264,12 @@ pub(crate) async fn handle_via_middle_proxy<R, W>(
     me_pool: Arc<MePool>,
     stats: Arc<Stats>,
     config: Arc<ProxyConfig>,
-    _buffer_pool: Arc<BufferPool>,
+    buffer_pool: Arc<BufferPool>,
     local_addr: SocketAddr,
     rng: Arc<SecureRandom>,
+    mut route_rx: watch::Receiver<RouteCutoverState>,
+    route_snapshot: RouteCutoverState,
+    session_id: u64,
 ) -> Result<()>
 where
     R: AsyncRead + Unpin + Send + 'static,
@@ -210,7 +280,7 @@ where
     let proto_tag = success.proto_tag;
     let pool_generation = me_pool.current_generation();
 
-    info!(
+    debug!(
         user = %user,
         peer = %peer,
         dc = success.dc_idx,
@@ -236,7 +306,27 @@ where
     };
 
     stats.increment_user_connects(&user);
-    stats.increment_user_curr_connects(&user);
+    stats.increment_current_connections_me();
+
+    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"
+        );
+        tokio::time::sleep(delay).await;
+        let _ = me_pool.send_close(conn_id).await;
+        me_pool.registry().unregister(conn_id).await;
+        stats.decrement_current_connections_me();
+        return Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+    }
 
     // Per-user ad_tag from access.user_ad_tags; fallback to general.ad_tag (hot-reloadable)
     let user_tag: Option<Vec<u8>> = config
@@ -269,7 +359,11 @@ where
 
     let frame_limit = config.general.max_client_frame;
 
-    let (c2me_tx, mut c2me_rx) = mpsc::channel::<C2MeCommand>(C2ME_CHANNEL_CAPACITY);
+    let c2me_channel_capacity = config
+        .general
+        .me_c2me_channel_capacity
+        .max(C2ME_CHANNEL_CAPACITY_FALLBACK);
+    let (c2me_tx, mut c2me_rx) = mpsc::channel::<C2MeCommand>(c2me_channel_capacity);
     let me_pool_c2me = me_pool.clone();
     let effective_tag = effective_tag;
     let c2me_sender = tokio::spawn(async move {
@@ -282,7 +376,7 @@ where
                         success.dc_idx,
                         peer,
                         translated_local_addr,
-                        &payload,
+                        payload.as_ref(),
                         flags,
                         effective_tag.as_deref(),
                     ).await?;
@@ -307,71 +401,152 @@ where
     let rng_clone = rng.clone();
     let user_clone = user.clone();
     let bytes_me2c_clone = bytes_me2c.clone();
+    let d2c_flush_policy = MeD2cFlushPolicy::from_config(&config);
     let me_writer = tokio::spawn(async move {
         let mut writer = crypto_writer;
         let mut frame_buf = Vec::with_capacity(16 * 1024);
         loop {
             tokio::select! {
                 msg = me_rx_task.recv() => {
-                    match msg {
-                        Some(MeResponse::Data { flags, data }) => {
-                            trace!(conn_id, bytes = data.len(), flags, "ME->C data");
-                            bytes_me2c_clone.fetch_add(data.len() as u64, Ordering::Relaxed);
-                            stats_clone.add_user_octets_to(&user_clone, data.len() as u64);
-                            write_client_payload(
-                                &mut writer,
-                                proto_tag,
-                                flags,
-                                &data,
-                                rng_clone.as_ref(),
-                                &mut frame_buf,
-                            )
-                            .await?;
+                    let Some(first) = msg else {
+                        debug!(conn_id, "ME channel closed");
+                        return Err(ProxyError::Proxy("ME connection lost".into()));
+                    };
 
-                            // Drain all immediately queued ME responses and flush once.
-                            while let Ok(next) = me_rx_task.try_recv() {
-                                match next {
-                                    MeResponse::Data { flags, data } => {
-                                        trace!(conn_id, bytes = data.len(), flags, "ME->C data (batched)");
-                                        bytes_me2c_clone.fetch_add(data.len() as u64, Ordering::Relaxed);
-                                        stats_clone.add_user_octets_to(&user_clone, data.len() as u64);
-                                        write_client_payload(
-                                            &mut writer,
-                                            proto_tag,
-                                            flags,
-                                            &data,
-                                            rng_clone.as_ref(),
-                                            &mut frame_buf,
-                                        ).await?;
+                    let mut batch_frames = 0usize;
+                    let mut batch_bytes = 0usize;
+                    let mut flush_immediately;
+
+                    match process_me_writer_response(
+                        first,
+                        &mut writer,
+                        proto_tag,
+                        rng_clone.as_ref(),
+                        &mut frame_buf,
+                        stats_clone.as_ref(),
+                        &user_clone,
+                        bytes_me2c_clone.as_ref(),
+                        conn_id,
+                        d2c_flush_policy.ack_flush_immediate,
+                        false,
+                    ).await? {
+                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                            batch_frames = batch_frames.saturating_add(frames);
+                            batch_bytes = batch_bytes.saturating_add(bytes);
+                            flush_immediately = immediate;
+                        }
+                        MeWriterResponseOutcome::Close => {
+                            let _ = writer.flush().await;
+                            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;
+                        };
+
+                        match process_me_writer_response(
+                            next,
+                            &mut writer,
+                            proto_tag,
+                            rng_clone.as_ref(),
+                            &mut frame_buf,
+                            stats_clone.as_ref(),
+                            &user_clone,
+                            bytes_me2c_clone.as_ref(),
+                            conn_id,
+                            d2c_flush_policy.ack_flush_immediate,
+                            true,
+                        ).await? {
+                            MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                batch_frames = batch_frames.saturating_add(frames);
+                                batch_bytes = batch_bytes.saturating_add(bytes);
+                                flush_immediately |= immediate;
+                            }
+                            MeWriterResponseOutcome::Close => {
+                                let _ = writer.flush().await;
+                                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
+                    {
+                        match tokio::time::timeout(d2c_flush_policy.max_delay, me_rx_task.recv()).await {
+                            Ok(Some(next)) => {
+                                match process_me_writer_response(
+                                    next,
+                                    &mut writer,
+                                    proto_tag,
+                                    rng_clone.as_ref(),
+                                    &mut frame_buf,
+                                    stats_clone.as_ref(),
+                                    &user_clone,
+                                    bytes_me2c_clone.as_ref(),
+                                    conn_id,
+                                    d2c_flush_policy.ack_flush_immediate,
+                                    true,
+                                ).await? {
+                                    MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                        batch_frames = batch_frames.saturating_add(frames);
+                                        batch_bytes = batch_bytes.saturating_add(bytes);
+                                        flush_immediately |= immediate;
                                     }
-                                    MeResponse::Ack(confirm) => {
-                                        trace!(conn_id, confirm, "ME->C quickack (batched)");
-                                        write_client_ack(&mut writer, proto_tag, confirm).await?;
-                                    }
-                                    MeResponse::Close => {
-                                        debug!(conn_id, "ME sent close (batched)");
+                                    MeWriterResponseOutcome::Close => {
                                         let _ = writer.flush().await;
                                         return Ok(());
                                     }
                                 }
-                            }
 
-                            writer.flush().await.map_err(ProxyError::Io)?;
-                        }
-                        Some(MeResponse::Ack(confirm)) => {
-                            trace!(conn_id, confirm, "ME->C quickack");
-                            write_client_ack(&mut writer, proto_tag, confirm).await?;
-                        }
-                        Some(MeResponse::Close) => {
-                            debug!(conn_id, "ME sent close");
-                            let _ = writer.flush().await;
-                            return Ok(());
-                        }
-                        None => {
-                            debug!(conn_id, "ME channel closed");
-                            return Err(ProxyError::Proxy("ME connection lost".into()));
+                                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;
+                                    };
+
+                                    match process_me_writer_response(
+                                        extra,
+                                        &mut writer,
+                                        proto_tag,
+                                        rng_clone.as_ref(),
+                                        &mut frame_buf,
+                                        stats_clone.as_ref(),
+                                        &user_clone,
+                                        bytes_me2c_clone.as_ref(),
+                                        conn_id,
+                                        d2c_flush_policy.ack_flush_immediate,
+                                        true,
+                                    ).await? {
+                                        MeWriterResponseOutcome::Continue { frames, bytes, flush_immediately: immediate } => {
+                                            batch_frames = batch_frames.saturating_add(frames);
+                                            batch_bytes = batch_bytes.saturating_add(bytes);
+                                            flush_immediately |= immediate;
+                                        }
+                                        MeWriterResponseOutcome::Close => {
+                                            let _ = writer.flush().await;
+                                            return Ok(());
+                                        }
+                                    }
+                                }
+                            }
+                            Ok(None) => {
+                                debug!(conn_id, "ME channel closed");
+                                return Err(ProxyError::Proxy("ME connection lost".into()));
+                            }
+                            Err(_) => {}
                         }
                     }
+
+                    writer.flush().await.map_err(ProxyError::Io)?;
                 }
                 _ = &mut stop_rx => {
                     debug!(conn_id, "ME writer stop signal");
@@ -384,46 +559,77 @@ where
     let mut main_result: Result<()> = Ok(());
     let mut client_closed = false;
     let mut frame_counter: u64 = 0;
+    let mut route_watch_open = true;
     loop {
-        match read_client_payload(
-            &mut crypto_reader,
-            proto_tag,
-            frame_limit,
-            &forensics,
-            &mut frame_counter,
-            &stats,
-        ).await {
-            Ok(Some((payload, quickack))) => {
-                trace!(conn_id, bytes = payload.len(), "C->ME frame");
-                forensics.bytes_c2me = forensics
-                    .bytes_c2me
-                    .saturating_add(payload.len() as u64);
-                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;
-                }
-                // Keep client read loop lightweight: route heavy ME send path via a dedicated task.
-                if enqueue_c2me_command(&c2me_tx, C2MeCommand::Data { payload, flags })
-                    .await
-                    .is_err()
-                {
-                    main_result = Err(ProxyError::Proxy("ME sender channel closed".into()));
-                    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"
+            );
+            tokio::time::sleep(delay).await;
+            let _ = enqueue_c2me_command(&c2me_tx, C2MeCommand::Close).await;
+            main_result = Err(ProxyError::Proxy(ROUTE_SWITCH_ERROR_MSG.to_string()));
+            break;
+        }
+
+        tokio::select! {
+            changed = route_rx.changed(), if route_watch_open => {
+                if changed.is_err() {
+                    route_watch_open = false;
                 }
             }
-            Ok(None) => {
-                debug!(conn_id, "Client EOF");
-                client_closed = true;
-                let _ = enqueue_c2me_command(&c2me_tx, C2MeCommand::Close).await;
-                break;
-            }
-            Err(e) => {
-                main_result = Err(e);
-                break;
+            payload_result = read_client_payload(
+                &mut crypto_reader,
+                proto_tag,
+                frame_limit,
+                Duration::from_secs(config.timeouts.client_handshake.max(1)),
+                &buffer_pool,
+                &forensics,
+                &mut frame_counter,
+                &stats,
+            ) => {
+                match payload_result {
+                    Ok(Some((payload, quickack))) => {
+                        trace!(conn_id, bytes = payload.len(), "C->ME frame");
+                        forensics.bytes_c2me = forensics
+                            .bytes_c2me
+                            .saturating_add(payload.len() as u64);
+                        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;
+                        }
+                        // Keep client read loop lightweight: route heavy ME send path via a dedicated task.
+                        if enqueue_c2me_command(&c2me_tx, C2MeCommand::Data { payload, flags })
+                            .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(&c2me_tx, C2MeCommand::Close).await;
+                        break;
+                    }
+                    Err(e) => {
+                        main_result = Err(e);
+                        break;
+                    }
+                }
             }
         }
     }
@@ -466,7 +672,7 @@ where
         "ME relay cleanup"
     );
     me_pool.registry().unregister(conn_id).await;
-    stats.decrement_user_curr_connects(&user);
+    stats.decrement_current_connections_me();
     result
 }
 
@@ -474,30 +680,49 @@ 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<(Vec<u8>, bool)>>
+) -> Result<Option<(PooledBuffer, bool)>>
 where
     R: AsyncRead + Unpin + Send + 'static,
 {
+    async fn read_exact_with_timeout<R>(
+        client_reader: &mut CryptoReader<R>,
+        buf: &mut [u8],
+        frame_read_timeout: Duration,
+    ) -> Result<()>
+    where
+        R: AsyncRead + Unpin + Send + 'static,
+    {
+        match timeout(frame_read_timeout, client_reader.read_exact(buf)).await {
+            Ok(Ok(_)) => Ok(()),
+            Ok(Err(e)) => Err(ProxyError::Io(e)),
+            Err(_) => Err(ProxyError::Io(std::io::Error::new(
+                std::io::ErrorKind::TimedOut,
+                "middle-relay client frame read timeout",
+            ))),
+        }
+    }
+
     loop {
         let (len, quickack, raw_len_bytes) = match proto_tag {
             ProtoTag::Abridged => {
                 let mut first = [0u8; 1];
-                match client_reader.read_exact(&mut first).await {
-                    Ok(_) => {}
-                    Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
-                    Err(e) => return Err(ProxyError::Io(e)),
+                match read_exact_with_timeout(client_reader, &mut first, frame_read_timeout).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];
-                    client_reader
-                        .read_exact(&mut ext)
-                        .await
-                        .map_err(ProxyError::Io)?;
+                    read_exact_with_timeout(client_reader, &mut ext, frame_read_timeout).await?;
                     u32::from_le_bytes([ext[0], ext[1], ext[2], 0]) as usize
                 } else {
                     (first[0] & 0x7f) as usize
@@ -510,10 +735,12 @@ where
             }
             ProtoTag::Intermediate | ProtoTag::Secure => {
                 let mut len_buf = [0u8; 4];
-                match client_reader.read_exact(&mut len_buf).await {
-                    Ok(_) => {}
-                    Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
-                    Err(e) => return Err(ProxyError::Io(e)),
+                match read_exact_with_timeout(client_reader, &mut len_buf, frame_read_timeout).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;
                 (
@@ -565,11 +792,14 @@ where
             len
         };
 
-        let mut payload = vec![0u8; len];
-        client_reader
-            .read_exact(&mut payload)
-            .await
-            .map_err(ProxyError::Io)?;
+        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_timeout(client_reader, &mut payload[..len], frame_read_timeout).await?;
 
         // Secure Intermediate: strip validated trailing padding bytes.
         if proto_tag == ProtoTag::Secure {
@@ -580,6 +810,81 @@ where
     }
 }
 
+enum MeWriterResponseOutcome {
+    Continue {
+        frames: usize,
+        bytes: usize,
+        flush_immediately: bool,
+    },
+    Close,
+}
+
+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,
+    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");
+            }
+            bytes_me2c.fetch_add(data.len() as u64, Ordering::Relaxed);
+            stats.add_user_octets_to(user, data.len() as u64);
+            write_client_payload(
+                client_writer,
+                proto_tag,
+                flags,
+                &data,
+                rng,
+                frame_buf,
+            )
+            .await?;
+
+            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");
+            }
+            write_client_ack(client_writer, proto_tag, confirm).await?;
+
+            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)
+        }
+    }
+}
+
 async fn write_client_payload<W>(
     client_writer: &mut CryptoWriter<W>,
     proto_tag: ProtoTag,
@@ -689,88 +994,9 @@ where
     client_writer
         .write_all(&bytes)
         .await
-        .map_err(ProxyError::Io)?;
-    // ACK should remain low-latency.
-    client_writer.flush().await.map_err(ProxyError::Io)
+        .map_err(ProxyError::Io)
 }
 
 #[cfg(test)]
-mod tests {
-    use super::*;
-    use tokio::time::{Duration as TokioDuration, timeout};
-
-    #[test]
-    fn should_yield_sender_only_on_budget_with_backlog() {
-        assert!(!should_yield_c2me_sender(0, true));
-        assert!(!should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET - 1, true));
-        assert!(!should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET, false));
-        assert!(should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET, true));
-    }
-
-    #[tokio::test]
-    async fn enqueue_c2me_command_uses_try_send_fast_path() {
-        let (tx, mut rx) = mpsc::channel::<C2MeCommand>(2);
-        enqueue_c2me_command(
-            &tx,
-            C2MeCommand::Data {
-                payload: vec![1, 2, 3],
-                flags: 0,
-            },
-        )
-        .await
-        .unwrap();
-
-        let recv = timeout(TokioDuration::from_millis(50), rx.recv())
-            .await
-            .unwrap()
-            .unwrap();
-        match recv {
-            C2MeCommand::Data { payload, flags } => {
-                assert_eq!(payload, vec![1, 2, 3]);
-                assert_eq!(flags, 0);
-            }
-            C2MeCommand::Close => panic!("unexpected close command"),
-        }
-    }
-
-    #[tokio::test]
-    async fn enqueue_c2me_command_falls_back_to_send_when_queue_is_full() {
-        let (tx, mut rx) = mpsc::channel::<C2MeCommand>(1);
-        tx.send(C2MeCommand::Data {
-            payload: vec![9],
-            flags: 9,
-        })
-        .await
-        .unwrap();
-
-        let tx2 = tx.clone();
-        let producer = tokio::spawn(async move {
-            enqueue_c2me_command(
-                &tx2,
-                C2MeCommand::Data {
-                    payload: vec![7, 7],
-                    flags: 7,
-                },
-            )
-            .await
-            .unwrap();
-        });
-
-        let _ = timeout(TokioDuration::from_millis(100), rx.recv())
-            .await
-            .unwrap();
-        producer.await.unwrap();
-
-        let recv = timeout(TokioDuration::from_millis(100), rx.recv())
-            .await
-            .unwrap()
-            .unwrap();
-        match recv {
-            C2MeCommand::Data { payload, flags } => {
-                assert_eq!(payload, vec![7, 7]);
-                assert_eq!(flags, 7);
-            }
-            C2MeCommand::Close => panic!("unexpected close command"),
-        }
-    }
-}
+#[path = "middle_relay_security_tests.rs"]
+mod security_tests;

src/proxy/middle_relay_security_tests.rs

@@ -0,0 +1,781 @@
+use super::*;
+use bytes::Bytes;
+use crate::crypto::AesCtr;
+use crate::crypto::SecureRandom;
+use crate::stats::Stats;
+use crate::stream::{BufferPool, CryptoReader, CryptoWriter, PooledBuffer};
+use std::net::SocketAddr;
+use std::sync::Arc;
+use std::sync::atomic::AtomicU64;
+use tokio::io::AsyncWriteExt;
+use tokio::io::duplex;
+use tokio::time::{Duration as TokioDuration, timeout};
+
+fn make_pooled_payload(data: &[u8]) -> PooledBuffer {
+    let pool = Arc::new(BufferPool::with_config(data.len().max(1), 4));
+    let mut payload = pool.get();
+    payload.resize(data.len(), 0);
+    payload[..data.len()].copy_from_slice(data);
+    payload
+}
+
+fn make_pooled_payload_from(pool: &Arc<BufferPool>, data: &[u8]) -> PooledBuffer {
+    let mut payload = pool.get();
+    payload.resize(data.len(), 0);
+    payload[..data.len()].copy_from_slice(data);
+    payload
+}
+
+#[test]
+fn should_yield_sender_only_on_budget_with_backlog() {
+    assert!(!should_yield_c2me_sender(0, true));
+    assert!(!should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET - 1, true));
+    assert!(!should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET, false));
+    assert!(should_yield_c2me_sender(C2ME_SENDER_FAIRNESS_BUDGET, true));
+}
+
+#[tokio::test]
+async fn enqueue_c2me_command_uses_try_send_fast_path() {
+    let (tx, mut rx) = mpsc::channel::<C2MeCommand>(2);
+    enqueue_c2me_command(
+        &tx,
+        C2MeCommand::Data {
+            payload: make_pooled_payload(&[1, 2, 3]),
+            flags: 0,
+        },
+    )
+    .await
+    .unwrap();
+
+    let recv = timeout(TokioDuration::from_millis(50), rx.recv())
+        .await
+        .unwrap()
+        .unwrap();
+    match recv {
+        C2MeCommand::Data { payload, flags } => {
+            assert_eq!(payload.as_ref(), &[1, 2, 3]);
+            assert_eq!(flags, 0);
+        }
+        C2MeCommand::Close => panic!("unexpected close command"),
+    }
+}
+
+#[tokio::test]
+async fn enqueue_c2me_command_falls_back_to_send_when_queue_is_full() {
+    let (tx, mut rx) = mpsc::channel::<C2MeCommand>(1);
+    tx.send(C2MeCommand::Data {
+        payload: make_pooled_payload(&[9]),
+        flags: 9,
+    })
+    .await
+    .unwrap();
+
+    let tx2 = tx.clone();
+    let producer = tokio::spawn(async move {
+        enqueue_c2me_command(
+            &tx2,
+            C2MeCommand::Data {
+                payload: make_pooled_payload(&[7, 7]),
+                flags: 7,
+            },
+        )
+        .await
+        .unwrap();
+    });
+
+    let _ = timeout(TokioDuration::from_millis(100), rx.recv())
+        .await
+        .unwrap();
+    producer.await.unwrap();
+
+    let recv = timeout(TokioDuration::from_millis(100), rx.recv())
+        .await
+        .unwrap()
+        .unwrap();
+    match recv {
+        C2MeCommand::Data { payload, flags } => {
+            assert_eq!(payload.as_ref(), &[7, 7]);
+            assert_eq!(flags, 7);
+        }
+        C2MeCommand::Close => panic!("unexpected close command"),
+    }
+}
+
+#[tokio::test]
+async fn enqueue_c2me_command_closed_channel_recycles_payload() {
+    let pool = Arc::new(BufferPool::with_config(64, 4));
+    let payload = make_pooled_payload_from(&pool, &[1, 2, 3, 4]);
+    let (tx, rx) = mpsc::channel::<C2MeCommand>(1);
+    drop(rx);
+
+    let result = enqueue_c2me_command(
+        &tx,
+        C2MeCommand::Data {
+            payload,
+            flags: 0,
+        },
+    )
+    .await;
+
+    assert!(result.is_err(), "closed queue must fail enqueue");
+    drop(result);
+    assert!(
+        pool.stats().pooled >= 1,
+        "payload must return to pool when enqueue fails on closed channel"
+    );
+}
+
+#[tokio::test]
+async fn enqueue_c2me_command_full_then_closed_recycles_waiting_payload() {
+    let pool = Arc::new(BufferPool::with_config(64, 4));
+    let (tx, rx) = mpsc::channel::<C2MeCommand>(1);
+
+    tx.send(C2MeCommand::Data {
+        payload: make_pooled_payload_from(&pool, &[9]),
+        flags: 1,
+    })
+    .await
+    .unwrap();
+
+    let tx2 = tx.clone();
+    let pool2 = pool.clone();
+    let blocked_send = tokio::spawn(async move {
+        enqueue_c2me_command(
+            &tx2,
+            C2MeCommand::Data {
+                payload: make_pooled_payload_from(&pool2, &[7, 7, 7]),
+                flags: 2,
+            },
+        )
+        .await
+    });
+
+    tokio::time::sleep(TokioDuration::from_millis(10)).await;
+    drop(rx);
+
+    let result = timeout(TokioDuration::from_secs(1), blocked_send)
+        .await
+        .expect("blocked send task must finish")
+        .expect("blocked send task must not panic");
+
+    assert!(
+        result.is_err(),
+        "closing receiver while sender is blocked must fail enqueue"
+    );
+    drop(result);
+    assert!(
+        pool.stats().pooled >= 2,
+        "both queued and blocked payloads must return to pool after channel close"
+    );
+}
+
+#[test]
+fn desync_dedup_cache_is_bounded() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("desync dedup test lock must be available");
+    clear_desync_dedup_for_testing();
+
+    let now = Instant::now();
+    for key in 0..DESYNC_DEDUP_MAX_ENTRIES as u64 {
+        assert!(
+            should_emit_full_desync(key, false, now),
+            "unique keys up to cap must be tracked"
+        );
+    }
+
+    assert!(
+        !should_emit_full_desync(u64::MAX, false, now),
+        "new key above cap must remain suppressed to avoid log amplification"
+    );
+
+    assert!(
+        !should_emit_full_desync(7, false, now),
+        "already tracked key inside dedup window must stay suppressed"
+    );
+}
+
+#[test]
+fn desync_dedup_full_cache_churn_stays_suppressed() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("desync dedup test lock must be available");
+    clear_desync_dedup_for_testing();
+
+    let now = Instant::now();
+    for key in 0..DESYNC_DEDUP_MAX_ENTRIES as u64 {
+        assert!(should_emit_full_desync(key, false, now));
+    }
+
+    for offset in 0..2048u64 {
+        assert!(
+            !should_emit_full_desync(u64::MAX - offset, false, now),
+            "fresh full-cache churn must remain suppressed under pressure"
+        );
+    }
+}
+
+fn make_forensics_state() -> RelayForensicsState {
+    RelayForensicsState {
+        trace_id: 1,
+        conn_id: 2,
+        user: "test-user".to_string(),
+        peer: "127.0.0.1:50000".parse::<SocketAddr>().unwrap(),
+        peer_hash: 3,
+        started_at: Instant::now(),
+        bytes_c2me: 0,
+        bytes_me2c: Arc::new(AtomicU64::new(0)),
+        desync_all_full: false,
+    }
+}
+
+fn make_crypto_reader(reader: tokio::io::DuplexStream) -> CryptoReader<tokio::io::DuplexStream> {
+    let key = [0u8; 32];
+    let iv = 0u128;
+    CryptoReader::new(reader, AesCtr::new(&key, iv))
+}
+
+fn make_crypto_writer(writer: tokio::io::DuplexStream) -> CryptoWriter<tokio::io::DuplexStream> {
+    let key = [0u8; 32];
+    let iv = 0u128;
+    CryptoWriter::new(writer, AesCtr::new(&key, iv), 8 * 1024)
+}
+
+fn encrypt_for_reader(plaintext: &[u8]) -> Vec<u8> {
+    let key = [0u8; 32];
+    let iv = 0u128;
+    let mut cipher = AesCtr::new(&key, iv);
+    cipher.encrypt(plaintext)
+}
+
+#[tokio::test]
+async fn read_client_payload_times_out_on_header_stall() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+    let (reader, _writer) = duplex(1024);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let buffer_pool = Arc::new(BufferPool::new());
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let result = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Intermediate,
+        1024,
+        TokioDuration::from_millis(25),
+        &buffer_pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await;
+
+    assert!(
+        matches!(result, Err(ProxyError::Io(ref e)) if e.kind() == std::io::ErrorKind::TimedOut),
+        "stalled header read must time out"
+    );
+}
+
+#[tokio::test]
+async fn read_client_payload_times_out_on_payload_stall() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+    let (reader, mut writer) = duplex(1024);
+    let encrypted_len = encrypt_for_reader(&[8, 0, 0, 0]);
+    writer.write_all(&encrypted_len).await.unwrap();
+
+    let mut crypto_reader = make_crypto_reader(reader);
+    let buffer_pool = Arc::new(BufferPool::new());
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let result = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Intermediate,
+        1024,
+        TokioDuration::from_millis(25),
+        &buffer_pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await;
+
+    assert!(
+        matches!(result, Err(ProxyError::Io(ref e)) if e.kind() == std::io::ErrorKind::TimedOut),
+        "stalled payload body read must time out"
+    );
+}
+
+#[tokio::test]
+async fn read_client_payload_large_intermediate_frame_is_exact() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+
+    let (reader, mut writer) = duplex(262_144);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let buffer_pool = Arc::new(BufferPool::new());
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let payload_len = buffer_pool.buffer_size().saturating_mul(3).max(65_537);
+    let mut plaintext = Vec::with_capacity(4 + payload_len);
+    plaintext.extend_from_slice(&(payload_len as u32).to_le_bytes());
+    plaintext.extend((0..payload_len).map(|idx| (idx as u8).wrapping_mul(31)));
+
+    let encrypted = encrypt_for_reader(&plaintext);
+    writer.write_all(&encrypted).await.unwrap();
+
+    let read = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Intermediate,
+        payload_len + 16,
+        TokioDuration::from_secs(1),
+        &buffer_pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await
+    .expect("payload read must succeed")
+    .expect("frame must be present");
+
+    let (frame, quickack) = read;
+    assert!(!quickack, "quickack flag must be unset");
+    assert_eq!(frame.len(), payload_len, "payload size must match wire length");
+    for (idx, byte) in frame.iter().enumerate() {
+        assert_eq!(*byte, (idx as u8).wrapping_mul(31));
+    }
+    assert_eq!(frame_counter, 1, "exactly one frame must be counted");
+}
+
+#[tokio::test]
+async fn read_client_payload_secure_strips_tail_padding_bytes() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+
+    let (reader, mut writer) = duplex(1024);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let buffer_pool = Arc::new(BufferPool::new());
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let payload = [0x11u8, 0x22, 0x33, 0x44, 0xaa, 0xbb, 0xcc, 0xdd];
+    let tail = [0xeeu8, 0xff, 0x99];
+    let wire_len = payload.len() + tail.len();
+
+    let mut plaintext = Vec::with_capacity(4 + wire_len);
+    plaintext.extend_from_slice(&(wire_len as u32).to_le_bytes());
+    plaintext.extend_from_slice(&payload);
+    plaintext.extend_from_slice(&tail);
+    let encrypted = encrypt_for_reader(&plaintext);
+    writer.write_all(&encrypted).await.unwrap();
+
+    let read = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Secure,
+        1024,
+        TokioDuration::from_secs(1),
+        &buffer_pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await
+    .expect("secure payload read must succeed")
+    .expect("secure frame must be present");
+
+    let (frame, quickack) = read;
+    assert!(!quickack, "quickack flag must be unset");
+    assert_eq!(frame.as_ref(), &payload);
+    assert_eq!(frame_counter, 1, "one secure frame must be counted");
+}
+
+#[tokio::test]
+async fn read_client_payload_secure_rejects_wire_len_below_4() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+
+    let (reader, mut writer) = duplex(1024);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let buffer_pool = Arc::new(BufferPool::new());
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let mut plaintext = Vec::with_capacity(7);
+    plaintext.extend_from_slice(&3u32.to_le_bytes());
+    plaintext.extend_from_slice(&[1u8, 2, 3]);
+    let encrypted = encrypt_for_reader(&plaintext);
+    writer.write_all(&encrypted).await.unwrap();
+
+    let result = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Secure,
+        1024,
+        TokioDuration::from_secs(1),
+        &buffer_pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await;
+
+    assert!(
+        matches!(result, Err(ProxyError::Proxy(ref msg)) if msg.contains("Frame too small: 3")),
+        "secure wire length below 4 must be fail-closed by the frame-too-small guard"
+    );
+}
+
+#[tokio::test]
+async fn read_client_payload_intermediate_skips_zero_len_frame() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+
+    let (reader, mut writer) = duplex(1024);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let buffer_pool = Arc::new(BufferPool::new());
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let payload = [7u8, 6, 5, 4, 3, 2, 1, 0];
+    let mut plaintext = Vec::with_capacity(4 + 4 + payload.len());
+    plaintext.extend_from_slice(&0u32.to_le_bytes());
+    plaintext.extend_from_slice(&(payload.len() as u32).to_le_bytes());
+    plaintext.extend_from_slice(&payload);
+    let encrypted = encrypt_for_reader(&plaintext);
+    writer.write_all(&encrypted).await.unwrap();
+
+    let read = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Intermediate,
+        1024,
+        TokioDuration::from_secs(1),
+        &buffer_pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await
+    .expect("intermediate payload read must succeed")
+    .expect("frame must be present");
+
+    let (frame, quickack) = read;
+    assert!(!quickack, "quickack flag must be unset");
+    assert_eq!(frame.as_ref(), &payload);
+    assert_eq!(frame_counter, 1, "zero-length frame must be skipped");
+}
+
+#[tokio::test]
+async fn read_client_payload_abridged_extended_len_sets_quickack() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+
+    let (reader, mut writer) = duplex(4096);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let buffer_pool = Arc::new(BufferPool::new());
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let payload_len = 4 * 130;
+    let len_words = (payload_len / 4) as u32;
+    let mut plaintext = Vec::with_capacity(1 + 3 + payload_len);
+    plaintext.push(0xff | 0x80);
+    let lw = len_words.to_le_bytes();
+    plaintext.extend_from_slice(&lw[..3]);
+    plaintext.extend((0..payload_len).map(|idx| (idx as u8).wrapping_add(17)));
+
+    let encrypted = encrypt_for_reader(&plaintext);
+    writer.write_all(&encrypted).await.unwrap();
+
+    let read = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Abridged,
+        payload_len + 16,
+        TokioDuration::from_secs(1),
+        &buffer_pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await
+    .expect("abridged payload read must succeed")
+    .expect("frame must be present");
+
+    let (frame, quickack) = read;
+    assert!(quickack, "quickack bit must be propagated from abridged header");
+    assert_eq!(frame.len(), payload_len);
+    assert_eq!(frame_counter, 1, "one abridged frame must be counted");
+}
+
+#[tokio::test]
+async fn read_client_payload_returns_buffer_to_pool_after_emit() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+
+    let pool = Arc::new(BufferPool::with_config(64, 8));
+    pool.preallocate(1);
+    assert_eq!(pool.stats().pooled, 1, "precondition: one pooled buffer");
+
+    let (reader, mut writer) = duplex(4096);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    // Force growth beyond default pool buffer size to catch ownership-take regressions.
+    let payload_len = 257usize;
+    let mut plaintext = Vec::with_capacity(4 + payload_len);
+    plaintext.extend_from_slice(&(payload_len as u32).to_le_bytes());
+    plaintext.extend((0..payload_len).map(|idx| (idx as u8).wrapping_mul(13)));
+
+    let encrypted = encrypt_for_reader(&plaintext);
+    writer.write_all(&encrypted).await.unwrap();
+
+    let _ = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Intermediate,
+        payload_len + 8,
+        TokioDuration::from_secs(1),
+        &pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await
+    .expect("payload read must succeed")
+    .expect("frame must be present");
+
+    assert_eq!(frame_counter, 1);
+    let pool_stats = pool.stats();
+    assert!(
+        pool_stats.pooled >= 1,
+        "emitted payload buffer must be returned to pool to avoid pool drain"
+    );
+}
+
+#[tokio::test]
+async fn read_client_payload_keeps_pool_buffer_checked_out_until_frame_drop() {
+    let _guard = desync_dedup_test_lock()
+        .lock()
+        .expect("middle relay test lock must be available");
+
+    let pool = Arc::new(BufferPool::with_config(64, 2));
+    pool.preallocate(1);
+    assert_eq!(pool.stats().pooled, 1, "one pooled buffer must be available");
+
+    let (reader, mut writer) = duplex(1024);
+    let mut crypto_reader = make_crypto_reader(reader);
+    let stats = Stats::new();
+    let forensics = make_forensics_state();
+    let mut frame_counter = 0;
+
+    let payload = [0x41u8, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48];
+    let mut plaintext = Vec::with_capacity(4 + payload.len());
+    plaintext.extend_from_slice(&(payload.len() as u32).to_le_bytes());
+    plaintext.extend_from_slice(&payload);
+    let encrypted = encrypt_for_reader(&plaintext);
+    writer.write_all(&encrypted).await.unwrap();
+
+    let (frame, quickack) = read_client_payload(
+        &mut crypto_reader,
+        ProtoTag::Intermediate,
+        1024,
+        TokioDuration::from_secs(1),
+        &pool,
+        &forensics,
+        &mut frame_counter,
+        &stats,
+    )
+    .await
+    .expect("payload read must succeed")
+    .expect("frame must be present");
+
+    assert!(!quickack);
+    assert_eq!(frame.as_ref(), &payload);
+    assert_eq!(
+        pool.stats().pooled,
+        0,
+        "buffer must stay checked out while frame payload is alive"
+    );
+
+    drop(frame);
+    assert!(
+        pool.stats().pooled >= 1,
+        "buffer must return to pool only after frame drop"
+    );
+}
+
+#[tokio::test]
+async fn enqueue_c2me_close_unblocks_after_queue_drain() {
+    let (tx, mut rx) = mpsc::channel::<C2MeCommand>(1);
+    tx.send(C2MeCommand::Data {
+        payload: make_pooled_payload(&[0x41]),
+        flags: 0,
+    })
+    .await
+    .unwrap();
+
+    let tx2 = tx.clone();
+    let close_task = tokio::spawn(async move { enqueue_c2me_command(&tx2, C2MeCommand::Close).await });
+
+    tokio::time::sleep(TokioDuration::from_millis(10)).await;
+
+    let first = timeout(TokioDuration::from_millis(100), rx.recv())
+        .await
+        .unwrap()
+        .expect("first queued item must be present");
+    assert!(matches!(first, C2MeCommand::Data { .. }));
+
+    close_task.await.unwrap().expect("close enqueue must succeed after drain");
+
+    let second = timeout(TokioDuration::from_millis(100), rx.recv())
+        .await
+        .unwrap()
+        .expect("close command must follow after queue drain");
+    assert!(matches!(second, C2MeCommand::Close));
+}
+
+#[tokio::test]
+async fn enqueue_c2me_close_full_then_receiver_drop_fails_cleanly() {
+    let (tx, rx) = mpsc::channel::<C2MeCommand>(1);
+    tx.send(C2MeCommand::Data {
+        payload: make_pooled_payload(&[0x42]),
+        flags: 0,
+    })
+    .await
+    .unwrap();
+
+    let tx2 = tx.clone();
+    let close_task = tokio::spawn(async move { enqueue_c2me_command(&tx2, C2MeCommand::Close).await });
+
+    tokio::time::sleep(TokioDuration::from_millis(10)).await;
+    drop(rx);
+
+    let result = timeout(TokioDuration::from_secs(1), close_task)
+        .await
+        .expect("close task must finish")
+        .expect("close task must not panic");
+    assert!(
+        result.is_err(),
+        "close enqueue must fail cleanly when receiver is dropped under pressure"
+    );
+}
+
+#[tokio::test]
+async fn process_me_writer_response_ack_obeys_flush_policy() {
+    let (writer_side, _reader_side) = duplex(1024);
+    let mut writer = make_crypto_writer(writer_side);
+    let rng = SecureRandom::new();
+    let mut frame_buf = Vec::new();
+    let stats = Stats::new();
+    let bytes_me2c = AtomicU64::new(0);
+
+    let immediate = process_me_writer_response(
+        MeResponse::Ack(0x11223344),
+        &mut writer,
+        ProtoTag::Intermediate,
+        &rng,
+        &mut frame_buf,
+        &stats,
+        "user",
+        &bytes_me2c,
+        77,
+        true,
+        false,
+    )
+    .await
+    .expect("ack response must be processed");
+
+    assert!(matches!(
+        immediate,
+        MeWriterResponseOutcome::Continue {
+            frames: 1,
+            bytes: 4,
+            flush_immediately: true,
+        }
+    ));
+
+    let delayed = process_me_writer_response(
+        MeResponse::Ack(0x55667788),
+        &mut writer,
+        ProtoTag::Intermediate,
+        &rng,
+        &mut frame_buf,
+        &stats,
+        "user",
+        &bytes_me2c,
+        77,
+        false,
+        false,
+    )
+    .await
+    .expect("ack response must be processed");
+
+    assert!(matches!(
+        delayed,
+        MeWriterResponseOutcome::Continue {
+            frames: 1,
+            bytes: 4,
+            flush_immediately: false,
+        }
+    ));
+}
+
+#[tokio::test]
+async fn process_me_writer_response_data_updates_byte_accounting() {
+    let (writer_side, _reader_side) = duplex(1024);
+    let mut writer = make_crypto_writer(writer_side);
+    let rng = SecureRandom::new();
+    let mut frame_buf = Vec::new();
+    let stats = Stats::new();
+    let bytes_me2c = AtomicU64::new(0);
+
+    let payload = vec![1u8, 2, 3, 4, 5, 6, 7, 8, 9];
+    let outcome = process_me_writer_response(
+        MeResponse::Data {
+            flags: 0,
+            data: Bytes::from(payload.clone()),
+        },
+        &mut writer,
+        ProtoTag::Intermediate,
+        &rng,
+        &mut frame_buf,
+        &stats,
+        "user",
+        &bytes_me2c,
+        88,
+        false,
+        false,
+    )
+    .await
+    .expect("data response must be processed");
+
+    assert!(matches!(
+        outcome,
+        MeWriterResponseOutcome::Continue {
+            frames: 1,
+            bytes,
+            flush_immediately: false,
+        } if bytes == payload.len()
+    ));
+    assert_eq!(
+        bytes_me2c.load(std::sync::atomic::Ordering::Relaxed),
+        payload.len() as u64,
+        "ME->C byte accounting must increase by emitted payload size"
+    );
+}

src/proxy/mod.rs

@@ -5,6 +5,7 @@ pub mod direct_relay;
 pub mod handshake;
 pub mod masking;
 pub mod middle_relay;
+pub mod route_mode;
 pub mod relay;
 
 pub use client::ClientHandler;

src/proxy/relay.rs

@@ -57,7 +57,9 @@ use std::sync::Arc;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::task::{Context, Poll};
 use std::time::Duration;
-use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional};
+use tokio::io::{
+    AsyncRead, AsyncWrite, AsyncWriteExt, ReadBuf, copy_bidirectional_with_sizes,
+};
 use tokio::time::Instant;
 use tracing::{debug, trace, warn};
 use crate::error::Result;
@@ -296,9 +298,8 @@ impl<S: AsyncWrite + Unpin> AsyncWrite for StatsIo<S> {
 ///
 /// ## API compatibility
 ///
-/// Signature is identical to the previous implementation. The `_buffer_pool`
-/// parameter is retained for call-site compatibility — `copy_bidirectional`
-/// manages its own internal buffers (8 KB per direction).
+/// The `_buffer_pool` parameter is retained for call-site compatibility.
+/// Effective relay copy buffers are configured by `c2s_buf_size` / `s2c_buf_size`.
 ///
 /// ## Guarantees preserved
 ///
@@ -312,6 +313,8 @@ pub async fn relay_bidirectional<CR, CW, SR, SW>(
     client_writer: CW,
     server_reader: SR,
     server_writer: SW,
+    c2s_buf_size: usize,
+    s2c_buf_size: usize,
     user: &str,
     stats: Arc<Stats>,
     _buffer_pool: Arc<BufferPool>,
@@ -402,7 +405,12 @@ where
     // When the watchdog fires, select! drops the copy future,
     // releasing the &mut borrows on client and server.
     let copy_result = tokio::select! {
-        result = copy_bidirectional(&mut client, &mut server) => Some(result),
+        result = copy_bidirectional_with_sizes(
+            &mut client,
+            &mut server,
+            c2s_buf_size.max(1),
+            s2c_buf_size.max(1),
+        ) => Some(result),
         _ = watchdog => None, // Activity timeout — cancel relay
     };
 
@@ -463,4 +471,4 @@ where
             Ok(())
         }
     }
-}
+}

src/proxy/route_mode.rs

@@ -0,0 +1,142 @@
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU8, AtomicU64, Ordering};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use tokio::sync::watch;
+
+pub(crate) const ROUTE_SWITCH_ERROR_MSG: &str = "Route mode switched by cutover";
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[repr(u8)]
+pub(crate) enum RelayRouteMode {
+    Direct = 0,
+    Middle = 1,
+}
+
+impl RelayRouteMode {
+    pub(crate) fn as_u8(self) -> u8 {
+        self as u8
+    }
+
+    pub(crate) fn from_u8(value: u8) -> Self {
+        match value {
+            1 => Self::Middle,
+            _ => Self::Direct,
+        }
+    }
+
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Direct => "direct",
+            Self::Middle => "middle",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct RouteCutoverState {
+    pub mode: RelayRouteMode,
+    pub generation: u64,
+}
+
+#[derive(Clone)]
+pub(crate) struct RouteRuntimeController {
+    mode: Arc<AtomicU8>,
+    generation: Arc<AtomicU64>,
+    direct_since_epoch_secs: Arc<AtomicU64>,
+    tx: watch::Sender<RouteCutoverState>,
+}
+
+impl RouteRuntimeController {
+    pub(crate) fn new(initial_mode: RelayRouteMode) -> Self {
+        let initial = RouteCutoverState {
+            mode: initial_mode,
+            generation: 0,
+        };
+        let (tx, _rx) = watch::channel(initial);
+        let direct_since_epoch_secs = if matches!(initial_mode, RelayRouteMode::Direct) {
+            now_epoch_secs()
+        } else {
+            0
+        };
+        Self {
+            mode: Arc::new(AtomicU8::new(initial_mode.as_u8())),
+            generation: Arc::new(AtomicU64::new(0)),
+            direct_since_epoch_secs: Arc::new(AtomicU64::new(direct_since_epoch_secs)),
+            tx,
+        }
+    }
+
+    pub(crate) fn snapshot(&self) -> RouteCutoverState {
+        RouteCutoverState {
+            mode: RelayRouteMode::from_u8(self.mode.load(Ordering::Relaxed)),
+            generation: self.generation.load(Ordering::Relaxed),
+        }
+    }
+
+    pub(crate) fn subscribe(&self) -> watch::Receiver<RouteCutoverState> {
+        self.tx.subscribe()
+    }
+
+    pub(crate) fn direct_since_epoch_secs(&self) -> Option<u64> {
+        let value = self.direct_since_epoch_secs.load(Ordering::Relaxed);
+        (value > 0).then_some(value)
+    }
+
+    pub(crate) fn set_mode(&self, mode: RelayRouteMode) -> Option<RouteCutoverState> {
+        let previous = self.mode.swap(mode.as_u8(), Ordering::Relaxed);
+        if previous == mode.as_u8() {
+            return None;
+        }
+        if matches!(mode, RelayRouteMode::Direct) {
+            self.direct_since_epoch_secs
+                .store(now_epoch_secs(), Ordering::Relaxed);
+        } else {
+            self.direct_since_epoch_secs.store(0, Ordering::Relaxed);
+        }
+        let generation = self.generation.fetch_add(1, Ordering::Relaxed) + 1;
+        let next = RouteCutoverState { mode, generation };
+        self.tx.send_replace(next);
+        Some(next)
+    }
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|value| value.as_secs())
+        .unwrap_or(0)
+}
+
+pub(crate) fn is_session_affected_by_cutover(
+    current: RouteCutoverState,
+    _session_mode: RelayRouteMode,
+    session_generation: u64,
+) -> bool {
+    current.generation > session_generation
+}
+
+pub(crate) fn affected_cutover_state(
+    rx: &watch::Receiver<RouteCutoverState>,
+    session_mode: RelayRouteMode,
+    session_generation: u64,
+) -> Option<RouteCutoverState> {
+    let current = *rx.borrow();
+    if is_session_affected_by_cutover(current, session_mode, session_generation) {
+        return Some(current);
+    }
+    None
+}
+
+pub(crate) fn cutover_stagger_delay(session_id: u64, generation: u64) -> Duration {
+    let mut value = session_id
+        ^ generation.rotate_left(17)
+        ^ 0x9e37_79b9_7f4a_7c15;
+    value ^= value >> 30;
+    value = value.wrapping_mul(0xbf58_476d_1ce4_e5b9);
+    value ^= value >> 27;
+    value = value.wrapping_mul(0x94d0_49bb_1331_11eb);
+    value ^= value >> 31;
+    let ms = 1000 + (value % 1000);
+    Duration::from_millis(ms)
+}

src/startup.rs

@@ -0,0 +1,373 @@
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+use tokio::sync::RwLock;
+
+pub const COMPONENT_CONFIG_LOAD: &str = "config_load";
+pub const COMPONENT_TRACING_INIT: &str = "tracing_init";
+pub const COMPONENT_API_BOOTSTRAP: &str = "api_bootstrap";
+pub const COMPONENT_TLS_FRONT_BOOTSTRAP: &str = "tls_front_bootstrap";
+pub const COMPONENT_NETWORK_PROBE: &str = "network_probe";
+pub const COMPONENT_ME_SECRET_FETCH: &str = "me_secret_fetch";
+pub const COMPONENT_ME_PROXY_CONFIG_V4: &str = "me_proxy_config_fetch_v4";
+pub const COMPONENT_ME_PROXY_CONFIG_V6: &str = "me_proxy_config_fetch_v6";
+pub const COMPONENT_ME_POOL_CONSTRUCT: &str = "me_pool_construct";
+pub const COMPONENT_ME_POOL_INIT_STAGE1: &str = "me_pool_init_stage1";
+pub const COMPONENT_ME_CONNECTIVITY_PING: &str = "me_connectivity_ping";
+pub const COMPONENT_DC_CONNECTIVITY_PING: &str = "dc_connectivity_ping";
+pub const COMPONENT_LISTENERS_BIND: &str = "listeners_bind";
+pub const COMPONENT_CONFIG_WATCHER_START: &str = "config_watcher_start";
+pub const COMPONENT_METRICS_START: &str = "metrics_start";
+pub const COMPONENT_RUNTIME_READY: &str = "runtime_ready";
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StartupStatus {
+    Initializing,
+    Ready,
+}
+
+impl StartupStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Initializing => "initializing",
+            Self::Ready => "ready",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StartupComponentStatus {
+    Pending,
+    Running,
+    Ready,
+    Failed,
+    Skipped,
+}
+
+impl StartupComponentStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Pending => "pending",
+            Self::Running => "running",
+            Self::Ready => "ready",
+            Self::Failed => "failed",
+            Self::Skipped => "skipped",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StartupMeStatus {
+    Pending,
+    Initializing,
+    Ready,
+    Failed,
+    Skipped,
+}
+
+impl StartupMeStatus {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Pending => "pending",
+            Self::Initializing => "initializing",
+            Self::Ready => "ready",
+            Self::Failed => "failed",
+            Self::Skipped => "skipped",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct StartupComponentSnapshot {
+    pub id: &'static str,
+    pub title: &'static str,
+    pub weight: f64,
+    pub status: StartupComponentStatus,
+    pub started_at_epoch_ms: Option<u64>,
+    pub finished_at_epoch_ms: Option<u64>,
+    pub duration_ms: Option<u64>,
+    pub attempts: u32,
+    pub details: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+pub struct StartupMeSnapshot {
+    pub status: StartupMeStatus,
+    pub current_stage: String,
+    pub init_attempt: u32,
+    pub retry_limit: String,
+    pub last_error: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+pub struct StartupSnapshot {
+    pub status: StartupStatus,
+    pub degraded: bool,
+    pub current_stage: String,
+    pub started_at_epoch_secs: u64,
+    pub ready_at_epoch_secs: Option<u64>,
+    pub total_elapsed_ms: u64,
+    pub transport_mode: String,
+    pub me: StartupMeSnapshot,
+    pub components: Vec<StartupComponentSnapshot>,
+}
+
+#[derive(Clone, Debug)]
+struct StartupComponent {
+    id: &'static str,
+    title: &'static str,
+    weight: f64,
+    status: StartupComponentStatus,
+    started_at_epoch_ms: Option<u64>,
+    finished_at_epoch_ms: Option<u64>,
+    duration_ms: Option<u64>,
+    attempts: u32,
+    details: Option<String>,
+}
+
+#[derive(Clone, Debug)]
+struct StartupState {
+    status: StartupStatus,
+    degraded: bool,
+    current_stage: String,
+    started_at_epoch_secs: u64,
+    ready_at_epoch_secs: Option<u64>,
+    transport_mode: String,
+    me: StartupMeSnapshot,
+    components: Vec<StartupComponent>,
+}
+
+pub struct StartupTracker {
+    started_at_instant: Instant,
+    state: RwLock<StartupState>,
+}
+
+impl StartupTracker {
+    pub fn new(started_at_epoch_secs: u64) -> Self {
+        Self {
+            started_at_instant: Instant::now(),
+            state: RwLock::new(StartupState {
+                status: StartupStatus::Initializing,
+                degraded: false,
+                current_stage: COMPONENT_CONFIG_LOAD.to_string(),
+                started_at_epoch_secs,
+                ready_at_epoch_secs: None,
+                transport_mode: "unknown".to_string(),
+                me: StartupMeSnapshot {
+                    status: StartupMeStatus::Pending,
+                    current_stage: "pending".to_string(),
+                    init_attempt: 0,
+                    retry_limit: "unlimited".to_string(),
+                    last_error: None,
+                },
+                components: component_blueprint(),
+            }),
+        }
+    }
+
+    pub async fn set_transport_mode(&self, mode: &'static str) {
+        self.state.write().await.transport_mode = mode.to_string();
+    }
+
+    pub async fn set_degraded(&self, degraded: bool) {
+        self.state.write().await.degraded = degraded;
+    }
+
+    pub async fn start_component(&self, id: &'static str, details: Option<String>) {
+        let mut guard = self.state.write().await;
+        guard.current_stage = id.to_string();
+        if let Some(component) = guard.components.iter_mut().find(|component| component.id == id) {
+            if component.started_at_epoch_ms.is_none() {
+                component.started_at_epoch_ms = Some(now_epoch_ms());
+            }
+            component.attempts = component.attempts.saturating_add(1);
+            component.status = StartupComponentStatus::Running;
+            component.details = normalize_details(details);
+        }
+    }
+
+    pub async fn complete_component(&self, id: &'static str, details: Option<String>) {
+        self.finish_component(id, StartupComponentStatus::Ready, details)
+            .await;
+    }
+
+    pub async fn fail_component(&self, id: &'static str, details: Option<String>) {
+        self.finish_component(id, StartupComponentStatus::Failed, details)
+            .await;
+    }
+
+    pub async fn skip_component(&self, id: &'static str, details: Option<String>) {
+        self.finish_component(id, StartupComponentStatus::Skipped, details)
+            .await;
+    }
+
+    async fn finish_component(
+        &self,
+        id: &'static str,
+        status: StartupComponentStatus,
+        details: Option<String>,
+    ) {
+        let mut guard = self.state.write().await;
+        let finished_at = now_epoch_ms();
+        if let Some(component) = guard.components.iter_mut().find(|component| component.id == id) {
+            if component.started_at_epoch_ms.is_none() {
+                component.started_at_epoch_ms = Some(finished_at);
+                component.attempts = component.attempts.saturating_add(1);
+            }
+            component.finished_at_epoch_ms = Some(finished_at);
+            component.duration_ms = component
+                .started_at_epoch_ms
+                .map(|started_at| finished_at.saturating_sub(started_at));
+            component.status = status;
+            component.details = normalize_details(details);
+        }
+    }
+
+    pub async fn set_me_status(&self, status: StartupMeStatus, stage: &'static str) {
+        let mut guard = self.state.write().await;
+        guard.me.status = status;
+        guard.me.current_stage = stage.to_string();
+    }
+
+    pub async fn set_me_retry_limit(&self, retry_limit: String) {
+        self.state.write().await.me.retry_limit = retry_limit;
+    }
+
+    pub async fn set_me_init_attempt(&self, attempt: u32) {
+        self.state.write().await.me.init_attempt = attempt;
+    }
+
+    pub async fn set_me_last_error(&self, error: Option<String>) {
+        self.state.write().await.me.last_error = normalize_details(error);
+    }
+
+    pub async fn mark_ready(&self) {
+        let mut guard = self.state.write().await;
+        if guard.status == StartupStatus::Ready {
+            return;
+        }
+        guard.status = StartupStatus::Ready;
+        guard.current_stage = "ready".to_string();
+        guard.ready_at_epoch_secs = Some(now_epoch_secs());
+    }
+
+    pub async fn snapshot(&self) -> StartupSnapshot {
+        let guard = self.state.read().await;
+        StartupSnapshot {
+            status: guard.status,
+            degraded: guard.degraded,
+            current_stage: guard.current_stage.clone(),
+            started_at_epoch_secs: guard.started_at_epoch_secs,
+            ready_at_epoch_secs: guard.ready_at_epoch_secs,
+            total_elapsed_ms: self.started_at_instant.elapsed().as_millis() as u64,
+            transport_mode: guard.transport_mode.clone(),
+            me: guard.me.clone(),
+            components: guard
+                .components
+                .iter()
+                .map(|component| StartupComponentSnapshot {
+                    id: component.id,
+                    title: component.title,
+                    weight: component.weight,
+                    status: component.status,
+                    started_at_epoch_ms: component.started_at_epoch_ms,
+                    finished_at_epoch_ms: component.finished_at_epoch_ms,
+                    duration_ms: component.duration_ms,
+                    attempts: component.attempts,
+                    details: component.details.clone(),
+                })
+                .collect(),
+        }
+    }
+}
+
+pub fn compute_progress_pct(snapshot: &StartupSnapshot, me_stage_progress: Option<f64>) -> f64 {
+    if snapshot.status == StartupStatus::Ready {
+        return 100.0;
+    }
+
+    let mut total_weight = 0.0f64;
+    let mut completed_weight = 0.0f64;
+
+    for component in &snapshot.components {
+        total_weight += component.weight;
+        let unit_progress = match component.status {
+            StartupComponentStatus::Pending => 0.0,
+            StartupComponentStatus::Running => {
+                if component.id == COMPONENT_ME_POOL_INIT_STAGE1 {
+                    me_stage_progress.unwrap_or(0.0).clamp(0.0, 1.0)
+                } else {
+                    0.0
+                }
+            }
+            StartupComponentStatus::Ready
+            | StartupComponentStatus::Failed
+            | StartupComponentStatus::Skipped => 1.0,
+        };
+        completed_weight += component.weight * unit_progress;
+    }
+
+    if total_weight <= f64::EPSILON {
+        0.0
+    } else {
+        ((completed_weight / total_weight) * 100.0).clamp(0.0, 100.0)
+    }
+}
+
+fn component_blueprint() -> Vec<StartupComponent> {
+    vec![
+        component(COMPONENT_CONFIG_LOAD, "Config load", 5.0),
+        component(COMPONENT_TRACING_INIT, "Tracing init", 3.0),
+        component(COMPONENT_API_BOOTSTRAP, "API bootstrap", 5.0),
+        component(COMPONENT_TLS_FRONT_BOOTSTRAP, "TLS front bootstrap", 5.0),
+        component(COMPONENT_NETWORK_PROBE, "Network probe", 10.0),
+        component(COMPONENT_ME_SECRET_FETCH, "ME secret fetch", 8.0),
+        component(COMPONENT_ME_PROXY_CONFIG_V4, "ME config v4 fetch", 4.0),
+        component(COMPONENT_ME_PROXY_CONFIG_V6, "ME config v6 fetch", 4.0),
+        component(COMPONENT_ME_POOL_CONSTRUCT, "ME pool construct", 6.0),
+        component(COMPONENT_ME_POOL_INIT_STAGE1, "ME pool init stage1", 24.0),
+        component(COMPONENT_ME_CONNECTIVITY_PING, "ME connectivity ping", 6.0),
+        component(COMPONENT_DC_CONNECTIVITY_PING, "DC connectivity ping", 8.0),
+        component(COMPONENT_LISTENERS_BIND, "Listener bind", 8.0),
+        component(COMPONENT_CONFIG_WATCHER_START, "Config watcher start", 2.0),
+        component(COMPONENT_METRICS_START, "Metrics start", 1.0),
+        component(COMPONENT_RUNTIME_READY, "Runtime ready", 1.0),
+    ]
+}
+
+fn component(id: &'static str, title: &'static str, weight: f64) -> StartupComponent {
+    StartupComponent {
+        id,
+        title,
+        weight,
+        status: StartupComponentStatus::Pending,
+        started_at_epoch_ms: None,
+        finished_at_epoch_ms: None,
+        duration_ms: None,
+        attempts: 0,
+        details: None,
+    }
+}
+
+fn normalize_details(details: Option<String>) -> Option<String> {
+    details.map(|detail| {
+        if detail.len() <= 256 {
+            detail
+        } else {
+            detail[..256].to_string()
+        }
+    })
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}
+
+fn now_epoch_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}

src/stream/frame_codec.rs

@@ -513,6 +513,7 @@ impl FrameCodecTrait for SecureCodec {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::collections::HashSet;
     use tokio_util::codec::{FramedRead, FramedWrite};
     use tokio::io::duplex;
     use futures::{SinkExt, StreamExt};
@@ -630,4 +631,31 @@ mod tests {
         let result = codec.decode(&mut buf);
         assert!(result.is_err());
     }
+
+    #[test]
+    fn secure_codec_always_adds_padding_and_jitters_wire_length() {
+        let codec = SecureCodec::new(Arc::new(SecureRandom::new()));
+        let payload = Bytes::from_static(&[1, 2, 3, 4, 5, 6, 7, 8]);
+        let mut wire_lens = HashSet::new();
+
+        for _ in 0..64 {
+            let frame = Frame::new(payload.clone());
+            let mut out = BytesMut::new();
+            codec.encode(&frame, &mut out).unwrap();
+
+            assert!(out.len() >= 4 + payload.len() + 1);
+            let wire_len = u32::from_le_bytes([out[0], out[1], out[2], out[3]]) as usize;
+            assert!(
+                (payload.len() + 1..=payload.len() + 3).contains(&wire_len),
+                "Secure wire length must be payload+1..3, got {wire_len}"
+            );
+            assert_ne!(wire_len % 4, 0, "Secure wire length must be non-4-aligned");
+            wire_lens.insert(wire_len);
+        }
+
+        assert!(
+            wire_lens.len() >= 2,
+            "Secure padding should create observable wire-length jitter"
+        );
+    }
 }

src/tls_front/cache.rs

@@ -8,7 +8,9 @@ use tokio::sync::RwLock;
 use tokio::time::sleep;
 use tracing::{debug, warn, info};
 
-use crate::tls_front::types::{CachedTlsData, ParsedServerHello, TlsFetchResult};
+use crate::tls_front::types::{
+    CachedTlsData, ParsedServerHello, TlsBehaviorProfile, TlsFetchResult,
+};
 
 /// Lightweight in-memory + optional on-disk cache for TLS fronting data.
 #[derive(Debug)]
@@ -37,6 +39,7 @@ impl TlsFrontCache {
             cert_payload: None,
             app_data_records_sizes: vec![default_len],
             total_app_data_len: default_len,
+            behavior_profile: TlsBehaviorProfile::default(),
             fetched_at: SystemTime::now(),
             domain: "default".to_string(),
         });
@@ -189,6 +192,7 @@ impl TlsFrontCache {
             cert_payload: fetched.cert_payload,
             app_data_records_sizes: fetched.app_data_records_sizes.clone(),
             total_app_data_len: fetched.total_app_data_len,
+            behavior_profile: fetched.behavior_profile,
             fetched_at: SystemTime::now(),
             domain: domain.to_string(),
         };

src/tls_front/emulator.rs

@@ -3,7 +3,7 @@ use crate::protocol::constants::{
     TLS_RECORD_APPLICATION, TLS_RECORD_CHANGE_CIPHER, TLS_RECORD_HANDSHAKE, TLS_VERSION,
 };
 use crate::protocol::tls::{TLS_DIGEST_LEN, TLS_DIGEST_POS, gen_fake_x25519_key};
-use crate::tls_front::types::{CachedTlsData, ParsedCertificateInfo};
+use crate::tls_front::types::{CachedTlsData, ParsedCertificateInfo, TlsProfileSource};
 
 const MIN_APP_DATA: usize = 64;
 const MAX_APP_DATA: usize = 16640; // RFC 8446 §5.2 allows up to 2^14 + 256
@@ -108,14 +108,12 @@ pub fn build_emulated_server_hello(
 ) -> Vec<u8> {
     // --- ServerHello ---
     let mut extensions = Vec::new();
-    // KeyShare (x25519)
     let key = gen_fake_x25519_key(rng);
-    extensions.extend_from_slice(&0x0033u16.to_be_bytes()); // key_share
-    extensions.extend_from_slice(&(2 + 2 + 32u16).to_be_bytes()); // len
-    extensions.extend_from_slice(&0x001du16.to_be_bytes()); // X25519
+    extensions.extend_from_slice(&0x0033u16.to_be_bytes());
+    extensions.extend_from_slice(&(2 + 2 + 32u16).to_be_bytes());
+    extensions.extend_from_slice(&0x001du16.to_be_bytes());
     extensions.extend_from_slice(&(32u16).to_be_bytes());
     extensions.extend_from_slice(&key);
-    // supported_versions (TLS1.3)
     extensions.extend_from_slice(&0x002bu16.to_be_bytes());
     extensions.extend_from_slice(&(2u16).to_be_bytes());
     extensions.extend_from_slice(&0x0304u16.to_be_bytes());
@@ -128,7 +126,6 @@ pub fn build_emulated_server_hello(
         extensions.push(alpn_proto.len() as u8);
         extensions.extend_from_slice(alpn_proto);
     }
-
     let extensions_len = extensions.len() as u16;
 
     let body_len = 2 + // version
@@ -173,11 +170,22 @@ pub fn build_emulated_server_hello(
     ];
 
     // --- ApplicationData (fake encrypted records) ---
-    // Use the same number and sizes of ApplicationData records as the cached server.
-    let mut sizes = cached.app_data_records_sizes.clone();
-    if sizes.is_empty() {
-        sizes.push(cached.total_app_data_len.max(1024));
-    }
+    let sizes = match cached.behavior_profile.source {
+        TlsProfileSource::Raw | TlsProfileSource::Merged => cached
+            .app_data_records_sizes
+            .first()
+            .copied()
+            .or_else(|| cached.behavior_profile.app_data_record_sizes.first().copied())
+            .map(|size| vec![size])
+            .unwrap_or_else(|| vec![cached.total_app_data_len.max(1024)]),
+        _ => {
+            let mut sizes = cached.app_data_records_sizes.clone();
+            if sizes.is_empty() {
+                sizes.push(cached.total_app_data_len.max(1024));
+            }
+            sizes
+        }
+    };
     let mut sizes = jitter_and_clamp_sizes(&sizes, rng);
     let compact_payload = cached
         .cert_info
@@ -269,7 +277,9 @@ pub fn build_emulated_server_hello(
 mod tests {
     use std::time::SystemTime;
 
-    use crate::tls_front::types::{CachedTlsData, ParsedServerHello, TlsCertPayload};
+    use crate::tls_front::types::{
+        CachedTlsData, ParsedServerHello, TlsBehaviorProfile, TlsCertPayload, TlsProfileSource,
+    };
 
     use super::build_emulated_server_hello;
     use crate::crypto::SecureRandom;
@@ -300,6 +310,7 @@ mod tests {
             cert_payload,
             app_data_records_sizes: vec![64],
             total_app_data_len: 64,
+            behavior_profile: TlsBehaviorProfile::default(),
             fetched_at: SystemTime::now(),
             domain: "example.com".to_string(),
         }
@@ -385,4 +396,34 @@ mod tests {
         let payload = first_app_data_payload(&response);
         assert!(payload.starts_with(b"CN=example.com"));
     }
+
+    #[test]
+    fn test_build_emulated_server_hello_ignores_tail_records_for_raw_profile() {
+        let mut cached = make_cached(None);
+        cached.app_data_records_sizes = vec![27, 3905, 537, 69];
+        cached.total_app_data_len = 4538;
+        cached.behavior_profile.source = TlsProfileSource::Merged;
+        cached.behavior_profile.app_data_record_sizes = vec![27, 3905, 537];
+        cached.behavior_profile.ticket_record_sizes = vec![69];
+
+        let rng = SecureRandom::new();
+        let response = build_emulated_server_hello(
+            b"secret",
+            &[0x12; 32],
+            &[0x34; 16],
+            &cached,
+            false,
+            &rng,
+            None,
+            0,
+        );
+
+        let hello_len = u16::from_be_bytes([response[3], response[4]]) as usize;
+        let ccs_start = 5 + hello_len;
+        let app_start = ccs_start + 6;
+        let app_len = u16::from_be_bytes([response[app_start + 3], response[app_start + 4]]) as usize;
+
+        assert_eq!(response[app_start], TLS_RECORD_APPLICATION);
+        assert_eq!(app_start + 5 + app_len, response.len());
+    }
 }

src/tls_front/fetcher.rs

@@ -21,14 +21,18 @@ use x509_parser::certificate::X509Certificate;
 
 use crate::crypto::SecureRandom;
 use crate::network::dns_overrides::resolve_socket_addr;
-use crate::protocol::constants::{TLS_RECORD_APPLICATION, TLS_RECORD_HANDSHAKE};
+use crate::protocol::constants::{
+    TLS_RECORD_APPLICATION, TLS_RECORD_CHANGE_CIPHER, TLS_RECORD_HANDSHAKE,
+};
 use crate::transport::proxy_protocol::{ProxyProtocolV1Builder, ProxyProtocolV2Builder};
 use crate::tls_front::types::{
     ParsedCertificateInfo,
     ParsedServerHello,
+    TlsBehaviorProfile,
     TlsCertPayload,
     TlsExtension,
     TlsFetchResult,
+    TlsProfileSource,
 };
 
 /// No-op verifier: accept any certificate (we only need lengths and metadata).
@@ -282,6 +286,41 @@ fn parse_server_hello(body: &[u8]) -> Option<ParsedServerHello> {
     })
 }
 
+fn derive_behavior_profile(records: &[(u8, Vec<u8>)]) -> TlsBehaviorProfile {
+    let mut change_cipher_spec_count = 0u8;
+    let mut app_data_record_sizes = Vec::new();
+
+    for (record_type, body) in records {
+        match *record_type {
+            TLS_RECORD_CHANGE_CIPHER => {
+                change_cipher_spec_count = change_cipher_spec_count.saturating_add(1);
+            }
+            TLS_RECORD_APPLICATION => {
+                app_data_record_sizes.push(body.len());
+            }
+            _ => {}
+        }
+    }
+
+    let mut ticket_record_sizes = Vec::new();
+    while app_data_record_sizes
+        .last()
+        .is_some_and(|size| *size <= 256 && ticket_record_sizes.len() < 2)
+    {
+        if let Some(size) = app_data_record_sizes.pop() {
+            ticket_record_sizes.push(size);
+        }
+    }
+    ticket_record_sizes.reverse();
+
+    TlsBehaviorProfile {
+        change_cipher_spec_count: change_cipher_spec_count.max(1),
+        app_data_record_sizes,
+        ticket_record_sizes,
+        source: TlsProfileSource::Raw,
+    }
+}
+
 fn parse_cert_info(certs: &[CertificateDer<'static>]) -> Option<ParsedCertificateInfo> {
     let first = certs.first()?;
     let (_rem, cert) = X509Certificate::from_der(first.as_ref()).ok()?;
@@ -443,39 +482,50 @@ where
     .await??;
 
     let mut records = Vec::new();
-    // Read up to 4 records: ServerHello, CCS, and up to two ApplicationData.
-    for _ in 0..4 {
+    let mut app_records_seen = 0usize;
+    // Read a bounded encrypted flight: ServerHello, CCS, certificate-like data,
+    // and a small number of ticket-like tail records.
+    for _ in 0..8 {
         match timeout(connect_timeout, read_tls_record(&mut stream)).await {
-            Ok(Ok(rec)) => records.push(rec),
+            Ok(Ok(rec)) => {
+                if rec.0 == TLS_RECORD_APPLICATION {
+                    app_records_seen += 1;
+                }
+                records.push(rec);
+            }
             Ok(Err(e)) => return Err(e),
             Err(_) => break,
         }
-        if records.len() >= 3 && records.iter().any(|(t, _)| *t == TLS_RECORD_APPLICATION) {
+        if app_records_seen >= 4 {
             break;
         }
     }
 
-    let mut app_sizes = Vec::new();
     let mut server_hello = None;
     for (t, body) in &records {
         if *t == TLS_RECORD_HANDSHAKE && server_hello.is_none() {
             server_hello = parse_server_hello(body);
-        } else if *t == TLS_RECORD_APPLICATION {
-            app_sizes.push(body.len());
         }
     }
 
     let parsed = server_hello.ok_or_else(|| anyhow!("ServerHello not received"))?;
+    let behavior_profile = derive_behavior_profile(&records);
+    let mut app_sizes = behavior_profile.app_data_record_sizes.clone();
+    app_sizes.extend_from_slice(&behavior_profile.ticket_record_sizes);
     let total_app_data_len = app_sizes.iter().sum::<usize>().max(1024);
+    let app_data_records_sizes = behavior_profile
+        .app_data_record_sizes
+        .first()
+        .copied()
+        .or_else(|| behavior_profile.ticket_record_sizes.first().copied())
+        .map(|size| vec![size])
+        .unwrap_or_else(|| vec![total_app_data_len]);
 
     Ok(TlsFetchResult {
         server_hello_parsed: parsed,
-        app_data_records_sizes: if app_sizes.is_empty() {
-            vec![total_app_data_len]
-        } else {
-            app_sizes
-        },
+        app_data_records_sizes,
         total_app_data_len,
+        behavior_profile,
         cert_info: None,
         cert_payload: None,
     })
@@ -608,6 +658,12 @@ where
         server_hello_parsed: parsed,
         app_data_records_sizes: app_data_records_sizes.clone(),
         total_app_data_len: app_data_records_sizes.iter().sum(),
+        behavior_profile: TlsBehaviorProfile {
+            change_cipher_spec_count: 1,
+            app_data_record_sizes: app_data_records_sizes,
+            ticket_record_sizes: Vec::new(),
+            source: TlsProfileSource::Rustls,
+        },
         cert_info,
         cert_payload,
     })
@@ -706,6 +762,7 @@ pub async fn fetch_real_tls(
             if let Some(mut raw) = raw_result {
                 raw.cert_info = rustls_result.cert_info;
                 raw.cert_payload = rustls_result.cert_payload;
+                raw.behavior_profile.source = TlsProfileSource::Merged;
                 debug!(sni = %sni, "Fetched TLS metadata via raw probe + rustls cert chain");
                 Ok(raw)
             } else {
@@ -725,7 +782,11 @@ pub async fn fetch_real_tls(
 
 #[cfg(test)]
 mod tests {
-    use super::encode_tls13_certificate_message;
+    use super::{derive_behavior_profile, encode_tls13_certificate_message};
+    use crate::protocol::constants::{
+        TLS_RECORD_APPLICATION, TLS_RECORD_CHANGE_CIPHER, TLS_RECORD_HANDSHAKE,
+    };
+    use crate::tls_front::types::TlsProfileSource;
 
     fn read_u24(bytes: &[u8]) -> usize {
         ((bytes[0] as usize) << 16) | ((bytes[1] as usize) << 8) | (bytes[2] as usize)
@@ -753,4 +814,20 @@ mod tests {
     fn test_encode_tls13_certificate_message_empty_chain() {
         assert!(encode_tls13_certificate_message(&[]).is_none());
     }
+
+    #[test]
+    fn test_derive_behavior_profile_splits_ticket_like_tail_records() {
+        let profile = derive_behavior_profile(&[
+            (TLS_RECORD_HANDSHAKE, vec![0u8; 90]),
+            (TLS_RECORD_CHANGE_CIPHER, vec![0x01]),
+            (TLS_RECORD_APPLICATION, vec![0u8; 1400]),
+            (TLS_RECORD_APPLICATION, vec![0u8; 220]),
+            (TLS_RECORD_APPLICATION, vec![0u8; 180]),
+        ]);
+
+        assert_eq!(profile.change_cipher_spec_count, 1);
+        assert_eq!(profile.app_data_record_sizes, vec![1400]);
+        assert_eq!(profile.ticket_record_sizes, vec![220, 180]);
+        assert_eq!(profile.source, TlsProfileSource::Raw);
+    }
 }

src/tls_front/types.rs

@@ -39,6 +39,53 @@ pub struct TlsCertPayload {
     pub certificate_message: Vec<u8>,
 }
 
+/// Provenance of the cached TLS behavior profile.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum TlsProfileSource {
+    /// Built from hardcoded defaults or legacy cache entries.
+    #[default]
+    Default,
+    /// Derived from raw TLS record capture only.
+    Raw,
+    /// Derived from rustls-only metadata fallback.
+    Rustls,
+    /// Merged from raw TLS capture and rustls certificate metadata.
+    Merged,
+}
+
+/// Coarse-grained TLS response behavior captured per SNI.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TlsBehaviorProfile {
+    /// Number of ChangeCipherSpec records observed before encrypted flight.
+    #[serde(default = "default_change_cipher_spec_count")]
+    pub change_cipher_spec_count: u8,
+    /// Sizes of the primary encrypted flight records carrying cert-like payload.
+    #[serde(default)]
+    pub app_data_record_sizes: Vec<usize>,
+    /// Sizes of small tail ApplicationData records that look like tickets.
+    #[serde(default)]
+    pub ticket_record_sizes: Vec<usize>,
+    /// Source of this behavior profile.
+    #[serde(default)]
+    pub source: TlsProfileSource,
+}
+
+fn default_change_cipher_spec_count() -> u8 {
+    1
+}
+
+impl Default for TlsBehaviorProfile {
+    fn default() -> Self {
+        Self {
+            change_cipher_spec_count: default_change_cipher_spec_count(),
+            app_data_record_sizes: Vec::new(),
+            ticket_record_sizes: Vec::new(),
+            source: TlsProfileSource::Default,
+        }
+    }
+}
+
 /// Cached data per SNI used by the emulator.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CachedTlsData {
@@ -48,6 +95,8 @@ pub struct CachedTlsData {
     pub cert_payload: Option<TlsCertPayload>,
     pub app_data_records_sizes: Vec<usize>,
     pub total_app_data_len: usize,
+    #[serde(default)]
+    pub behavior_profile: TlsBehaviorProfile,
     #[serde(default = "now_system_time", skip_serializing, skip_deserializing)]
     pub fetched_at: SystemTime,
     pub domain: String,
@@ -63,6 +112,40 @@ pub struct TlsFetchResult {
     pub server_hello_parsed: ParsedServerHello,
     pub app_data_records_sizes: Vec<usize>,
     pub total_app_data_len: usize,
+    #[serde(default)]
+    pub behavior_profile: TlsBehaviorProfile,
     pub cert_info: Option<ParsedCertificateInfo>,
     pub cert_payload: Option<TlsCertPayload>,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cached_tls_data_deserializes_without_behavior_profile() {
+        let json = r#"
+        {
+            "server_hello_template": {
+                "version": [3, 3],
+                "random": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+                "session_id": [],
+                "cipher_suite": [19, 1],
+                "compression": 0,
+                "extensions": []
+            },
+            "cert_info": null,
+            "cert_payload": null,
+            "app_data_records_sizes": [1024],
+            "total_app_data_len": 1024,
+            "domain": "example.com"
+        }
+        "#;
+
+        let cached: CachedTlsData = serde_json::from_str(json).unwrap();
+        assert_eq!(cached.behavior_profile.change_cipher_spec_count, 1);
+        assert!(cached.behavior_profile.app_data_record_sizes.is_empty());
+        assert!(cached.behavior_profile.ticket_record_sizes.is_empty());
+        assert_eq!(cached.behavior_profile.source, TlsProfileSource::Default);
+    }
+}

src/transport/middle_proxy/codec.rs

@@ -1,4 +1,5 @@
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use bytes::Bytes;
 
 use crate::crypto::{AesCbc, crc32, crc32c};
 use crate::error::{ProxyError, Result};
@@ -6,8 +7,8 @@ use crate::protocol::constants::*;
 
 /// Commands sent to dedicated writer tasks to avoid mutex contention on TCP writes.
 pub(crate) enum WriterCommand {
-    Data(Vec<u8>),
-    DataAndFlush(Vec<u8>),
+    Data(Bytes),
+    DataAndFlush(Bytes),
     Close,
 }
 

src/transport/middle_proxy/config_updater.rs

@@ -1,6 +1,7 @@
 use std::collections::HashMap;
 use std::hash::{DefaultHasher, Hash, Hasher};
 use std::net::IpAddr;
+use std::path::Path;
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -14,6 +15,7 @@ use crate::error::Result;
 use super::MePool;
 use super::rotation::{MeReinitTrigger, enqueue_reinit_trigger};
 use super::secret::download_proxy_secret_with_max_len;
+use super::selftest::record_timeskew_sample;
 use std::time::SystemTime;
 
 async fn retry_fetch(url: &str) -> Option<ProxyConfigData> {
@@ -42,6 +44,88 @@ pub struct ProxyConfigData {
     pub proxy_for_lines: u32,
 }
 
+pub fn parse_proxy_config_text(text: &str, http_status: u16) -> ProxyConfigData {
+    let mut map: HashMap<i32, Vec<(IpAddr, u16)>> = HashMap::new();
+    let mut proxy_for_lines: u32 = 0;
+    for line in text.lines() {
+        if let Some((dc, ip, port)) = parse_proxy_line(line) {
+            map.entry(dc).or_default().push((ip, port));
+            proxy_for_lines = proxy_for_lines.saturating_add(1);
+        }
+    }
+
+    let default_dc = text.lines().find_map(|l| {
+        let t = l.trim();
+        if let Some(rest) = t.strip_prefix("default") {
+            return rest.trim().trim_end_matches(';').parse::<i32>().ok();
+        }
+        None
+    });
+
+    ProxyConfigData {
+        map,
+        default_dc,
+        http_status,
+        proxy_for_lines,
+    }
+}
+
+pub async fn load_proxy_config_cache(path: &str) -> Result<ProxyConfigData> {
+    let text = tokio::fs::read_to_string(path).await.map_err(|e| {
+        crate::error::ProxyError::Proxy(format!("read proxy-config cache '{path}' failed: {e}"))
+    })?;
+    Ok(parse_proxy_config_text(&text, 200))
+}
+
+pub async fn save_proxy_config_cache(path: &str, raw_text: &str) -> Result<()> {
+    if let Some(parent) = Path::new(path).parent()
+        && !parent.as_os_str().is_empty()
+    {
+        tokio::fs::create_dir_all(parent).await.map_err(|e| {
+            crate::error::ProxyError::Proxy(format!(
+                "create proxy-config cache dir '{}' failed: {e}",
+                parent.display()
+            ))
+        })?;
+    }
+
+    tokio::fs::write(path, raw_text).await.map_err(|e| {
+        crate::error::ProxyError::Proxy(format!("write proxy-config cache '{path}' failed: {e}"))
+    })?;
+    Ok(())
+}
+
+pub async fn fetch_proxy_config_with_raw(url: &str) -> Result<(ProxyConfigData, String)> {
+    let resp = reqwest::get(url)
+        .await
+        .map_err(|e| crate::error::ProxyError::Proxy(format!("fetch_proxy_config GET failed: {e}")))?
+        ;
+    let http_status = resp.status().as_u16();
+
+    if let Some(date) = resp.headers().get(reqwest::header::DATE)
+        && let Ok(date_str) = date.to_str()
+        && let Ok(server_time) = httpdate::parse_http_date(date_str)
+        && let Ok(skew) = SystemTime::now().duration_since(server_time).or_else(|e| {
+            server_time.duration_since(SystemTime::now()).map_err(|_| e)
+        })
+    {
+        let skew_secs = skew.as_secs();
+        record_timeskew_sample("proxy_config_date_header", skew_secs);
+        if skew_secs > 60 {
+            warn!(skew_secs, "Time skew >60s detected from fetch_proxy_config Date header");
+        } else if skew_secs > 30 {
+            warn!(skew_secs, "Time skew >30s detected from fetch_proxy_config Date header");
+        }
+    }
+
+    let text = resp
+        .text()
+        .await
+        .map_err(|e| crate::error::ProxyError::Proxy(format!("fetch_proxy_config read failed: {e}")))?;
+    let parsed = parse_proxy_config_text(&text, http_status);
+    Ok((parsed, text))
+}
+
 #[derive(Debug, Default)]
 struct StableSnapshot {
     candidate_hash: Option<u64>,
@@ -170,61 +254,9 @@ fn parse_proxy_line(line: &str) -> Option<(i32, IpAddr, u16)> {
 }
 
 pub async fn fetch_proxy_config(url: &str) -> Result<ProxyConfigData> {
-    let resp = reqwest::get(url)
+    fetch_proxy_config_with_raw(url)
         .await
-        .map_err(|e| crate::error::ProxyError::Proxy(format!("fetch_proxy_config GET failed: {e}")))?
-        ;
-    let http_status = resp.status().as_u16();
-
-    if let Some(date) = resp.headers().get(reqwest::header::DATE)
-        && let Ok(date_str) = date.to_str()
-        && let Ok(server_time) = httpdate::parse_http_date(date_str)
-        && let Ok(skew) = SystemTime::now().duration_since(server_time).or_else(|e| {
-            server_time.duration_since(SystemTime::now()).map_err(|_| e)
-        })
-    {
-        let skew_secs = skew.as_secs();
-        if skew_secs > 60 {
-            warn!(skew_secs, "Time skew >60s detected from fetch_proxy_config Date header");
-        } else if skew_secs > 30 {
-            warn!(skew_secs, "Time skew >30s detected from fetch_proxy_config Date header");
-        }
-    }
-
-    let text = resp
-        .text()
-        .await
-        .map_err(|e| crate::error::ProxyError::Proxy(format!("fetch_proxy_config read failed: {e}")))?;
-
-    let mut map: HashMap<i32, Vec<(IpAddr, u16)>> = HashMap::new();
-    let mut proxy_for_lines: u32 = 0;
-    for line in text.lines() {
-        if let Some((dc, ip, port)) = parse_proxy_line(line) {
-            map.entry(dc).or_default().push((ip, port));
-            proxy_for_lines = proxy_for_lines.saturating_add(1);
-        }
-    }
-
-    let default_dc = text
-        .lines()
-        .find_map(|l| {
-            let t = l.trim();
-            if let Some(rest) = t.strip_prefix("default") {
-                return rest
-                    .trim()
-                    .trim_end_matches(';')
-                    .parse::<i32>()
-                    .ok();
-            }
-            None
-        });
-
-    Ok(ProxyConfigData {
-        map,
-        default_dc,
-        http_status,
-        proxy_for_lines,
-    })
+        .map(|(parsed, _raw)| parsed)
 }
 
 fn snapshot_passes_guards(
@@ -266,6 +298,7 @@ async fn run_update_cycle(
     pool.update_runtime_reinit_policy(
         cfg.general.hardswap,
         cfg.general.me_pool_drain_ttl_secs,
+        cfg.general.me_pool_drain_threshold,
         cfg.general.effective_me_pool_force_close_secs(),
         cfg.general.me_pool_min_fresh_ratio,
         cfg.general.me_hardswap_warmup_delay_min_ms,
@@ -276,12 +309,30 @@ async fn run_update_cycle(
         cfg.general.me_bind_stale_ttl_secs,
         cfg.general.me_secret_atomic_snapshot,
         cfg.general.me_deterministic_writer_sort,
+        cfg.general.me_writer_pick_mode,
+        cfg.general.me_writer_pick_sample_size,
         cfg.general.me_single_endpoint_shadow_writers,
         cfg.general.me_single_endpoint_outage_mode_enabled,
         cfg.general.me_single_endpoint_outage_disable_quarantine,
         cfg.general.me_single_endpoint_outage_backoff_min_ms,
         cfg.general.me_single_endpoint_outage_backoff_max_ms,
         cfg.general.me_single_endpoint_shadow_rotate_every_secs,
+        cfg.general.me_floor_mode,
+        cfg.general.me_adaptive_floor_idle_secs,
+        cfg.general.me_adaptive_floor_min_writers_single_endpoint,
+        cfg.general.me_adaptive_floor_min_writers_multi_endpoint,
+        cfg.general.me_adaptive_floor_recover_grace_secs,
+        cfg.general.me_adaptive_floor_writers_per_core_total,
+        cfg.general.me_adaptive_floor_cpu_cores_override,
+        cfg.general.me_adaptive_floor_max_extra_writers_single_per_core,
+        cfg.general.me_adaptive_floor_max_extra_writers_multi_per_core,
+        cfg.general.me_adaptive_floor_max_active_writers_per_core,
+        cfg.general.me_adaptive_floor_max_warm_writers_per_core,
+        cfg.general.me_adaptive_floor_max_active_writers_global,
+        cfg.general.me_adaptive_floor_max_warm_writers_global,
+        cfg.general.me_health_interval_ms_unhealthy,
+        cfg.general.me_health_interval_ms_healthy,
+        cfg.general.me_warn_rate_limit_ms,
     );
 
     let required_cfg_snapshots = cfg.general.me_config_stable_snapshots.max(1);
@@ -474,6 +525,7 @@ pub async fn me_config_updater(
                 pool.update_runtime_reinit_policy(
                     cfg.general.hardswap,
                     cfg.general.me_pool_drain_ttl_secs,
+                    cfg.general.me_pool_drain_threshold,
                     cfg.general.effective_me_pool_force_close_secs(),
                     cfg.general.me_pool_min_fresh_ratio,
                     cfg.general.me_hardswap_warmup_delay_min_ms,
@@ -484,12 +536,30 @@ pub async fn me_config_updater(
                     cfg.general.me_bind_stale_ttl_secs,
                     cfg.general.me_secret_atomic_snapshot,
                     cfg.general.me_deterministic_writer_sort,
+                    cfg.general.me_writer_pick_mode,
+                    cfg.general.me_writer_pick_sample_size,
                     cfg.general.me_single_endpoint_shadow_writers,
                     cfg.general.me_single_endpoint_outage_mode_enabled,
                     cfg.general.me_single_endpoint_outage_disable_quarantine,
                     cfg.general.me_single_endpoint_outage_backoff_min_ms,
                     cfg.general.me_single_endpoint_outage_backoff_max_ms,
                     cfg.general.me_single_endpoint_shadow_rotate_every_secs,
+                    cfg.general.me_floor_mode,
+                    cfg.general.me_adaptive_floor_idle_secs,
+                    cfg.general.me_adaptive_floor_min_writers_single_endpoint,
+                    cfg.general.me_adaptive_floor_min_writers_multi_endpoint,
+                    cfg.general.me_adaptive_floor_recover_grace_secs,
+                    cfg.general.me_adaptive_floor_writers_per_core_total,
+                    cfg.general.me_adaptive_floor_cpu_cores_override,
+                    cfg.general.me_adaptive_floor_max_extra_writers_single_per_core,
+                    cfg.general.me_adaptive_floor_max_extra_writers_multi_per_core,
+                    cfg.general.me_adaptive_floor_max_active_writers_per_core,
+                    cfg.general.me_adaptive_floor_max_warm_writers_per_core,
+                    cfg.general.me_adaptive_floor_max_active_writers_global,
+                    cfg.general.me_adaptive_floor_max_warm_writers_global,
+                    cfg.general.me_health_interval_ms_unhealthy,
+                    cfg.general.me_health_interval_ms_healthy,
+                    cfg.general.me_warn_rate_limit_ms,
                 );
                 let new_secs = cfg.general.effective_update_every_secs().max(1);
                 if new_secs == update_every_secs {

src/transport/middle_proxy/handshake.rs

@@ -33,15 +33,33 @@ use super::codec::{
     cbc_decrypt_inplace, cbc_encrypt_padded, parse_handshake_flags, parse_nonce_payload,
     read_rpc_frame_plaintext, rpc_crc,
 };
+use super::selftest::{BndAddrStatus, BndPortStatus, record_bnd_status, record_upstream_bnd_status};
 use super::wire::{extract_ip_material, IpMaterial};
 use super::MePool;
 
 const ME_KDF_DRIFT_STRICT: bool = false;
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+enum KdfClientPortSource {
+    LocalSocket = 0,
+    SocksBound = 1,
+}
+
+impl KdfClientPortSource {
+    fn from_socks_bound_port(socks_bound_port: Option<u16>) -> Self {
+        if socks_bound_port.is_some() {
+            Self::SocksBound
+        } else {
+            Self::LocalSocket
+        }
+    }
+}
+
 /// Result of a successful ME handshake with timings.
 pub(crate) struct HandshakeOutput {
     pub rd: ReadHalf<TcpStream>,
     pub wr: WriteHalf<TcpStream>,
+    pub source_ip: IpAddr,
     pub read_key: [u8; 32],
     pub read_iv: [u8; 16],
     pub write_key: [u8; 32],
@@ -52,54 +70,23 @@ pub(crate) struct HandshakeOutput {
 
 impl MePool {
     fn kdf_material_fingerprint(
-        local_addr_nat: SocketAddr,
+        local_ip_nat: IpAddr,
         peer_addr_nat: SocketAddr,
-        client_port_for_kdf: u16,
-        reflected: Option<SocketAddr>,
-        socks_bound_addr: Option<SocketAddr>,
+        reflected_ip: Option<IpAddr>,
+        socks_bound_ip: Option<IpAddr>,
+        client_port_source: KdfClientPortSource,
     ) -> u64 {
         let mut hasher = DefaultHasher::new();
-        local_addr_nat.hash(&mut hasher);
+        local_ip_nat.hash(&mut hasher);
         peer_addr_nat.hash(&mut hasher);
-        client_port_for_kdf.hash(&mut hasher);
-        reflected.hash(&mut hasher);
-        socks_bound_addr.hash(&mut hasher);
+        reflected_ip.hash(&mut hasher);
+        socks_bound_ip.hash(&mut hasher);
+        client_port_source.hash(&mut hasher);
         hasher.finish()
     }
 
     async fn resolve_dc_idx_for_endpoint(&self, addr: SocketAddr) -> Option<i16> {
-        if addr.is_ipv4() {
-            let map = self.proxy_map_v4.read().await;
-            for (dc, addrs) in map.iter() {
-                if addrs
-                    .iter()
-                    .any(|(ip, port)| SocketAddr::new(*ip, *port) == addr)
-                {
-                    let abs_dc = dc.abs();
-                    if abs_dc > 0
-                        && let Ok(dc_idx) = i16::try_from(abs_dc)
-                    {
-                        return Some(dc_idx);
-                    }
-                }
-            }
-        } else {
-            let map = self.proxy_map_v6.read().await;
-            for (dc, addrs) in map.iter() {
-                if addrs
-                    .iter()
-                    .any(|(ip, port)| SocketAddr::new(*ip, *port) == addr)
-                {
-                    let abs_dc = dc.abs();
-                    if abs_dc > 0
-                        && let Ok(dc_idx) = i16::try_from(abs_dc)
-                    {
-                        return Some(dc_idx);
-                    }
-                }
-            }
-        }
-        None
+        i16::try_from(self.resolve_dc_for_endpoint(addr).await).ok()
     }
 
     fn direct_bind_ip_for_stun(
@@ -146,14 +133,27 @@ impl MePool {
         )
     }
 
+    fn bnd_port_status(bound: Option<SocketAddr>) -> BndPortStatus {
+        match bound {
+            Some(addr) if addr.port() == 0 => BndPortStatus::Zero,
+            Some(_) => BndPortStatus::Ok,
+            None => BndPortStatus::Error,
+        }
+    }
+
     /// TCP connect with timeout + return RTT in milliseconds.
     pub(crate) async fn connect_tcp(
         &self,
         addr: SocketAddr,
+        dc_idx_override: Option<i16>,
     ) -> Result<(TcpStream, f64, Option<UpstreamEgressInfo>)> {
         let start = Instant::now();
         let (stream, upstream_egress) = if let Some(upstream) = &self.upstream {
-            let dc_idx = self.resolve_dc_idx_for_endpoint(addr).await;
+            let dc_idx = if let Some(dc_idx) = dc_idx_override {
+                Some(dc_idx)
+            } else {
+                self.resolve_dc_idx_for_endpoint(addr).await
+            };
             let (stream, egress) = upstream.connect_with_details(addr, dc_idx, None).await?;
             (stream, Some(egress))
         } else {
@@ -200,10 +200,26 @@ impl MePool {
 
     fn configure_keepalive(stream: &TcpStream) -> std::io::Result<()> {
         let sock = SockRef::from(stream);
-        let ka = TcpKeepalive::new()
-            .with_time(Duration::from_secs(30))
-            .with_interval(Duration::from_secs(10))
-            .with_retries(3);
+        let ka = TcpKeepalive::new().with_time(Duration::from_secs(30));
+
+        // Mirror socket2 v0.5.10 target gate for with_retries(), the stricter method.
+        #[cfg(any(
+            target_os = "android",
+            target_os = "dragonfly",
+            target_os = "freebsd",
+            target_os = "fuchsia",
+            target_os = "illumos",
+            target_os = "ios",
+            target_os = "visionos",
+            target_os = "linux",
+            target_os = "macos",
+            target_os = "netbsd",
+            target_os = "tvos",
+            target_os = "watchos",
+            target_os = "cygwin",
+        ))]
+        let ka = ka.with_interval(Duration::from_secs(10)).with_retries(3);
+
         sock.set_tcp_keepalive(&ka)?;
         sock.set_keepalive(true)?;
         Ok(())
@@ -249,7 +265,27 @@ impl MePool {
             IpFamily::V6
         };
         let is_socks_route = Self::is_socks_route(upstream_egress);
+        let raw_socks_bound_addr = if is_socks_route {
+            upstream_egress.and_then(|info| info.socks_bound_addr)
+        } else {
+            None
+        };
         let socks_bound_addr = Self::select_socks_bound_addr(family, upstream_egress);
+        let bnd_addr_status = if !is_socks_route {
+            BndAddrStatus::Error
+        } else if raw_socks_bound_addr.is_some() && socks_bound_addr.is_none() {
+            BndAddrStatus::Bogon
+        } else if socks_bound_addr.is_some() {
+            BndAddrStatus::Ok
+        } else {
+            BndAddrStatus::Error
+        };
+        let bnd_port_status = if is_socks_route {
+            Self::bnd_port_status(raw_socks_bound_addr)
+        } else {
+            BndPortStatus::Error
+        };
+        record_bnd_status(bnd_addr_status, bnd_port_status, raw_socks_bound_addr);
         let reflected = if let Some(bound) = socks_bound_addr {
             Some(bound)
         } else if is_socks_route {
@@ -280,6 +316,18 @@ impl MePool {
 
         let local_addr_nat = self.translate_our_addr_with_reflection(local_addr, reflected);
         let peer_addr_nat = SocketAddr::new(self.translate_ip_for_nat(peer_addr.ip()), peer_addr.port());
+        if let Some(upstream_info) = upstream_egress {
+            let client_ip_for_kdf = socks_bound_addr
+                .map(|value| value.ip())
+                .unwrap_or(local_addr_nat.ip());
+            record_upstream_bnd_status(
+                upstream_info.upstream_id,
+                bnd_addr_status,
+                bnd_port_status,
+                raw_socks_bound_addr,
+                Some(client_ip_for_kdf),
+            );
+        }
         let (mut rd, mut wr) = tokio::io::split(stream);
 
         let my_nonce: [u8; 16] = rng.bytes(16).try_into().unwrap();
@@ -359,35 +407,53 @@ impl MePool {
 
         let ts_bytes = crypto_ts.to_le_bytes();
         let server_port_bytes = peer_addr_nat.port().to_le_bytes();
-        let client_port_for_kdf = socks_bound_addr
+        let socks_bound_port = socks_bound_addr
             .map(|bound| bound.port())
-            .filter(|port| *port != 0)
-            .unwrap_or(local_addr_nat.port());
+            .filter(|port| *port != 0);
+        let client_port_for_kdf = socks_bound_port.unwrap_or(local_addr_nat.port());
+        let client_port_source = KdfClientPortSource::from_socks_bound_port(socks_bound_port);
         let kdf_fingerprint = Self::kdf_material_fingerprint(
-            local_addr_nat,
+            local_addr_nat.ip(),
             peer_addr_nat,
-            client_port_for_kdf,
-            reflected,
-            socks_bound_addr,
+            reflected.map(|value| value.ip()),
+            socks_bound_addr.map(|value| value.ip()),
+            client_port_source,
         );
-        let mut kdf_fingerprint_guard = self.kdf_material_fingerprint.lock().await;
-        if let Some(prev_fingerprint) = kdf_fingerprint_guard.get(&peer_addr_nat).copied()
-            && prev_fingerprint != kdf_fingerprint
+        let previous_kdf_fingerprint = {
+            let kdf_fingerprint_guard = self.kdf_material_fingerprint.read().await;
+            kdf_fingerprint_guard.get(&peer_addr_nat).copied()
+        };
+        if let Some((prev_fingerprint, prev_client_port)) = previous_kdf_fingerprint
         {
-            self.stats.increment_me_kdf_drift_total();
-            warn!(
-                %peer_addr_nat,
-                %local_addr_nat,
-                client_port_for_kdf,
-                "ME KDF input drift detected for endpoint"
-            );
-            if ME_KDF_DRIFT_STRICT {
-                return Err(ProxyError::InvalidHandshake(
-                    "ME KDF input drift detected (strict mode)".to_string(),
-                ));
+            if prev_fingerprint != kdf_fingerprint {
+                self.stats.increment_me_kdf_drift_total();
+                warn!(
+                    %peer_addr_nat,
+                    %local_addr_nat,
+                    client_port_for_kdf,
+                    client_port_source = ?client_port_source,
+                    "ME KDF material drift detected for endpoint"
+                );
+                if ME_KDF_DRIFT_STRICT {
+                    return Err(ProxyError::InvalidHandshake(
+                        "ME KDF material drift detected (strict mode)".to_string(),
+                    ));
+                }
+            } else if prev_client_port != client_port_for_kdf {
+                self.stats.increment_me_kdf_port_only_drift_total();
+                debug!(
+                    %peer_addr_nat,
+                    previous_client_port_for_kdf = prev_client_port,
+                    client_port_for_kdf,
+                    client_port_source = ?client_port_source,
+                    "ME KDF client port changed with stable material"
+                );
             }
         }
-        kdf_fingerprint_guard.insert(peer_addr_nat, kdf_fingerprint);
+        // Keep fingerprint updates eventually consistent for diagnostics while avoiding
+        // serializing all concurrent handshakes on a single async mutex.
+        let mut kdf_fingerprint_guard = self.kdf_material_fingerprint.write().await;
+        kdf_fingerprint_guard.insert(peer_addr_nat, (kdf_fingerprint, client_port_for_kdf));
         drop(kdf_fingerprint_guard);
 
         let client_port_bytes = client_port_for_kdf.to_le_bytes();
@@ -624,6 +690,7 @@ impl MePool {
         Ok(HandshakeOutput {
             rd,
             wr,
+            source_ip: local_addr_nat.ip(),
             read_key: rk,
             read_iv,
             write_key: wk,
@@ -648,3 +715,66 @@ fn hex_dump(data: &[u8]) -> String {
     }
     out
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::ErrorKind;
+    use tokio::net::{TcpListener, TcpStream};
+
+    #[tokio::test]
+    async fn test_configure_keepalive_loopback() {
+        let listener = match TcpListener::bind("127.0.0.1:0").await {
+            Ok(listener) => listener,
+            Err(error) if error.kind() == ErrorKind::PermissionDenied => return,
+            Err(error) => panic!("bind failed: {error}"),
+        };
+
+        let addr = match listener.local_addr() {
+            Ok(addr) => addr,
+            Err(error) => panic!("local_addr failed: {error}"),
+        };
+
+        let stream = match TcpStream::connect(addr).await {
+            Ok(stream) => stream,
+            Err(error) if error.kind() == ErrorKind::PermissionDenied => return,
+            Err(error) => panic!("connect failed: {error}"),
+        };
+
+        if let Err(error) = MePool::configure_keepalive(&stream) {
+            if error.kind() == ErrorKind::PermissionDenied {
+                return;
+            }
+            panic!("configure_keepalive failed: {error}");
+        }
+    }
+
+    #[test]
+    #[cfg(target_os = "openbsd")]
+    fn test_openbsd_keepalive_cfg_path_compiles() {
+        let _ka = TcpKeepalive::new().with_time(Duration::from_secs(30));
+    }
+
+    #[test]
+    #[cfg(any(
+        target_os = "android",
+        target_os = "dragonfly",
+        target_os = "freebsd",
+        target_os = "fuchsia",
+        target_os = "illumos",
+        target_os = "ios",
+        target_os = "visionos",
+        target_os = "linux",
+        target_os = "macos",
+        target_os = "netbsd",
+        target_os = "tvos",
+        target_os = "watchos",
+        target_os = "cygwin",
+    ))]
+    fn test_retry_keepalive_cfg_path_compiles() {
+        let _ka = TcpKeepalive::new()
+            .with_time(Duration::from_secs(30))
+            .with_interval(Duration::from_secs(10))
+            .with_retries(3);
+    }
+}

src/transport/middle_proxy/mod.rs

@@ -10,6 +10,7 @@ mod pool_init;
 mod pool_nat;
 mod pool_refill;
 mod pool_reinit;
+mod pool_runtime_api;
 mod pool_writer;
 mod ping;
 mod reader;
@@ -17,7 +18,9 @@ mod registry;
 mod rotation;
 mod send;
 mod secret;
+mod selftest;
 mod wire;
+mod pool_status;
 
 use bytes::Bytes;
 
@@ -29,8 +32,15 @@ pub use pool::MePool;
 pub use pool_nat::{stun_probe, detect_public_ip};
 pub use registry::ConnRegistry;
 pub use secret::fetch_proxy_secret;
-pub use config_updater::{fetch_proxy_config, me_config_updater};
+#[allow(unused_imports)]
+pub use config_updater::{
+    ProxyConfigData, fetch_proxy_config, fetch_proxy_config_with_raw, load_proxy_config_cache,
+    me_config_updater, save_proxy_config_cache,
+};
 pub use rotation::{MeReinitTrigger, me_reinit_scheduler, me_rotation_task};
+pub(crate) use selftest::{
+    bnd_snapshot, timeskew_snapshot, upstream_bnd_snapshots,
+};
 pub use wire::proto_flags_for_tag;
 
 #[derive(Debug)]

src/transport/middle_proxy/ping.rs

@@ -331,7 +331,7 @@ pub async fn run_me_ping(pool: &Arc<MePool>, rng: &SecureRandom) -> Vec<MePingRe
             let mut error = None;
             let mut route = None;
 
-            match pool.connect_tcp(addr).await {
+            match pool.connect_tcp(addr, None).await {
                 Ok((stream, conn_rtt, upstream_egress)) => {
                     connect_ms = Some(conn_rtt);
                     route = route_from_egress(upstream_egress);

src/transport/middle_proxy/pool.rs

@@ -7,7 +7,9 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 use tokio::sync::{Mutex, Notify, RwLock, mpsc};
 use tokio_util::sync::CancellationToken;
 
-use crate::config::{MeBindStaleMode, MeSocksKdfPolicy};
+use crate::config::{
+    MeBindStaleMode, MeFloorMode, MeRouteNoWriterMode, MeSocksKdfPolicy, MeWriterPickMode,
+};
 use crate::crypto::SecureRandom;
 use crate::network::IpFamily;
 use crate::network::probe::NetworkDecision;
@@ -22,18 +24,28 @@ pub(super) struct RefillDcKey {
     pub family: IpFamily,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub(super) struct RefillEndpointKey {
+    pub dc: i32,
+    pub addr: SocketAddr,
+}
+
 #[derive(Clone)]
 pub struct MeWriter {
     pub id: u64,
     pub addr: SocketAddr,
+    pub source_ip: IpAddr,
+    pub writer_dc: i32,
     pub generation: u64,
     pub contour: Arc<AtomicU8>,
     pub created_at: Instant,
     pub tx: mpsc::Sender<WriterCommand>,
     pub cancel: CancellationToken,
     pub degraded: Arc<AtomicBool>,
+    pub rtt_ema_ms_x10: Arc<AtomicU32>,
     pub draining: Arc<AtomicBool>,
     pub draining_started_at_epoch_secs: Arc<AtomicU64>,
+    pub drain_deadline_epoch_secs: Arc<AtomicU64>,
     pub allow_drain_fallback: Arc<AtomicBool>,
 }
 
@@ -94,6 +106,8 @@ pub struct MePool {
     pub(super) me_keepalive_interval: Duration,
     pub(super) me_keepalive_jitter: Duration,
     pub(super) me_keepalive_payload_random: bool,
+    pub(super) rpc_proxy_req_every_secs: AtomicU64,
+    pub(super) writer_cmd_channel_capacity: usize,
     pub(super) me_warmup_stagger_enabled: bool,
     pub(super) me_warmup_step_delay: Duration,
     pub(super) me_warmup_step_jitter: Duration,
@@ -107,17 +121,46 @@ pub struct MePool {
     pub(super) me_single_endpoint_outage_backoff_min_ms: AtomicU64,
     pub(super) me_single_endpoint_outage_backoff_max_ms: AtomicU64,
     pub(super) me_single_endpoint_shadow_rotate_every_secs: AtomicU64,
+    pub(super) me_floor_mode: AtomicU8,
+    pub(super) me_adaptive_floor_idle_secs: AtomicU64,
+    pub(super) me_adaptive_floor_min_writers_single_endpoint: AtomicU8,
+    pub(super) me_adaptive_floor_min_writers_multi_endpoint: AtomicU8,
+    pub(super) me_adaptive_floor_recover_grace_secs: AtomicU64,
+    pub(super) me_adaptive_floor_writers_per_core_total: AtomicU32,
+    pub(super) me_adaptive_floor_cpu_cores_override: AtomicU32,
+    pub(super) me_adaptive_floor_max_extra_writers_single_per_core: AtomicU32,
+    pub(super) me_adaptive_floor_max_extra_writers_multi_per_core: AtomicU32,
+    pub(super) me_adaptive_floor_max_active_writers_per_core: AtomicU32,
+    pub(super) me_adaptive_floor_max_warm_writers_per_core: AtomicU32,
+    pub(super) me_adaptive_floor_max_active_writers_global: AtomicU32,
+    pub(super) me_adaptive_floor_max_warm_writers_global: AtomicU32,
+    pub(super) me_adaptive_floor_cpu_cores_detected: AtomicU32,
+    pub(super) me_adaptive_floor_cpu_cores_effective: AtomicU32,
+    pub(super) me_adaptive_floor_global_cap_raw: AtomicU64,
+    pub(super) me_adaptive_floor_global_cap_effective: AtomicU64,
+    pub(super) me_adaptive_floor_target_writers_total: AtomicU64,
+    pub(super) me_adaptive_floor_active_cap_configured: AtomicU64,
+    pub(super) me_adaptive_floor_active_cap_effective: AtomicU64,
+    pub(super) me_adaptive_floor_warm_cap_configured: AtomicU64,
+    pub(super) me_adaptive_floor_warm_cap_effective: AtomicU64,
+    pub(super) me_adaptive_floor_active_writers_current: AtomicU64,
+    pub(super) me_adaptive_floor_warm_writers_current: AtomicU64,
     pub(super) proxy_map_v4: Arc<RwLock<HashMap<i32, Vec<(IpAddr, u16)>>>>,
     pub(super) proxy_map_v6: Arc<RwLock<HashMap<i32, Vec<(IpAddr, u16)>>>>,
+    pub(super) endpoint_dc_map: Arc<RwLock<HashMap<SocketAddr, Option<i32>>>>,
     pub(super) default_dc: AtomicI32,
     pub(super) next_writer_id: AtomicU64,
     pub(super) ping_tracker: Arc<Mutex<HashMap<i64, (std::time::Instant, u64)>>>,
+    pub(super) ping_tracker_last_cleanup_epoch_ms: AtomicU64,
     pub(super) rtt_stats: Arc<Mutex<HashMap<u64, (f64, f64)>>>,
     pub(super) nat_reflection_cache: Arc<Mutex<NatReflectionCache>>,
+    pub(super) nat_reflection_singleflight_v4: Arc<Mutex<()>>,
+    pub(super) nat_reflection_singleflight_v6: Arc<Mutex<()>>,
     pub(super) writer_available: Arc<Notify>,
-    pub(super) refill_inflight: Arc<Mutex<HashSet<SocketAddr>>>,
+    pub(super) refill_inflight: Arc<Mutex<HashSet<RefillEndpointKey>>>,
     pub(super) refill_inflight_dc: Arc<Mutex<HashSet<RefillDcKey>>>,
     pub(super) conn_count: AtomicUsize,
+    pub(super) draining_active_runtime: AtomicU64,
     pub(super) stats: Arc<crate::stats::Stats>,
     pub(super) generation: AtomicU64,
     pub(super) active_generation: AtomicU64,
@@ -127,8 +170,9 @@ pub struct MePool {
     pub(super) pending_hardswap_map_hash: AtomicU64,
     pub(super) hardswap: AtomicBool,
     pub(super) endpoint_quarantine: Arc<Mutex<HashMap<SocketAddr, Instant>>>,
-    pub(super) kdf_material_fingerprint: Arc<Mutex<HashMap<SocketAddr, u64>>>,
+    pub(super) kdf_material_fingerprint: Arc<RwLock<HashMap<SocketAddr, (u64, u16)>>>,
     pub(super) me_pool_drain_ttl_secs: AtomicU64,
+    pub(super) me_pool_drain_threshold: AtomicU64,
     pub(super) me_pool_force_close_secs: AtomicU64,
     pub(super) me_pool_min_fresh_ratio_permille: AtomicU32,
     pub(super) me_hardswap_warmup_delay_min_ms: AtomicU64,
@@ -139,8 +183,20 @@ pub struct MePool {
     pub(super) me_bind_stale_ttl_secs: AtomicU64,
     pub(super) secret_atomic_snapshot: AtomicBool,
     pub(super) me_deterministic_writer_sort: AtomicBool,
+    pub(super) me_writer_pick_mode: AtomicU8,
+    pub(super) me_writer_pick_sample_size: AtomicU8,
     pub(super) me_socks_kdf_policy: AtomicU8,
+    pub(super) me_reader_route_data_wait_ms: Arc<AtomicU64>,
+    pub(super) me_route_no_writer_mode: AtomicU8,
+    pub(super) me_route_no_writer_wait: Duration,
+    pub(super) me_route_inline_recovery_attempts: u32,
+    pub(super) me_route_inline_recovery_wait: Duration,
+    pub(super) me_health_interval_ms_unhealthy: AtomicU64,
+    pub(super) me_health_interval_ms_healthy: AtomicU64,
+    pub(super) me_warn_rate_limit_ms: AtomicU64,
+    pub(super) runtime_ready: AtomicBool,
     pool_size: usize,
+    pub(super) preferred_endpoints_by_dc: Arc<RwLock<HashMap<i32, Vec<SocketAddr>>>>,
 }
 
 #[derive(Debug, Default)]
@@ -188,6 +244,7 @@ impl MePool {
         me_keepalive_interval_secs: u64,
         me_keepalive_jitter_secs: u64,
         me_keepalive_payload_random: bool,
+        rpc_proxy_req_every_secs: u64,
         me_warmup_stagger_enabled: bool,
         me_warmup_step_delay_ms: u64,
         me_warmup_step_jitter_ms: u64,
@@ -201,8 +258,22 @@ impl MePool {
         me_single_endpoint_outage_backoff_min_ms: u64,
         me_single_endpoint_outage_backoff_max_ms: u64,
         me_single_endpoint_shadow_rotate_every_secs: u64,
+        me_floor_mode: MeFloorMode,
+        me_adaptive_floor_idle_secs: u64,
+        me_adaptive_floor_min_writers_single_endpoint: u8,
+        me_adaptive_floor_min_writers_multi_endpoint: u8,
+        me_adaptive_floor_recover_grace_secs: u64,
+        me_adaptive_floor_writers_per_core_total: u16,
+        me_adaptive_floor_cpu_cores_override: u16,
+        me_adaptive_floor_max_extra_writers_single_per_core: u16,
+        me_adaptive_floor_max_extra_writers_multi_per_core: u16,
+        me_adaptive_floor_max_active_writers_per_core: u16,
+        me_adaptive_floor_max_warm_writers_per_core: u16,
+        me_adaptive_floor_max_active_writers_global: u32,
+        me_adaptive_floor_max_warm_writers_global: u32,
         hardswap: bool,
         me_pool_drain_ttl_secs: u64,
+        me_pool_drain_threshold: u64,
         me_pool_force_close_secs: u64,
         me_pool_min_fresh_ratio: f32,
         me_hardswap_warmup_delay_min_ms: u64,
@@ -213,12 +284,29 @@ impl MePool {
         me_bind_stale_ttl_secs: u64,
         me_secret_atomic_snapshot: bool,
         me_deterministic_writer_sort: bool,
+        me_writer_pick_mode: MeWriterPickMode,
+        me_writer_pick_sample_size: u8,
         me_socks_kdf_policy: MeSocksKdfPolicy,
+        me_writer_cmd_channel_capacity: usize,
+        me_route_channel_capacity: usize,
         me_route_backpressure_base_timeout_ms: u64,
         me_route_backpressure_high_timeout_ms: u64,
         me_route_backpressure_high_watermark_pct: u8,
+        me_reader_route_data_wait_ms: u64,
+        me_health_interval_ms_unhealthy: u64,
+        me_health_interval_ms_healthy: u64,
+        me_warn_rate_limit_ms: u64,
+        me_route_no_writer_mode: MeRouteNoWriterMode,
+        me_route_no_writer_wait_ms: u64,
+        me_route_inline_recovery_attempts: u32,
+        me_route_inline_recovery_wait_ms: u64,
     ) -> Arc<Self> {
-        let registry = Arc::new(ConnRegistry::new());
+        let endpoint_dc_map = Self::build_endpoint_dc_map_from_maps(&proxy_map_v4, &proxy_map_v6);
+        let preferred_endpoints_by_dc =
+            Self::build_preferred_endpoints_by_dc(&decision, &proxy_map_v4, &proxy_map_v6);
+        let registry = Arc::new(ConnRegistry::with_route_channel_capacity(
+            me_route_channel_capacity,
+        ));
         registry.update_route_backpressure_policy(
             me_route_backpressure_base_timeout_ms,
             me_route_backpressure_high_timeout_ms,
@@ -264,6 +352,8 @@ impl MePool {
             me_keepalive_interval: Duration::from_secs(me_keepalive_interval_secs),
             me_keepalive_jitter: Duration::from_secs(me_keepalive_jitter_secs),
             me_keepalive_payload_random,
+            rpc_proxy_req_every_secs: AtomicU64::new(rpc_proxy_req_every_secs),
+            writer_cmd_channel_capacity: me_writer_cmd_channel_capacity.max(1),
             me_warmup_stagger_enabled,
             me_warmup_step_delay: Duration::from_millis(me_warmup_step_delay_ms),
             me_warmup_step_jitter: Duration::from_millis(me_warmup_step_jitter_ms),
@@ -287,18 +377,69 @@ impl MePool {
             me_single_endpoint_shadow_rotate_every_secs: AtomicU64::new(
                 me_single_endpoint_shadow_rotate_every_secs,
             ),
+            me_floor_mode: AtomicU8::new(me_floor_mode.as_u8()),
+            me_adaptive_floor_idle_secs: AtomicU64::new(me_adaptive_floor_idle_secs),
+            me_adaptive_floor_min_writers_single_endpoint: AtomicU8::new(
+                me_adaptive_floor_min_writers_single_endpoint,
+            ),
+            me_adaptive_floor_min_writers_multi_endpoint: AtomicU8::new(
+                me_adaptive_floor_min_writers_multi_endpoint,
+            ),
+            me_adaptive_floor_recover_grace_secs: AtomicU64::new(
+                me_adaptive_floor_recover_grace_secs,
+            ),
+            me_adaptive_floor_writers_per_core_total: AtomicU32::new(
+                me_adaptive_floor_writers_per_core_total as u32,
+            ),
+            me_adaptive_floor_cpu_cores_override: AtomicU32::new(
+                me_adaptive_floor_cpu_cores_override as u32,
+            ),
+            me_adaptive_floor_max_extra_writers_single_per_core: AtomicU32::new(
+                me_adaptive_floor_max_extra_writers_single_per_core as u32,
+            ),
+            me_adaptive_floor_max_extra_writers_multi_per_core: AtomicU32::new(
+                me_adaptive_floor_max_extra_writers_multi_per_core as u32,
+            ),
+            me_adaptive_floor_max_active_writers_per_core: AtomicU32::new(
+                me_adaptive_floor_max_active_writers_per_core as u32,
+            ),
+            me_adaptive_floor_max_warm_writers_per_core: AtomicU32::new(
+                me_adaptive_floor_max_warm_writers_per_core as u32,
+            ),
+            me_adaptive_floor_max_active_writers_global: AtomicU32::new(
+                me_adaptive_floor_max_active_writers_global,
+            ),
+            me_adaptive_floor_max_warm_writers_global: AtomicU32::new(
+                me_adaptive_floor_max_warm_writers_global,
+            ),
+            me_adaptive_floor_cpu_cores_detected: AtomicU32::new(1),
+            me_adaptive_floor_cpu_cores_effective: AtomicU32::new(1),
+            me_adaptive_floor_global_cap_raw: AtomicU64::new(0),
+            me_adaptive_floor_global_cap_effective: AtomicU64::new(0),
+            me_adaptive_floor_target_writers_total: AtomicU64::new(0),
+            me_adaptive_floor_active_cap_configured: AtomicU64::new(0),
+            me_adaptive_floor_active_cap_effective: AtomicU64::new(0),
+            me_adaptive_floor_warm_cap_configured: AtomicU64::new(0),
+            me_adaptive_floor_warm_cap_effective: AtomicU64::new(0),
+            me_adaptive_floor_active_writers_current: AtomicU64::new(0),
+            me_adaptive_floor_warm_writers_current: AtomicU64::new(0),
             pool_size: 2,
             proxy_map_v4: Arc::new(RwLock::new(proxy_map_v4)),
             proxy_map_v6: Arc::new(RwLock::new(proxy_map_v6)),
-            default_dc: AtomicI32::new(default_dc.unwrap_or(0)),
+            endpoint_dc_map: Arc::new(RwLock::new(endpoint_dc_map)),
+            default_dc: AtomicI32::new(default_dc.unwrap_or(2)),
             next_writer_id: AtomicU64::new(1),
             ping_tracker: Arc::new(Mutex::new(HashMap::new())),
+            ping_tracker_last_cleanup_epoch_ms: AtomicU64::new(0),
             rtt_stats: Arc::new(Mutex::new(HashMap::new())),
             nat_reflection_cache: Arc::new(Mutex::new(NatReflectionCache::default())),
+            nat_reflection_singleflight_v4: Arc::new(Mutex::new(())),
+            nat_reflection_singleflight_v6: Arc::new(Mutex::new(())),
             writer_available: Arc::new(Notify::new()),
             refill_inflight: Arc::new(Mutex::new(HashSet::new())),
             refill_inflight_dc: Arc::new(Mutex::new(HashSet::new())),
             conn_count: AtomicUsize::new(0),
+            draining_active_runtime: AtomicU64::new(0),
             generation: AtomicU64::new(1),
             active_generation: AtomicU64::new(1),
             warm_generation: AtomicU64::new(0),
@@ -307,8 +448,9 @@ impl MePool {
             pending_hardswap_map_hash: AtomicU64::new(0),
             hardswap: AtomicBool::new(hardswap),
             endpoint_quarantine: Arc::new(Mutex::new(HashMap::new())),
-            kdf_material_fingerprint: Arc::new(Mutex::new(HashMap::new())),
+            kdf_material_fingerprint: Arc::new(RwLock::new(HashMap::new())),
             me_pool_drain_ttl_secs: AtomicU64::new(me_pool_drain_ttl_secs),
+            me_pool_drain_threshold: AtomicU64::new(me_pool_drain_threshold),
             me_pool_force_close_secs: AtomicU64::new(me_pool_force_close_secs),
             me_pool_min_fresh_ratio_permille: AtomicU32::new(Self::ratio_to_permille(
                 me_pool_min_fresh_ratio,
@@ -323,7 +465,19 @@ impl MePool {
             me_bind_stale_ttl_secs: AtomicU64::new(me_bind_stale_ttl_secs),
             secret_atomic_snapshot: AtomicBool::new(me_secret_atomic_snapshot),
             me_deterministic_writer_sort: AtomicBool::new(me_deterministic_writer_sort),
+            me_writer_pick_mode: AtomicU8::new(me_writer_pick_mode.as_u8()),
+            me_writer_pick_sample_size: AtomicU8::new(me_writer_pick_sample_size.clamp(2, 4)),
             me_socks_kdf_policy: AtomicU8::new(me_socks_kdf_policy.as_u8()),
+            me_reader_route_data_wait_ms: Arc::new(AtomicU64::new(me_reader_route_data_wait_ms)),
+            me_route_no_writer_mode: AtomicU8::new(me_route_no_writer_mode.as_u8()),
+            me_route_no_writer_wait: Duration::from_millis(me_route_no_writer_wait_ms),
+            me_route_inline_recovery_attempts,
+            me_route_inline_recovery_wait: Duration::from_millis(me_route_inline_recovery_wait_ms),
+            me_health_interval_ms_unhealthy: AtomicU64::new(me_health_interval_ms_unhealthy.max(1)),
+            me_health_interval_ms_healthy: AtomicU64::new(me_health_interval_ms_healthy.max(1)),
+            me_warn_rate_limit_ms: AtomicU64::new(me_warn_rate_limit_ms.max(1)),
+            runtime_ready: AtomicBool::new(false),
+            preferred_endpoints_by_dc: Arc::new(RwLock::new(preferred_endpoints_by_dc)),
         })
     }
 
@@ -331,10 +485,19 @@ impl MePool {
         self.active_generation.load(Ordering::Relaxed)
     }
 
+    pub fn set_runtime_ready(&self, ready: bool) {
+        self.runtime_ready.store(ready, Ordering::Relaxed);
+    }
+
+    pub fn is_runtime_ready(&self) -> bool {
+        self.runtime_ready.load(Ordering::Relaxed)
+    }
+
     pub fn update_runtime_reinit_policy(
         &self,
         hardswap: bool,
         drain_ttl_secs: u64,
+        pool_drain_threshold: u64,
         force_close_secs: u64,
         min_fresh_ratio: f32,
         hardswap_warmup_delay_min_ms: u64,
@@ -345,16 +508,36 @@ impl MePool {
         bind_stale_ttl_secs: u64,
         secret_atomic_snapshot: bool,
         deterministic_writer_sort: bool,
+        writer_pick_mode: MeWriterPickMode,
+        writer_pick_sample_size: u8,
         single_endpoint_shadow_writers: u8,
         single_endpoint_outage_mode_enabled: bool,
         single_endpoint_outage_disable_quarantine: bool,
         single_endpoint_outage_backoff_min_ms: u64,
         single_endpoint_outage_backoff_max_ms: u64,
         single_endpoint_shadow_rotate_every_secs: u64,
+        floor_mode: MeFloorMode,
+        adaptive_floor_idle_secs: u64,
+        adaptive_floor_min_writers_single_endpoint: u8,
+        adaptive_floor_min_writers_multi_endpoint: u8,
+        adaptive_floor_recover_grace_secs: u64,
+        adaptive_floor_writers_per_core_total: u16,
+        adaptive_floor_cpu_cores_override: u16,
+        adaptive_floor_max_extra_writers_single_per_core: u16,
+        adaptive_floor_max_extra_writers_multi_per_core: u16,
+        adaptive_floor_max_active_writers_per_core: u16,
+        adaptive_floor_max_warm_writers_per_core: u16,
+        adaptive_floor_max_active_writers_global: u32,
+        adaptive_floor_max_warm_writers_global: u32,
+        me_health_interval_ms_unhealthy: u64,
+        me_health_interval_ms_healthy: u64,
+        me_warn_rate_limit_ms: u64,
     ) {
         self.hardswap.store(hardswap, Ordering::Relaxed);
         self.me_pool_drain_ttl_secs
             .store(drain_ttl_secs, Ordering::Relaxed);
+        self.me_pool_drain_threshold
+            .store(pool_drain_threshold, Ordering::Relaxed);
         self.me_pool_force_close_secs
             .store(force_close_secs, Ordering::Relaxed);
         self.me_pool_min_fresh_ratio_permille
@@ -375,6 +558,14 @@ impl MePool {
             .store(secret_atomic_snapshot, Ordering::Relaxed);
         self.me_deterministic_writer_sort
             .store(deterministic_writer_sort, Ordering::Relaxed);
+        let previous_writer_pick_mode = self.writer_pick_mode();
+        self.me_writer_pick_mode
+            .store(writer_pick_mode.as_u8(), Ordering::Relaxed);
+        self.me_writer_pick_sample_size
+            .store(writer_pick_sample_size.clamp(2, 4), Ordering::Relaxed);
+        if previous_writer_pick_mode != writer_pick_mode {
+            self.stats.increment_me_writer_pick_mode_switch_total();
+        }
         self.me_single_endpoint_shadow_writers
             .store(single_endpoint_shadow_writers, Ordering::Relaxed);
         self.me_single_endpoint_outage_mode_enabled
@@ -387,6 +578,65 @@ impl MePool {
             .store(single_endpoint_outage_backoff_max_ms, Ordering::Relaxed);
         self.me_single_endpoint_shadow_rotate_every_secs
             .store(single_endpoint_shadow_rotate_every_secs, Ordering::Relaxed);
+        let previous_floor_mode = self.floor_mode();
+        self.me_floor_mode
+            .store(floor_mode.as_u8(), Ordering::Relaxed);
+        self.me_adaptive_floor_idle_secs
+            .store(adaptive_floor_idle_secs, Ordering::Relaxed);
+        self.me_adaptive_floor_min_writers_single_endpoint
+            .store(adaptive_floor_min_writers_single_endpoint, Ordering::Relaxed);
+        self.me_adaptive_floor_min_writers_multi_endpoint
+            .store(adaptive_floor_min_writers_multi_endpoint, Ordering::Relaxed);
+        self.me_adaptive_floor_recover_grace_secs
+            .store(adaptive_floor_recover_grace_secs, Ordering::Relaxed);
+        self.me_adaptive_floor_writers_per_core_total
+            .store(adaptive_floor_writers_per_core_total as u32, Ordering::Relaxed);
+        self.me_adaptive_floor_cpu_cores_override
+            .store(adaptive_floor_cpu_cores_override as u32, Ordering::Relaxed);
+        self.me_adaptive_floor_max_extra_writers_single_per_core
+            .store(
+                adaptive_floor_max_extra_writers_single_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.me_adaptive_floor_max_extra_writers_multi_per_core
+            .store(
+                adaptive_floor_max_extra_writers_multi_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.me_adaptive_floor_max_active_writers_per_core
+            .store(
+                adaptive_floor_max_active_writers_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.me_adaptive_floor_max_warm_writers_per_core
+            .store(
+                adaptive_floor_max_warm_writers_per_core as u32,
+                Ordering::Relaxed,
+            );
+        self.me_adaptive_floor_max_active_writers_global
+            .store(adaptive_floor_max_active_writers_global, Ordering::Relaxed);
+        self.me_adaptive_floor_max_warm_writers_global
+            .store(adaptive_floor_max_warm_writers_global, Ordering::Relaxed);
+        self.me_health_interval_ms_unhealthy
+            .store(me_health_interval_ms_unhealthy.max(1), Ordering::Relaxed);
+        self.me_health_interval_ms_healthy
+            .store(me_health_interval_ms_healthy.max(1), Ordering::Relaxed);
+        self.me_warn_rate_limit_ms
+            .store(me_warn_rate_limit_ms.max(1), Ordering::Relaxed);
+        if previous_floor_mode != floor_mode {
+            self.stats.increment_me_floor_mode_switch_total();
+            match (previous_floor_mode, floor_mode) {
+                (MeFloorMode::Static, MeFloorMode::Adaptive) => {
+                    self.stats
+                        .increment_me_floor_mode_switch_static_to_adaptive_total();
+                }
+                (MeFloorMode::Adaptive, MeFloorMode::Static) => {
+                    self.stats
+                        .increment_me_floor_mode_switch_adaptive_to_static_total();
+                }
+                _ => {}
+            }
+        }
     }
 
     pub fn reset_stun_state(&self) {
@@ -397,9 +647,9 @@ impl MePool {
         }
     }
 
+    /// Translate the local ME address into the address material sent to the proxy.
     pub fn translate_our_addr(&self, addr: SocketAddr) -> SocketAddr {
-        let ip = self.translate_ip_for_nat(addr.ip());
-        SocketAddr::new(ip, addr.port())
+        self.translate_our_addr_with_reflection(addr, None)
     }
 
     pub fn registry(&self) -> &Arc<ConnRegistry> {
@@ -412,9 +662,12 @@ impl MePool {
         route_backpressure_base_timeout_ms: u64,
         route_backpressure_high_timeout_ms: u64,
         route_backpressure_high_watermark_pct: u8,
+        reader_route_data_wait_ms: u64,
     ) {
         self.me_socks_kdf_policy
             .store(socks_kdf_policy.as_u8(), Ordering::Relaxed);
+        self.me_reader_route_data_wait_ms
+            .store(reader_route_data_wait_ms, Ordering::Relaxed);
         self.registry.update_route_backpressure_policy(
             route_backpressure_base_timeout_ms,
             route_backpressure_high_timeout_ms,
@@ -439,10 +692,58 @@ impl MePool {
         }
     }
 
+    pub(super) fn draining_active_runtime(&self) -> u64 {
+        self.draining_active_runtime.load(Ordering::Relaxed)
+    }
+
+    pub(super) fn increment_draining_active_runtime(&self) {
+        self.draining_active_runtime.fetch_add(1, Ordering::Relaxed);
+    }
+
+    pub(super) fn decrement_draining_active_runtime(&self) {
+        let mut current = self.draining_active_runtime.load(Ordering::Relaxed);
+        loop {
+            if current == 0 {
+                break;
+            }
+            match self.draining_active_runtime.compare_exchange_weak(
+                current,
+                current - 1,
+                Ordering::Relaxed,
+                Ordering::Relaxed,
+            ) {
+                Ok(_) => break,
+                Err(actual) => current = actual,
+            }
+        }
+    }
+
     pub(super) async fn key_selector(&self) -> u32 {
         self.proxy_secret.read().await.key_selector
     }
 
+    pub(super) async fn non_draining_writer_counts_by_contour(&self) -> (usize, usize, usize) {
+        let ws = self.writers.read().await;
+        let mut active = 0usize;
+        let mut warm = 0usize;
+        for writer in ws.iter() {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            match WriterContour::from_u8(writer.contour.load(Ordering::Relaxed)) {
+                WriterContour::Active => active = active.saturating_add(1),
+                WriterContour::Warm => warm = warm.saturating_add(1),
+                WriterContour::Draining => {}
+            }
+        }
+        (active, warm, active.saturating_add(warm))
+    }
+
+    pub(super) async fn active_contour_writer_count_total(&self) -> usize {
+        let (active, _, _) = self.non_draining_writer_counts_by_contour().await;
+        active
+    }
+
     pub(super) async fn secret_snapshot(&self) -> SecretSnapshot {
         self.proxy_secret.read().await.clone()
     }
@@ -451,6 +752,16 @@ impl MePool {
         MeBindStaleMode::from_u8(self.me_bind_stale_mode.load(Ordering::Relaxed))
     }
 
+    pub(super) fn writer_pick_mode(&self) -> MeWriterPickMode {
+        MeWriterPickMode::from_u8(self.me_writer_pick_mode.load(Ordering::Relaxed))
+    }
+
+    pub(super) fn writer_pick_sample_size(&self) -> usize {
+        self.me_writer_pick_sample_size
+            .load(Ordering::Relaxed)
+            .clamp(2, 4) as usize
+    }
+
     pub(super) fn required_writers_for_dc(&self, endpoint_count: usize) -> usize {
         if endpoint_count == 0 {
             return 0;
@@ -464,6 +775,265 @@ impl MePool {
         endpoint_count.max(3)
     }
 
+    pub(super) fn floor_mode(&self) -> MeFloorMode {
+        MeFloorMode::from_u8(self.me_floor_mode.load(Ordering::Relaxed))
+    }
+
+    pub(super) fn adaptive_floor_idle_duration(&self) -> Duration {
+        Duration::from_secs(self.me_adaptive_floor_idle_secs.load(Ordering::Relaxed))
+    }
+
+    pub(super) fn adaptive_floor_recover_grace_duration(&self) -> Duration {
+        Duration::from_secs(
+            self.me_adaptive_floor_recover_grace_secs
+                .load(Ordering::Relaxed),
+        )
+    }
+
+    pub(super) fn adaptive_floor_min_writers_multi_endpoint(&self) -> usize {
+        (self
+            .me_adaptive_floor_min_writers_multi_endpoint
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(super) fn adaptive_floor_max_extra_single_per_core(&self) -> usize {
+        self.me_adaptive_floor_max_extra_writers_single_per_core
+            .load(Ordering::Relaxed) as usize
+    }
+
+    pub(super) fn adaptive_floor_max_extra_multi_per_core(&self) -> usize {
+        self.me_adaptive_floor_max_extra_writers_multi_per_core
+            .load(Ordering::Relaxed) as usize
+    }
+
+    pub(super) fn adaptive_floor_max_active_writers_per_core(&self) -> usize {
+        (self
+            .me_adaptive_floor_max_active_writers_per_core
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(super) fn adaptive_floor_max_warm_writers_per_core(&self) -> usize {
+        (self
+            .me_adaptive_floor_max_warm_writers_per_core
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(super) fn adaptive_floor_max_active_writers_global(&self) -> usize {
+        (self
+            .me_adaptive_floor_max_active_writers_global
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(super) fn adaptive_floor_max_warm_writers_global(&self) -> usize {
+        (self
+            .me_adaptive_floor_max_warm_writers_global
+            .load(Ordering::Relaxed) as usize)
+            .max(1)
+    }
+
+    pub(super) fn adaptive_floor_detected_cpu_cores(&self) -> usize {
+        std::thread::available_parallelism()
+            .map(|value| value.get())
+            .unwrap_or(1)
+            .max(1)
+    }
+
+    pub(super) fn adaptive_floor_effective_cpu_cores(&self) -> usize {
+        let detected = self.adaptive_floor_detected_cpu_cores();
+        let override_cores = self
+            .me_adaptive_floor_cpu_cores_override
+            .load(Ordering::Relaxed) as usize;
+        let effective = if override_cores == 0 {
+            detected
+        } else {
+            override_cores.max(1)
+        };
+        self.me_adaptive_floor_cpu_cores_detected
+            .store(detected as u32, Ordering::Relaxed);
+        self.me_adaptive_floor_cpu_cores_effective
+            .store(effective as u32, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_cpu_cores_detected_gauge(detected as u64);
+        self.stats
+            .set_me_floor_cpu_cores_effective_gauge(effective as u64);
+        effective
+    }
+
+    // Keeps per-contour (active/warm) writer budget bounded by CPU count.
+    // Baseline is 86 writers on the first core and +48 for each extra core.
+    fn adaptive_floor_cpu_budget_per_contour_cap(&self, cores: usize) -> usize {
+        const FIRST_CORE_WRITER_BUDGET: usize = 86;
+        const EXTRA_CORE_WRITER_BUDGET: usize = 48;
+        if cores == 0 {
+            return FIRST_CORE_WRITER_BUDGET;
+        }
+        FIRST_CORE_WRITER_BUDGET.saturating_add(
+            cores
+                .saturating_sub(1)
+                .saturating_mul(EXTRA_CORE_WRITER_BUDGET),
+        )
+    }
+
+    pub(super) fn adaptive_floor_active_cap_configured_total(&self) -> usize {
+        let cores = self.adaptive_floor_effective_cpu_cores();
+        let per_contour_budget = self.adaptive_floor_cpu_budget_per_contour_cap(cores);
+        let configured = cores
+            .saturating_mul(self.adaptive_floor_max_active_writers_per_core())
+            .min(self.adaptive_floor_max_active_writers_global())
+            .min(per_contour_budget)
+            .max(1);
+        self.me_adaptive_floor_active_cap_configured
+            .store(configured as u64, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_active_cap_configured_gauge(configured as u64);
+        configured
+    }
+
+    pub(super) fn adaptive_floor_warm_cap_configured_total(&self) -> usize {
+        let cores = self.adaptive_floor_effective_cpu_cores();
+        let per_contour_budget = self.adaptive_floor_cpu_budget_per_contour_cap(cores);
+        let configured = cores
+            .saturating_mul(self.adaptive_floor_max_warm_writers_per_core())
+            .min(self.adaptive_floor_max_warm_writers_global())
+            .min(per_contour_budget)
+            .max(1);
+        self.me_adaptive_floor_warm_cap_configured
+            .store(configured as u64, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_warm_cap_configured_gauge(configured as u64);
+        configured
+    }
+
+    pub(super) fn set_adaptive_floor_runtime_caps(
+        &self,
+        active_cap_configured: usize,
+        active_cap_effective: usize,
+        warm_cap_configured: usize,
+        warm_cap_effective: usize,
+        target_writers_total: usize,
+        active_writers_current: usize,
+        warm_writers_current: usize,
+    ) {
+        self.me_adaptive_floor_global_cap_raw
+            .store(active_cap_configured as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_global_cap_effective
+            .store(active_cap_effective as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_target_writers_total
+            .store(target_writers_total as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_active_cap_configured
+            .store(active_cap_configured as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_active_cap_effective
+            .store(active_cap_effective as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_warm_cap_configured
+            .store(warm_cap_configured as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_warm_cap_effective
+            .store(warm_cap_effective as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_active_writers_current
+            .store(active_writers_current as u64, Ordering::Relaxed);
+        self.me_adaptive_floor_warm_writers_current
+            .store(warm_writers_current as u64, Ordering::Relaxed);
+        self.stats
+            .set_me_floor_global_cap_raw_gauge(active_cap_configured as u64);
+        self.stats
+            .set_me_floor_global_cap_effective_gauge(active_cap_effective as u64);
+        self.stats
+            .set_me_floor_target_writers_total_gauge(target_writers_total as u64);
+        self.stats
+            .set_me_floor_active_cap_configured_gauge(active_cap_configured as u64);
+        self.stats
+            .set_me_floor_active_cap_effective_gauge(active_cap_effective as u64);
+        self.stats
+            .set_me_floor_warm_cap_configured_gauge(warm_cap_configured as u64);
+        self.stats
+            .set_me_floor_warm_cap_effective_gauge(warm_cap_effective as u64);
+        self.stats
+            .set_me_writers_active_current_gauge(active_writers_current as u64);
+        self.stats
+            .set_me_writers_warm_current_gauge(warm_writers_current as u64);
+    }
+
+    pub(super) async fn active_coverage_required_total(&self) -> usize {
+        let mut endpoints_by_dc = HashMap::<i32, HashSet<SocketAddr>>::new();
+
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await;
+            for (dc, addrs) in map.iter() {
+                let entry = endpoints_by_dc.entry(*dc).or_default();
+                for (ip, port) in addrs.iter().copied() {
+                    entry.insert(SocketAddr::new(ip, port));
+                }
+            }
+        }
+
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await;
+            for (dc, addrs) in map.iter() {
+                let entry = endpoints_by_dc.entry(*dc).or_default();
+                for (ip, port) in addrs.iter().copied() {
+                    entry.insert(SocketAddr::new(ip, port));
+                }
+            }
+        }
+
+        endpoints_by_dc
+            .values()
+            .map(|endpoints| self.required_writers_for_dc_with_floor_mode(endpoints.len(), false))
+            .sum()
+    }
+
+    pub(super) async fn can_open_writer_for_contour(
+        &self,
+        contour: WriterContour,
+        allow_coverage_override: bool,
+    ) -> bool {
+        let (active_writers, warm_writers, _) = self.non_draining_writer_counts_by_contour().await;
+        match contour {
+            WriterContour::Active => {
+                let active_cap = self.adaptive_floor_active_cap_configured_total();
+                if active_writers < active_cap {
+                    return true;
+                }
+                if !allow_coverage_override {
+                    return false;
+                }
+                let coverage_required = self.active_coverage_required_total().await;
+                active_writers < coverage_required
+            }
+            WriterContour::Warm => warm_writers < self.adaptive_floor_warm_cap_configured_total(),
+            WriterContour::Draining => true,
+        }
+    }
+
+    pub(super) fn required_writers_for_dc_with_floor_mode(
+        &self,
+        endpoint_count: usize,
+        reduce_for_idle: bool,
+    ) -> usize {
+        let base_required = self.required_writers_for_dc(endpoint_count);
+        if !reduce_for_idle {
+            return base_required;
+        }
+        if self.floor_mode() != MeFloorMode::Adaptive {
+            return base_required;
+        }
+        let min_writers = if endpoint_count == 1 {
+            (self
+                .me_adaptive_floor_min_writers_single_endpoint
+                .load(Ordering::Relaxed) as usize)
+                .max(1)
+        } else {
+            (self
+                .me_adaptive_floor_min_writers_multi_endpoint
+                .load(Ordering::Relaxed) as usize)
+                .max(1)
+        };
+        base_required.min(min_writers)
+    }
+
     pub(super) fn single_endpoint_outage_mode_enabled(&self) -> bool {
         self.me_single_endpoint_outage_mode_enabled
             .load(Ordering::Relaxed)
@@ -519,6 +1089,51 @@ impl MePool {
         order
     }
 
+    pub(super) fn default_dc_for_routing(&self) -> i32 {
+        let dc = self.default_dc.load(Ordering::Relaxed);
+        if dc == 0 { 2 } else { dc }
+    }
+
+    pub(super) async fn has_configured_endpoints_for_dc(&self, dc: i32) -> bool {
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await;
+            if map.get(&dc).is_some_and(|endpoints| !endpoints.is_empty()) {
+                return true;
+            }
+        }
+
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await;
+            if map.get(&dc).is_some_and(|endpoints| !endpoints.is_empty()) {
+                return true;
+            }
+        }
+
+        false
+    }
+
+    pub(super) async fn resolve_target_dc_for_routing(&self, target_dc: i32) -> (i32, bool) {
+        if target_dc == 0 {
+            return (self.default_dc_for_routing(), true);
+        }
+
+        if self.has_configured_endpoints_for_dc(target_dc).await {
+            return (target_dc, false);
+        }
+
+        (self.default_dc_for_routing(), true)
+    }
+
+    pub(super) async fn resolve_dc_for_endpoint(&self, addr: SocketAddr) -> i32 {
+        if let Some(cached) = self.endpoint_dc_map.read().await.get(&addr).copied()
+            && let Some(dc) = cached
+        {
+            return dc;
+        }
+
+        self.default_dc_for_routing()
+    }
+
     pub(super) async fn proxy_map_for_family(
         &self,
         family: IpFamily,
@@ -528,4 +1143,123 @@ impl MePool {
             IpFamily::V6 => self.proxy_map_v6.read().await.clone(),
         }
     }
+
+    fn merge_endpoint_dc(
+        endpoint_dc_map: &mut HashMap<SocketAddr, Option<i32>>,
+        dc: i32,
+        ip: IpAddr,
+        port: u16,
+    ) {
+        let endpoint = SocketAddr::new(ip, port);
+        match endpoint_dc_map.get_mut(&endpoint) {
+            None => {
+                endpoint_dc_map.insert(endpoint, Some(dc));
+            }
+            Some(existing) => {
+                if existing.is_some_and(|existing_dc| existing_dc != dc) {
+                    *existing = None;
+                }
+            }
+        }
+    }
+
+    fn build_preferred_endpoints_by_dc(
+        decision: &NetworkDecision,
+        map_v4: &HashMap<i32, Vec<(IpAddr, u16)>>,
+        map_v6: &HashMap<i32, Vec<(IpAddr, u16)>>,
+    ) -> HashMap<i32, Vec<SocketAddr>> {
+        let mut out = HashMap::<i32, Vec<SocketAddr>>::new();
+        let mut dcs = HashSet::<i32>::new();
+        dcs.extend(map_v4.keys().copied());
+        dcs.extend(map_v6.keys().copied());
+
+        for dc in dcs {
+            let v4 = map_v4
+                .get(&dc)
+                .map(|items| {
+                    items
+                        .iter()
+                        .map(|(ip, port)| SocketAddr::new(*ip, *port))
+                        .collect::<Vec<_>>()
+                })
+                .unwrap_or_default();
+            let v6 = map_v6
+                .get(&dc)
+                .map(|items| {
+                    items
+                        .iter()
+                        .map(|(ip, port)| SocketAddr::new(*ip, *port))
+                        .collect::<Vec<_>>()
+                })
+                .unwrap_or_default();
+
+            let mut selected = if decision.effective_multipath {
+                let mut both = Vec::<SocketAddr>::with_capacity(v4.len().saturating_add(v6.len()));
+                if decision.prefer_ipv6() {
+                    both.extend(v6.iter().copied());
+                    both.extend(v4.iter().copied());
+                } else {
+                    both.extend(v4.iter().copied());
+                    both.extend(v6.iter().copied());
+                }
+                both
+            } else if decision.prefer_ipv6() {
+                if !v6.is_empty() { v6 } else { v4 }
+            } else if !v4.is_empty() {
+                v4
+            } else {
+                v6
+            };
+
+            selected.sort_unstable();
+            selected.dedup();
+            out.insert(dc, selected);
+        }
+
+        out
+    }
+
+    fn build_endpoint_dc_map_from_maps(
+        map_v4: &HashMap<i32, Vec<(IpAddr, u16)>>,
+        map_v6: &HashMap<i32, Vec<(IpAddr, u16)>>,
+    ) -> HashMap<SocketAddr, Option<i32>> {
+        let mut endpoint_dc_map = HashMap::<SocketAddr, Option<i32>>::new();
+        for (dc, endpoints) in map_v4 {
+            for (ip, port) in endpoints {
+                Self::merge_endpoint_dc(&mut endpoint_dc_map, *dc, *ip, *port);
+            }
+        }
+        for (dc, endpoints) in map_v6 {
+            for (ip, port) in endpoints {
+                Self::merge_endpoint_dc(&mut endpoint_dc_map, *dc, *ip, *port);
+            }
+        }
+        endpoint_dc_map
+    }
+
+    pub(super) async fn rebuild_endpoint_dc_map(&self) {
+        let map_v4 = self.proxy_map_v4.read().await.clone();
+        let map_v6 = self.proxy_map_v6.read().await.clone();
+        let rebuilt = Self::build_endpoint_dc_map_from_maps(&map_v4, &map_v6);
+        let preferred = Self::build_preferred_endpoints_by_dc(&self.decision, &map_v4, &map_v6);
+        *self.endpoint_dc_map.write().await = rebuilt;
+        *self.preferred_endpoints_by_dc.write().await = preferred;
+    }
+
+    pub(super) async fn preferred_endpoints_for_dc(&self, dc: i32) -> Vec<SocketAddr> {
+        let guard = self.preferred_endpoints_by_dc.read().await;
+        guard.get(&dc).cloned().unwrap_or_default()
+    }
+
+    pub(super) fn health_interval_unhealthy(&self) -> Duration {
+        Duration::from_millis(self.me_health_interval_ms_unhealthy.load(Ordering::Relaxed).max(1))
+    }
+
+    pub(super) fn health_interval_healthy(&self) -> Duration {
+        Duration::from_millis(self.me_health_interval_ms_healthy.load(Ordering::Relaxed).max(1))
+    }
+
+    pub(super) fn warn_rate_limit_duration(&self) -> Duration {
+        Duration::from_millis(self.me_warn_rate_limit_ms.load(Ordering::Relaxed).max(1))
+    }
 }

src/transport/middle_proxy/pool_config.rs

@@ -54,6 +54,7 @@ impl MePool {
                     && let Some(addrs) = guard.get(&k).cloned()
                 {
                     guard.insert(-k, addrs);
+                    changed = true;
                 }
             }
         }
@@ -65,9 +66,14 @@ impl MePool {
                     && let Some(addrs) = guard.get(&k).cloned()
                 {
                     guard.insert(-k, addrs);
+                    changed = true;
                 }
             }
         }
+        if changed {
+            self.rebuild_endpoint_dc_map().await;
+            self.writer_available.notify_waiters();
+        }
         if changed {
             SnapshotApplyOutcome::AppliedChanged
         } else {
@@ -104,7 +110,10 @@ impl MePool {
     pub async fn reconnect_all(self: &Arc<Self>) {
         let ws = self.writers.read().await.clone();
         for w in ws {
-            if let Ok(()) = self.connect_one(w.addr, self.rng.as_ref()).await {
+            if let Ok(()) = self
+                .connect_one_for_dc(w.addr, w.writer_dc, self.rng.as_ref())
+                .await
+            {
                 self.mark_writer_draining(w.id).await;
                 tokio::time::sleep(Duration::from_secs(2)).await;
             }

src/transport/middle_proxy/pool_init.rs

@@ -1,4 +1,4 @@
-use std::collections::{HashMap, HashSet};
+use std::collections::HashSet;
 use std::net::{IpAddr, SocketAddr};
 use std::sync::Arc;
 
@@ -14,10 +14,12 @@ use super::pool::MePool;
 impl MePool {
     pub async fn init(self: &Arc<Self>, pool_size: usize, rng: &Arc<SecureRandom>) -> Result<()> {
         let family_order = self.family_order();
+        let connect_concurrency = self.me_reconnect_max_concurrent_per_dc.max(1) as usize;
         let ks = self.key_selector().await;
         info!(
             me_servers = self.proxy_map_v4.read().await.len(),
             pool_size,
+            connect_concurrency,
             key_selector = format_args!("0x{ks:08x}"),
             secret_len = self.proxy_secret.read().await.secret.len(),
             "Initializing ME pool"
@@ -25,39 +27,54 @@ impl MePool {
 
         for family in family_order {
             let map = self.proxy_map_for_family(family).await;
-            let mut grouped_dc_addrs: HashMap<i32, Vec<(IpAddr, u16)>> = HashMap::new();
-            for (dc, addrs) in map {
-                if addrs.is_empty() {
-                    continue;
-                }
-                grouped_dc_addrs.entry(dc.abs()).or_default().extend(addrs);
-            }
-            let mut dc_addrs: Vec<(i32, Vec<(IpAddr, u16)>)> = grouped_dc_addrs
+            let mut dc_addrs: Vec<(i32, Vec<(IpAddr, u16)>)> = map
                 .into_iter()
                 .map(|(dc, mut addrs)| {
                     addrs.sort_unstable();
                     addrs.dedup();
                     (dc, addrs)
                 })
+                .filter(|(_, addrs)| !addrs.is_empty())
                 .collect();
             dc_addrs.sort_unstable_by_key(|(dc, _)| *dc);
+            dc_addrs.sort_by_key(|(_, addrs)| (addrs.len() != 1, addrs.len()));
 
-            // Ensure at least one live writer per DC group; run missing DCs in parallel.
+            // Stage 1: build base coverage for conditional-cast.
+            // Single-endpoint DCs are prefilled first; multi-endpoint DCs require one live writer.
             let mut join = tokio::task::JoinSet::new();
             for (dc, addrs) in dc_addrs.iter().cloned() {
                 if addrs.is_empty() {
                     continue;
                 }
+                let target_writers = if addrs.len() == 1 {
+                    self.required_writers_for_dc_with_floor_mode(addrs.len(), false)
+                } else {
+                    1usize
+                };
                 let endpoints: HashSet<SocketAddr> = addrs
                     .iter()
                     .map(|(ip, port)| SocketAddr::new(*ip, *port))
                     .collect();
-                if self.active_writer_count_for_endpoints(&endpoints).await > 0 {
+                if self
+                    .active_writer_count_for_dc_endpoints(dc, &endpoints)
+                    .await
+                    >= target_writers
+                {
                     continue;
                 }
                 let pool = Arc::clone(self);
                 let rng_clone = Arc::clone(rng);
-                join.spawn(async move { pool.connect_primary_for_dc(dc, addrs, rng_clone).await });
+                join.spawn(async move {
+                    pool.connect_primary_for_dc(
+                        dc,
+                        addrs,
+                        target_writers,
+                        rng_clone,
+                        connect_concurrency,
+                        true,
+                    )
+                    .await
+                });
             }
             while join.join_next().await.is_some() {}
 
@@ -67,7 +84,7 @@ impl MePool {
                     .iter()
                     .map(|(ip, port)| SocketAddr::new(*ip, *port))
                     .collect();
-                if self.active_writer_count_for_endpoints(&endpoints).await == 0 {
+                if self.active_writer_count_for_dc_endpoints(*dc, &endpoints).await == 0 {
                     missing_dcs.push(*dc);
                 }
             }
@@ -77,47 +94,36 @@ impl MePool {
                 )));
             }
 
-            // Warm reserve writers asynchronously so startup does not block after first working pool is ready.
+            // Stage 2: continue saturating multi-endpoint DC groups in background.
             let pool = Arc::clone(self);
             let rng_clone = Arc::clone(rng);
             let dc_addrs_bg = dc_addrs.clone();
             tokio::spawn(async move {
-                if pool.me_warmup_stagger_enabled {
-                    for (dc, addrs) in &dc_addrs_bg {
-                        for (ip, port) in addrs {
-                            if pool.connection_count() >= pool_size {
-                                break;
-                            }
-                            let addr = SocketAddr::new(*ip, *port);
-                            let jitter = rand::rng()
-                                .random_range(0..=pool.me_warmup_step_jitter.as_millis() as u64);
-                            let delay_ms = pool.me_warmup_step_delay.as_millis() as u64 + jitter;
-                            tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
-                            if let Err(e) = pool.connect_one(addr, rng_clone.as_ref()).await {
-                                debug!(%addr, dc = %dc, error = %e, "Extra ME connect failed (staggered)");
-                            }
-                        }
-                    }
-                } else {
-                    for (dc, addrs) in &dc_addrs_bg {
-                        for (ip, port) in addrs {
-                            if pool.connection_count() >= pool_size {
-                                break;
-                            }
-                            let addr = SocketAddr::new(*ip, *port);
-                            if let Err(e) = pool.connect_one(addr, rng_clone.as_ref()).await {
-                                debug!(%addr, dc = %dc, error = %e, "Extra ME connect failed");
-                            }
-                        }
-                        if pool.connection_count() >= pool_size {
-                            break;
-                        }
+                let mut join_bg = tokio::task::JoinSet::new();
+                for (dc, addrs) in dc_addrs_bg {
+                    if addrs.len() <= 1 {
+                        continue;
                     }
+                    let target_writers = pool.required_writers_for_dc_with_floor_mode(addrs.len(), false);
+                    let pool_clone = Arc::clone(&pool);
+                    let rng_clone_local = Arc::clone(&rng_clone);
+                    join_bg.spawn(async move {
+                        pool_clone
+                            .connect_primary_for_dc(
+                                dc,
+                                addrs,
+                                target_writers,
+                                rng_clone_local,
+                                connect_concurrency,
+                                false,
+                            )
+                            .await
+                    });
                 }
+                while join_bg.join_next().await.is_some() {}
                 debug!(
-                    target_pool_size = pool_size,
                     current_pool_size = pool.connection_count(),
-                    "Background ME reserve warmup finished"
+                    "Background ME saturation warmup finished"
                 );
             });
 
@@ -140,62 +146,111 @@ impl MePool {
         self: Arc<Self>,
         dc: i32,
         mut addrs: Vec<(IpAddr, u16)>,
+        target_writers: usize,
         rng: Arc<SecureRandom>,
+        connect_concurrency: usize,
+        allow_coverage_override: bool,
     ) -> bool {
         if addrs.is_empty() {
             return false;
         }
+        let target_writers = target_writers.max(1);
         addrs.shuffle(&mut rand::rng());
-        if addrs.len() > 1 {
-            let concurrency = 2usize;
+        let endpoints: Vec<SocketAddr> = addrs
+            .iter()
+            .map(|(ip, port)| SocketAddr::new(*ip, *port))
+            .collect();
+        let endpoint_set: HashSet<SocketAddr> = endpoints.iter().copied().collect();
+
+        loop {
+            let alive = self
+                .active_writer_count_for_dc_endpoints(dc, &endpoint_set)
+                .await;
+            if alive >= target_writers {
+                info!(
+                    dc = %dc,
+                    alive,
+                    target_writers,
+                    "ME connected"
+                );
+                return true;
+            }
+
+            let missing = target_writers.saturating_sub(alive).max(1);
+            let concurrency = connect_concurrency.max(1).min(missing);
             let mut join = tokio::task::JoinSet::new();
-            let mut next_idx = 0usize;
+            for _ in 0..concurrency {
+                let pool = Arc::clone(&self);
+                let rng_clone = Arc::clone(&rng);
+                let endpoints_clone = endpoints.clone();
+                let generation = self.current_generation();
+                join.spawn(async move {
+                    pool.connect_endpoints_round_robin_with_generation_contour(
+                        dc,
+                        &endpoints_clone,
+                        rng_clone.as_ref(),
+                        generation,
+                        super::pool::WriterContour::Active,
+                        allow_coverage_override,
+                    )
+                    .await
+                });
+            }
 
-            while next_idx < addrs.len() || !join.is_empty() {
-                while next_idx < addrs.len() && join.len() < concurrency {
-                    let (ip, port) = addrs[next_idx];
-                    next_idx += 1;
-                    let addr = SocketAddr::new(ip, port);
-                    let pool = Arc::clone(&self);
-                    let rng_clone = Arc::clone(&rng);
-                    join.spawn(async move {
-                        (addr, pool.connect_one(addr, rng_clone.as_ref()).await)
-                    });
-                }
-
-                let Some(res) = join.join_next().await else {
-                    break;
-                };
+            let mut progress = false;
+            while let Some(res) = join.join_next().await {
                 match res {
-                    Ok((addr, Ok(()))) => {
-                        info!(%addr, dc = %dc, "ME connected");
-                        join.abort_all();
-                        while join.join_next().await.is_some() {}
-                        return true;
-                    }
-                    Ok((addr, Err(e))) => {
-                        warn!(%addr, dc = %dc, error = %e, "ME connect failed, trying next");
+                    Ok(true) => {
+                        progress = true;
                     }
+                    Ok(false) => {}
                     Err(e) => {
                         warn!(dc = %dc, error = %e, "ME connect task failed");
                     }
                 }
             }
-            warn!(dc = %dc, "All ME servers for DC failed at init");
-            return false;
-        }
 
-        for (ip, port) in addrs {
-            let addr = SocketAddr::new(ip, port);
-            match self.connect_one(addr, rng.as_ref()).await {
-                Ok(()) => {
-                    info!(%addr, dc = %dc, "ME connected");
-                    return true;
+            let alive_after = self
+                .active_writer_count_for_dc_endpoints(dc, &endpoint_set)
+                .await;
+            if alive_after >= target_writers {
+                info!(
+                    dc = %dc,
+                    alive = alive_after,
+                    target_writers,
+                    "ME connected"
+                );
+                return true;
+            }
+            if !progress {
+                let active_writers_current = self.active_contour_writer_count_total().await;
+                let active_cap_configured = self.adaptive_floor_active_cap_configured_total();
+                if !allow_coverage_override && active_writers_current >= active_cap_configured {
+                    info!(
+                        dc = %dc,
+                        alive = alive_after,
+                        target_writers,
+                        active_writers_current,
+                        active_cap_configured,
+                        "ME init saturation stopped by active writer cap"
+                    );
+                } else {
+                    warn!(
+                        dc = %dc,
+                        alive = alive_after,
+                        target_writers,
+                        "All ME servers for DC failed at init"
+                    );
                 }
-                Err(e) => warn!(%addr, dc = %dc, error = %e, "ME connect failed, trying next"),
+                return false;
+            }
+
+            if self.me_warmup_stagger_enabled {
+                let jitter = rand::rng()
+                    .random_range(0..=self.me_warmup_step_jitter.as_millis() as u64);
+                let delay_ms = self.me_warmup_step_delay.as_millis() as u64 + jitter;
+                tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
             }
         }
-        warn!(dc = %dc, "All ME servers for DC failed at init");
-        false
     }
 }

src/transport/middle_proxy/pool_nat.rs

@@ -159,7 +159,13 @@ impl MePool {
         addr: std::net::SocketAddr,
         reflected: Option<std::net::SocketAddr>,
     ) -> std::net::SocketAddr {
-        let ip = if let Some(r) = reflected {
+        let ip = if let Some(nat_ip) = self.nat_ip_cfg {
+            match (addr.ip(), nat_ip) {
+                (IpAddr::V4(_), IpAddr::V4(dst)) => IpAddr::V4(dst),
+                (IpAddr::V6(_), IpAddr::V6(dst)) => IpAddr::V6(dst),
+                _ => addr.ip(),
+            }
+        } else if let Some(r) = reflected {
             // Use reflected IP (not port) only when local address is non-public.
             if is_bogon(addr.ip()) || addr.ip().is_loopback() || addr.ip().is_unspecified() {
                 r.ip()
@@ -248,6 +254,43 @@ impl MePool {
             }
         }
 
+        let _singleflight_guard = if use_shared_cache {
+            Some(match family {
+                IpFamily::V4 => self.nat_reflection_singleflight_v4.lock().await,
+                IpFamily::V6 => self.nat_reflection_singleflight_v6.lock().await,
+            })
+        } else {
+            None
+        };
+
+        if use_shared_cache
+            && let Some(until) = *self.stun_backoff_until.read().await
+            && Instant::now() < until
+        {
+            if let Ok(cache) = self.nat_reflection_cache.try_lock() {
+                let slot = match family {
+                    IpFamily::V4 => cache.v4,
+                    IpFamily::V6 => cache.v6,
+                };
+                return slot.map(|(_, addr)| addr);
+            }
+            return None;
+        }
+
+        if use_shared_cache
+            && let Ok(mut cache) = self.nat_reflection_cache.try_lock()
+        {
+            let slot = match family {
+                IpFamily::V4 => &mut cache.v4,
+                IpFamily::V6 => &mut cache.v6,
+            };
+            if let Some((ts, addr)) = slot
+                && ts.elapsed() < STUN_CACHE_TTL
+            {
+                return Some(*addr);
+            }
+        }
+
         let attempt = if use_shared_cache {
             self.nat_probe_attempts.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
         } else {

src/transport/middle_proxy/pool_refill.rs

@@ -1,4 +1,4 @@
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 use std::net::SocketAddr;
 use std::sync::Arc;
 use std::sync::atomic::Ordering;
@@ -9,7 +9,7 @@ use tracing::{debug, info, warn};
 use crate::crypto::SecureRandom;
 use crate::network::IpFamily;
 
-use super::pool::{MePool, RefillDcKey, WriterContour};
+use super::pool::{MePool, RefillDcKey, RefillEndpointKey, WriterContour};
 
 const ME_FLAP_UPTIME_THRESHOLD_SECS: u64 = 20;
 const ME_FLAP_QUARANTINE_SECS: u64 = 25;
@@ -37,7 +37,7 @@ impl MePool {
         );
     }
 
-    async fn is_endpoint_quarantined(&self, addr: SocketAddr) -> bool {
+    pub(super) async fn is_endpoint_quarantined(&self, addr: SocketAddr) -> bool {
         let mut guard = self.endpoint_quarantine.lock().await;
         let now = Instant::now();
         guard.retain(|_, expiry| *expiry > now);
@@ -82,91 +82,79 @@ impl MePool {
         Vec::new()
     }
 
-    pub(super) async fn has_refill_inflight_for_endpoints(&self, endpoints: &[SocketAddr]) -> bool {
-        if endpoints.is_empty() {
-            return false;
-        }
-
-        {
-            let guard = self.refill_inflight.lock().await;
-            if endpoints.iter().any(|addr| guard.contains(addr)) {
-                return true;
-            }
-        }
-
-        let dc_keys = self.resolve_refill_dc_keys_for_endpoints(endpoints).await;
-        if dc_keys.is_empty() {
-            return false;
-        }
+    pub(super) async fn has_refill_inflight_for_dc_key(&self, key: RefillDcKey) -> bool {
         let guard = self.refill_inflight_dc.lock().await;
-        dc_keys.iter().any(|key| guard.contains(key))
-    }
-
-    async fn resolve_refill_dc_key_for_addr(&self, addr: SocketAddr) -> Option<RefillDcKey> {
-        let family = if addr.is_ipv4() {
-            IpFamily::V4
-        } else {
-            IpFamily::V6
-        };
-        let map = self.proxy_map_for_family(family).await;
-        for (dc, endpoints) in map {
-            if endpoints
-                .into_iter()
-                .any(|(ip, port)| SocketAddr::new(ip, port) == addr)
-            {
-                return Some(RefillDcKey {
-                    dc: dc.abs(),
-                    family,
-                });
-            }
-        }
-        None
-    }
-
-    async fn resolve_refill_dc_keys_for_endpoints(
-        &self,
-        endpoints: &[SocketAddr],
-    ) -> HashSet<RefillDcKey> {
-        let mut out = HashSet::<RefillDcKey>::new();
-        for addr in endpoints {
-            if let Some(key) = self.resolve_refill_dc_key_for_addr(*addr).await {
-                out.insert(key);
-            }
-        }
-        out
+        guard.contains(&key)
     }
 
     pub(super) async fn connect_endpoints_round_robin(
         self: &Arc<Self>,
+        dc: i32,
         endpoints: &[SocketAddr],
         rng: &SecureRandom,
     ) -> bool {
         self.connect_endpoints_round_robin_with_generation_contour(
+            dc,
             endpoints,
             rng,
             self.current_generation(),
             WriterContour::Active,
+            false,
         )
         .await
     }
 
     pub(super) async fn connect_endpoints_round_robin_with_generation_contour(
         self: &Arc<Self>,
+        dc: i32,
         endpoints: &[SocketAddr],
         rng: &SecureRandom,
         generation: u64,
         contour: WriterContour,
+        allow_coverage_override: bool,
     ) -> bool {
-        let candidates = self.connectable_endpoints(endpoints).await;
+        let mut candidates = self.connectable_endpoints(endpoints).await;
         if candidates.is_empty() {
             return false;
         }
+        if candidates.len() > 1 {
+            let mut active_by_endpoint = HashMap::<SocketAddr, usize>::new();
+            let ws = self.writers.read().await;
+            for writer in ws.iter() {
+                if writer.draining.load(Ordering::Relaxed) {
+                    continue;
+                }
+                if writer.writer_dc != dc {
+                    continue;
+                }
+                if !matches!(
+                    super::pool::WriterContour::from_u8(
+                        writer.contour.load(Ordering::Relaxed),
+                    ),
+                    super::pool::WriterContour::Active
+                ) {
+                    continue;
+                }
+                if candidates.contains(&writer.addr) {
+                    *active_by_endpoint.entry(writer.addr).or_insert(0) += 1;
+                }
+            }
+            drop(ws);
+            candidates.sort_by_key(|addr| (active_by_endpoint.get(addr).copied().unwrap_or(0), *addr));
+        }
         let start = (self.rr.fetch_add(1, Ordering::Relaxed) as usize) % candidates.len();
         for offset in 0..candidates.len() {
             let idx = (start + offset) % candidates.len();
             let addr = candidates[idx];
             match self
-                .connect_one_with_generation_contour(addr, rng, generation, contour)
+                .connect_one_with_generation_contour_for_dc_with_cap_policy(
+                    addr,
+                    rng,
+                    generation,
+                    contour,
+                    dc,
+                    allow_coverage_override,
+                )
                 .await
             {
                 Ok(()) => return true,
@@ -176,48 +164,23 @@ impl MePool {
         false
     }
 
-    async fn endpoints_for_same_dc(&self, addr: SocketAddr) -> Vec<SocketAddr> {
-        let mut target_dc = HashSet::<i32>::new();
+    async fn endpoints_for_dc(&self, target_dc: i32) -> Vec<SocketAddr> {
         let mut endpoints = HashSet::<SocketAddr>::new();
 
         if self.decision.ipv4_me {
-            let map = self.proxy_map_v4.read().await.clone();
-            for (dc, addrs) in &map {
-                if addrs
-                    .iter()
-                    .any(|(ip, port)| SocketAddr::new(*ip, *port) == addr)
-                {
-                    target_dc.insert(dc.abs());
-                }
-            }
-            for dc in &target_dc {
-                for key in [*dc, -*dc] {
-                    if let Some(addrs) = map.get(&key) {
-                        for (ip, port) in addrs {
-                            endpoints.insert(SocketAddr::new(*ip, *port));
-                        }
-                    }
+            let map = self.proxy_map_v4.read().await;
+            if let Some(addrs) = map.get(&target_dc) {
+                for (ip, port) in addrs {
+                    endpoints.insert(SocketAddr::new(*ip, *port));
                 }
             }
         }
 
         if self.decision.ipv6_me {
-            let map = self.proxy_map_v6.read().await.clone();
-            for (dc, addrs) in &map {
-                if addrs
-                    .iter()
-                    .any(|(ip, port)| SocketAddr::new(*ip, *port) == addr)
-                {
-                    target_dc.insert(dc.abs());
-                }
-            }
-            for dc in &target_dc {
-                for key in [*dc, -*dc] {
-                    if let Some(addrs) = map.get(&key) {
-                        for (ip, port) in addrs {
-                            endpoints.insert(SocketAddr::new(*ip, *port));
-                        }
-                    }
+            let map = self.proxy_map_v6.read().await;
+            if let Some(addrs) = map.get(&target_dc) {
+                for (ip, port) in addrs {
+                    endpoints.insert(SocketAddr::new(*ip, *port));
                 }
             }
         }
@@ -227,14 +190,14 @@ impl MePool {
         sorted
     }
 
-    async fn refill_writer_after_loss(self: &Arc<Self>, addr: SocketAddr) -> bool {
+    async fn refill_writer_after_loss(self: &Arc<Self>, addr: SocketAddr, writer_dc: i32) -> bool {
         let fast_retries = self.me_reconnect_fast_retry_count.max(1);
         let same_endpoint_quarantined = self.is_endpoint_quarantined(addr).await;
 
         if !same_endpoint_quarantined {
             for attempt in 0..fast_retries {
                 self.stats.increment_me_reconnect_attempt();
-                match self.connect_one(addr, self.rng.as_ref()).await {
+                match self.connect_one_for_dc(addr, writer_dc, self.rng.as_ref()).await {
                     Ok(()) => {
                         self.stats.increment_me_reconnect_success();
                         self.stats.increment_me_writer_restored_same_endpoint_total();
@@ -262,7 +225,7 @@ impl MePool {
             );
         }
 
-        let dc_endpoints = self.endpoints_for_same_dc(addr).await;
+        let dc_endpoints = self.endpoints_for_dc(writer_dc).await;
         if dc_endpoints.is_empty() {
             self.stats.increment_me_refill_failed_total();
             return false;
@@ -271,7 +234,7 @@ impl MePool {
         for attempt in 0..fast_retries {
             self.stats.increment_me_reconnect_attempt();
             if self
-                .connect_endpoints_round_robin(&dc_endpoints, self.rng.as_ref())
+                .connect_endpoints_round_robin(writer_dc, &dc_endpoints, self.rng.as_ref())
                 .await
             {
                 self.stats.increment_me_reconnect_success();
@@ -289,48 +252,63 @@ impl MePool {
         false
     }
 
-    pub(crate) fn trigger_immediate_refill(self: &Arc<Self>, addr: SocketAddr) {
+    pub(crate) fn trigger_immediate_refill_for_dc(self: &Arc<Self>, addr: SocketAddr, writer_dc: i32) {
+        let endpoint_key = RefillEndpointKey {
+            dc: writer_dc,
+            addr,
+        };
+        let pre_inserted = if let Ok(mut guard) = self.refill_inflight.try_lock() {
+            if !guard.insert(endpoint_key) {
+                self.stats.increment_me_refill_skipped_inflight_total();
+                return;
+            }
+            true
+        } else {
+            false
+        };
+
         let pool = Arc::clone(self);
         tokio::spawn(async move {
-            let dc_endpoints = pool.endpoints_for_same_dc(addr).await;
-            let dc_keys = pool.resolve_refill_dc_keys_for_endpoints(&dc_endpoints).await;
+            let dc_key = RefillDcKey {
+                dc: writer_dc,
+                family: if addr.is_ipv4() {
+                    IpFamily::V4
+                } else {
+                    IpFamily::V6
+                },
+            };
 
-            {
+            if !pre_inserted {
                 let mut guard = pool.refill_inflight.lock().await;
-                if !guard.insert(addr) {
+                if !guard.insert(endpoint_key) {
                     pool.stats.increment_me_refill_skipped_inflight_total();
                     return;
                 }
             }
 
-            if !dc_keys.is_empty() {
+            {
                 let mut dc_guard = pool.refill_inflight_dc.lock().await;
-                if dc_keys.iter().any(|key| dc_guard.contains(key)) {
+                if dc_guard.contains(&dc_key) {
                     pool.stats.increment_me_refill_skipped_inflight_total();
                     drop(dc_guard);
                     let mut guard = pool.refill_inflight.lock().await;
-                    guard.remove(&addr);
+                    guard.remove(&endpoint_key);
                     return;
                 }
-                dc_guard.extend(dc_keys.iter().copied());
+                dc_guard.insert(dc_key);
             }
 
             pool.stats.increment_me_refill_triggered_total();
-
-            let restored = pool.refill_writer_after_loss(addr).await;
+            let restored = pool.refill_writer_after_loss(addr, writer_dc).await;
             if !restored {
-                warn!(%addr, "ME immediate refill failed");
+                warn!(%addr, dc = writer_dc, "ME immediate refill failed");
             }
 
             let mut guard = pool.refill_inflight.lock().await;
-            guard.remove(&addr);
+            guard.remove(&endpoint_key);
             drop(guard);
-            if !dc_keys.is_empty() {
-                let mut dc_guard = pool.refill_inflight_dc.lock().await;
-                for key in &dc_keys {
-                    dc_guard.remove(key);
-                }
-            }
+            let mut dc_guard = pool.refill_inflight_dc.lock().await;
+            dc_guard.remove(&dc_key);
         });
     }
 }

src/transport/middle_proxy/pool_reinit.rs

@@ -62,7 +62,7 @@ impl MePool {
 
     fn coverage_ratio(
         desired_by_dc: &HashMap<i32, HashSet<SocketAddr>>,
-        active_writer_addrs: &HashSet<SocketAddr>,
+        active_writer_addrs: &HashSet<(i32, SocketAddr)>,
     ) -> (f32, Vec<i32>) {
         if desired_by_dc.is_empty() {
             return (1.0, Vec::new());
@@ -76,7 +76,7 @@ impl MePool {
             }
             if endpoints
                 .iter()
-                .any(|addr| active_writer_addrs.contains(addr))
+                .any(|addr| active_writer_addrs.contains(&(*dc, *addr)))
             {
                 covered += 1;
             } else {
@@ -91,32 +91,25 @@ impl MePool {
     }
 
     pub async fn reconcile_connections(self: &Arc<Self>, rng: &SecureRandom) {
-        let writers = self.writers.read().await;
-        let current: HashSet<SocketAddr> = writers
-            .iter()
-            .filter(|w| !w.draining.load(Ordering::Relaxed))
-            .map(|w| w.addr)
-            .collect();
-        drop(writers);
-
         for family in self.family_order() {
             let map = self.proxy_map_for_family(family).await;
-            for (_dc, addrs) in &map {
+            for (dc, addrs) in &map {
                 let dc_addrs: Vec<SocketAddr> = addrs
                     .iter()
                     .map(|(ip, port)| SocketAddr::new(*ip, *port))
                     .collect();
-                if !dc_addrs.iter().any(|a| current.contains(a)) {
+                let dc_endpoints: HashSet<SocketAddr> = dc_addrs.iter().copied().collect();
+                if self.active_writer_count_for_dc_endpoints(*dc, &dc_endpoints).await == 0 {
                     let mut shuffled = dc_addrs.clone();
                     shuffled.shuffle(&mut rand::rng());
                     for addr in shuffled {
-                        if self.connect_one(addr, rng).await.is_ok() {
+                        if self.connect_one_for_dc(addr, *dc, rng).await.is_ok() {
                             break;
                         }
                     }
                 }
             }
-            if !self.decision.effective_multipath && !current.is_empty() {
+            if !self.decision.effective_multipath && self.connection_count() > 0 {
                 break;
             }
         }
@@ -128,7 +121,7 @@ impl MePool {
         if self.decision.ipv4_me {
             let map_v4 = self.proxy_map_v4.read().await.clone();
             for (dc, addrs) in map_v4 {
-                let entry = out.entry(dc.abs()).or_default();
+                let entry = out.entry(dc).or_default();
                 for (ip, port) in addrs {
                     entry.insert(SocketAddr::new(ip, port));
                 }
@@ -138,7 +131,7 @@ impl MePool {
         if self.decision.ipv6_me {
             let map_v6 = self.proxy_map_v6.read().await.clone();
             for (dc, addrs) in map_v6 {
-                let entry = out.entry(dc.abs()).or_default();
+                let entry = out.entry(dc).or_default();
                 for (ip, port) in addrs {
                     entry.insert(SocketAddr::new(ip, port));
                 }
@@ -148,6 +141,38 @@ impl MePool {
         out
     }
 
+    pub(super) async fn has_non_draining_writer_per_desired_dc_group(&self) -> bool {
+        let desired_by_dc = self.desired_dc_endpoints().await;
+        let required_dcs: HashSet<i32> = desired_by_dc
+            .iter()
+            .filter_map(|(dc, endpoints)| {
+                if endpoints.is_empty() {
+                    None
+                } else {
+                    Some(*dc)
+                }
+            })
+            .collect();
+        if required_dcs.is_empty() {
+            return true;
+        }
+
+        let ws = self.writers.read().await;
+        let mut covered_dcs = HashSet::<i32>::with_capacity(required_dcs.len());
+        for writer in ws.iter() {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            if required_dcs.contains(&writer.writer_dc) {
+                covered_dcs.insert(writer.writer_dc);
+                if covered_dcs.len() == required_dcs.len() {
+                    return true;
+                }
+            }
+        }
+        false
+    }
+
     fn hardswap_warmup_connect_delay_ms(&self) -> u64 {
         let min_ms = self.me_hardswap_warmup_delay_min_ms.load(Ordering::Relaxed);
         let max_ms = self.me_hardswap_warmup_delay_max_ms.load(Ordering::Relaxed);
@@ -174,26 +199,30 @@ impl MePool {
         core.saturating_add(rand::rng().random_range(0..=jitter))
     }
 
-    async fn fresh_writer_count_for_endpoints(
+    async fn fresh_writer_count_for_dc_endpoints(
         &self,
         generation: u64,
+        dc: i32,
         endpoints: &HashSet<SocketAddr>,
     ) -> usize {
         let ws = self.writers.read().await;
         ws.iter()
             .filter(|w| !w.draining.load(Ordering::Relaxed))
             .filter(|w| w.generation == generation)
+            .filter(|w| w.writer_dc == dc)
             .filter(|w| endpoints.contains(&w.addr))
             .count()
     }
 
-    pub(super) async fn active_writer_count_for_endpoints(
+    pub(super) async fn active_writer_count_for_dc_endpoints(
         &self,
+        dc: i32,
         endpoints: &HashSet<SocketAddr>,
     ) -> usize {
         let ws = self.writers.read().await;
         ws.iter()
             .filter(|w| !w.draining.load(Ordering::Relaxed))
+            .filter(|w| w.writer_dc == dc)
             .filter(|w| endpoints.contains(&w.addr))
             .count()
     }
@@ -220,7 +249,7 @@ impl MePool {
             let required = self.required_writers_for_dc(endpoint_list.len());
             let mut completed = false;
             let mut last_fresh_count = self
-                .fresh_writer_count_for_endpoints(generation, endpoints)
+                .fresh_writer_count_for_dc_endpoints(generation, *dc, endpoints)
                 .await;
 
             for pass_idx in 0..total_passes {
@@ -247,10 +276,12 @@ impl MePool {
 
                     let connected = self
                         .connect_endpoints_round_robin_with_generation_contour(
+                            *dc,
                             &endpoint_list,
                             rng,
                             generation,
                             WriterContour::Warm,
+                            false,
                         )
                         .await;
                     debug!(
@@ -265,7 +296,7 @@ impl MePool {
                 }
 
                 last_fresh_count = self
-                    .fresh_writer_count_for_endpoints(generation, endpoints)
+                    .fresh_writer_count_for_dc_endpoints(generation, *dc, endpoints)
                     .await;
                 if last_fresh_count >= required {
                     completed = true;
@@ -377,10 +408,10 @@ impl MePool {
         }
 
         let writers = self.writers.read().await;
-        let active_writer_addrs: HashSet<SocketAddr> = writers
+        let active_writer_addrs: HashSet<(i32, SocketAddr)> = writers
             .iter()
             .filter(|w| !w.draining.load(Ordering::Relaxed))
-            .map(|w| w.addr)
+            .map(|w| (w.writer_dc, w.addr))
             .collect();
         let min_ratio = Self::permille_to_ratio(
             self.me_pool_min_fresh_ratio_permille
@@ -410,6 +441,7 @@ impl MePool {
                     .iter()
                     .filter(|w| !w.draining.load(Ordering::Relaxed))
                     .filter(|w| w.generation == generation)
+                    .filter(|w| w.writer_dc == *dc)
                     .filter(|w| endpoints.contains(&w.addr))
                     .count();
                 if fresh_count < required {
@@ -438,9 +470,9 @@ impl MePool {
             self.promote_warm_generation_to_active(generation).await;
         }
 
-        let desired_addrs: HashSet<SocketAddr> = desired_by_dc
-            .values()
-            .flat_map(|set| set.iter().copied())
+        let desired_addrs: HashSet<(i32, SocketAddr)> = desired_by_dc
+            .iter()
+            .flat_map(|(dc, set)| set.iter().copied().map(|addr| (*dc, addr)))
             .collect();
 
         let stale_writer_ids: Vec<u64> = writers
@@ -450,7 +482,7 @@ impl MePool {
                 if hardswap {
                     w.generation < generation
                 } else {
-                    !desired_addrs.contains(&w.addr)
+                    !desired_addrs.contains(&(w.writer_dc, w.addr))
                 }
             })
             .map(|w| w.id)
@@ -475,12 +507,30 @@ impl MePool {
             coverage_ratio = format_args!("{coverage_ratio:.3}"),
             min_ratio = format_args!("{min_ratio:.3}"),
             drain_timeout_secs,
-            "ME reinit cycle covered; draining stale writers"
+            "ME reinit cycle covered; processing stale writers"
         );
         self.stats.increment_pool_swap_total();
+        let can_drop_with_replacement = self
+            .has_non_draining_writer_per_desired_dc_group()
+            .await;
+        if can_drop_with_replacement {
+            info!(
+                stale_writers = stale_writer_ids.len(),
+                "ME reinit stale writers: replacement coverage ready, force-closing clients for fast rebind"
+            );
+        } else {
+            warn!(
+                stale_writers = stale_writer_ids.len(),
+                "ME reinit stale writers: replacement coverage incomplete, keeping draining fallback"
+            );
+        }
         for writer_id in stale_writer_ids {
             self.mark_writer_draining_with_timeout(writer_id, drain_timeout, !hardswap)
                 .await;
+            if can_drop_with_replacement {
+                self.stats.increment_pool_force_close_total();
+                self.remove_writer_and_close_clients(writer_id).await;
+            }
         }
         if hardswap {
             self.clear_pending_hardswap_state();

src/transport/middle_proxy/pool_runtime_api.rs

@@ -0,0 +1,128 @@
+use std::collections::HashMap;
+use std::time::Instant;
+
+use super::pool::{MePool, RefillDcKey};
+use crate::network::IpFamily;
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiRefillDcSnapshot {
+    pub dc: i16,
+    pub family: &'static str,
+    pub inflight: usize,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiRefillSnapshot {
+    pub inflight_endpoints_total: usize,
+    pub inflight_dc_total: usize,
+    pub by_dc: Vec<MeApiRefillDcSnapshot>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiNatReflectionSnapshot {
+    pub addr: std::net::SocketAddr,
+    pub age_secs: u64,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiNatStunSnapshot {
+    pub nat_probe_enabled: bool,
+    pub nat_probe_disabled_runtime: bool,
+    pub nat_probe_attempts: u8,
+    pub configured_servers: Vec<String>,
+    pub live_servers: Vec<String>,
+    pub reflection_v4: Option<MeApiNatReflectionSnapshot>,
+    pub reflection_v6: Option<MeApiNatReflectionSnapshot>,
+    pub stun_backoff_remaining_ms: Option<u64>,
+}
+
+impl MePool {
+    pub(crate) async fn api_refill_snapshot(&self) -> MeApiRefillSnapshot {
+        let inflight_endpoints_total = self.refill_inflight.lock().await.len();
+        let inflight_dc_keys = self
+            .refill_inflight_dc
+            .lock()
+            .await
+            .iter()
+            .copied()
+            .collect::<Vec<RefillDcKey>>();
+
+        let mut by_dc_map = HashMap::<(i16, &'static str), usize>::new();
+        for key in inflight_dc_keys {
+            let family = match key.family {
+                IpFamily::V4 => "v4",
+                IpFamily::V6 => "v6",
+            };
+            let dc = key.dc as i16;
+            *by_dc_map.entry((dc, family)).or_insert(0) += 1;
+        }
+
+        let mut by_dc = by_dc_map
+            .into_iter()
+            .map(|((dc, family), inflight)| MeApiRefillDcSnapshot {
+                dc,
+                family,
+                inflight,
+            })
+            .collect::<Vec<_>>();
+        by_dc.sort_by_key(|entry| (entry.dc, entry.family));
+
+        MeApiRefillSnapshot {
+            inflight_endpoints_total,
+            inflight_dc_total: by_dc.len(),
+            by_dc,
+        }
+    }
+
+    pub(crate) async fn api_nat_stun_snapshot(&self) -> MeApiNatStunSnapshot {
+        let now = Instant::now();
+        let mut configured_servers = if !self.nat_stun_servers.is_empty() {
+            self.nat_stun_servers.clone()
+        } else if let Some(stun) = &self.nat_stun {
+            if stun.trim().is_empty() {
+                Vec::new()
+            } else {
+                vec![stun.clone()]
+            }
+        } else {
+            Vec::new()
+        };
+        configured_servers.sort();
+        configured_servers.dedup();
+
+        let mut live_servers = self.nat_stun_live_servers.read().await.clone();
+        live_servers.sort();
+        live_servers.dedup();
+
+        let reflection = self.nat_reflection_cache.lock().await;
+        let reflection_v4 = reflection.v4.map(|(ts, addr)| MeApiNatReflectionSnapshot {
+            addr,
+            age_secs: now.saturating_duration_since(ts).as_secs(),
+        });
+        let reflection_v6 = reflection.v6.map(|(ts, addr)| MeApiNatReflectionSnapshot {
+            addr,
+            age_secs: now.saturating_duration_since(ts).as_secs(),
+        });
+        drop(reflection);
+
+        let backoff_until = *self.stun_backoff_until.read().await;
+        let stun_backoff_remaining_ms = backoff_until.and_then(|until| {
+            (until > now).then_some(until.duration_since(now).as_millis() as u64)
+        });
+
+        MeApiNatStunSnapshot {
+            nat_probe_enabled: self.nat_probe,
+            nat_probe_disabled_runtime: self
+                .nat_probe_disabled
+                .load(std::sync::atomic::Ordering::Relaxed),
+            nat_probe_attempts: self
+                .nat_probe_attempts
+                .load(std::sync::atomic::Ordering::Relaxed),
+            configured_servers,
+            live_servers,
+            reflection_v4,
+            reflection_v6,
+            stun_backoff_remaining_ms,
+        }
+    }
+}

src/transport/middle_proxy/pool_status.rs

@@ -0,0 +1,684 @@
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+use std::net::{IpAddr, SocketAddr};
+use std::sync::atomic::Ordering;
+use std::time::Instant;
+
+use super::pool::{MePool, WriterContour};
+use crate::config::{MeBindStaleMode, MeFloorMode, MeSocksKdfPolicy};
+use crate::transport::upstream::IpPreference;
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiWriterStatusSnapshot {
+    pub writer_id: u64,
+    pub dc: Option<i16>,
+    pub endpoint: SocketAddr,
+    pub generation: u64,
+    pub state: &'static str,
+    pub draining: bool,
+    pub degraded: bool,
+    pub bound_clients: usize,
+    pub idle_for_secs: Option<u64>,
+    pub rtt_ema_ms: Option<f64>,
+    pub matches_active_generation: bool,
+    pub in_desired_map: bool,
+    pub allow_drain_fallback: bool,
+    pub drain_started_at_epoch_secs: Option<u64>,
+    pub drain_deadline_epoch_secs: Option<u64>,
+    pub drain_over_ttl: bool,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiDcStatusSnapshot {
+    pub dc: i16,
+    pub endpoints: Vec<SocketAddr>,
+    pub endpoint_writers: Vec<MeApiDcEndpointWriterSnapshot>,
+    pub available_endpoints: usize,
+    pub available_pct: f64,
+    pub required_writers: usize,
+    pub floor_min: usize,
+    pub floor_target: usize,
+    pub floor_max: usize,
+    pub floor_capped: bool,
+    pub alive_writers: usize,
+    pub coverage_pct: f64,
+    pub fresh_alive_writers: usize,
+    pub fresh_coverage_pct: f64,
+    pub rtt_ms: Option<f64>,
+    pub load: usize,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiDcEndpointWriterSnapshot {
+    pub endpoint: SocketAddr,
+    pub active_writers: usize,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiStatusSnapshot {
+    pub generated_at_epoch_secs: u64,
+    pub configured_dc_groups: usize,
+    pub configured_endpoints: usize,
+    pub available_endpoints: usize,
+    pub available_pct: f64,
+    pub required_writers: usize,
+    pub alive_writers: usize,
+    pub coverage_pct: f64,
+    pub fresh_alive_writers: usize,
+    pub fresh_coverage_pct: f64,
+    pub writers: Vec<MeApiWriterStatusSnapshot>,
+    pub dcs: Vec<MeApiDcStatusSnapshot>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiQuarantinedEndpointSnapshot {
+    pub endpoint: SocketAddr,
+    pub remaining_ms: u64,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiDcPathSnapshot {
+    pub dc: i16,
+    pub ip_preference: Option<&'static str>,
+    pub selected_addr_v4: Option<SocketAddr>,
+    pub selected_addr_v6: Option<SocketAddr>,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeApiRuntimeSnapshot {
+    pub active_generation: u64,
+    pub warm_generation: u64,
+    pub pending_hardswap_generation: u64,
+    pub pending_hardswap_age_secs: Option<u64>,
+    pub hardswap_enabled: bool,
+    pub floor_mode: &'static str,
+    pub adaptive_floor_idle_secs: u64,
+    pub adaptive_floor_min_writers_single_endpoint: u8,
+    pub adaptive_floor_min_writers_multi_endpoint: u8,
+    pub adaptive_floor_recover_grace_secs: u64,
+    pub adaptive_floor_writers_per_core_total: u16,
+    pub adaptive_floor_cpu_cores_override: u16,
+    pub adaptive_floor_max_extra_writers_single_per_core: u16,
+    pub adaptive_floor_max_extra_writers_multi_per_core: u16,
+    pub adaptive_floor_max_active_writers_per_core: u16,
+    pub adaptive_floor_max_warm_writers_per_core: u16,
+    pub adaptive_floor_max_active_writers_global: u32,
+    pub adaptive_floor_max_warm_writers_global: u32,
+    pub adaptive_floor_cpu_cores_detected: u32,
+    pub adaptive_floor_cpu_cores_effective: u32,
+    pub adaptive_floor_global_cap_raw: u64,
+    pub adaptive_floor_global_cap_effective: u64,
+    pub adaptive_floor_target_writers_total: u64,
+    pub adaptive_floor_active_cap_configured: u64,
+    pub adaptive_floor_active_cap_effective: u64,
+    pub adaptive_floor_warm_cap_configured: u64,
+    pub adaptive_floor_warm_cap_effective: u64,
+    pub adaptive_floor_active_writers_current: u64,
+    pub adaptive_floor_warm_writers_current: u64,
+    pub me_keepalive_enabled: bool,
+    pub me_keepalive_interval_secs: u64,
+    pub me_keepalive_jitter_secs: u64,
+    pub me_keepalive_payload_random: bool,
+    pub rpc_proxy_req_every_secs: u64,
+    pub me_reconnect_max_concurrent_per_dc: u32,
+    pub me_reconnect_backoff_base_ms: u64,
+    pub me_reconnect_backoff_cap_ms: u64,
+    pub me_reconnect_fast_retry_count: u32,
+    pub me_pool_drain_ttl_secs: u64,
+    pub me_pool_force_close_secs: u64,
+    pub me_pool_min_fresh_ratio: f32,
+    pub me_bind_stale_mode: &'static str,
+    pub me_bind_stale_ttl_secs: u64,
+    pub me_single_endpoint_shadow_writers: u8,
+    pub me_single_endpoint_outage_mode_enabled: bool,
+    pub me_single_endpoint_outage_disable_quarantine: bool,
+    pub me_single_endpoint_outage_backoff_min_ms: u64,
+    pub me_single_endpoint_outage_backoff_max_ms: u64,
+    pub me_single_endpoint_shadow_rotate_every_secs: u64,
+    pub me_deterministic_writer_sort: bool,
+    pub me_writer_pick_mode: &'static str,
+    pub me_writer_pick_sample_size: u8,
+    pub me_socks_kdf_policy: &'static str,
+    pub quarantined_endpoints: Vec<MeApiQuarantinedEndpointSnapshot>,
+    pub network_path: Vec<MeApiDcPathSnapshot>,
+}
+
+impl MePool {
+    pub(crate) async fn admission_ready_conditional_cast(&self) -> bool {
+        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+
+        if endpoints_by_dc.is_empty() {
+            return false;
+        }
+
+        let writers = self.writers.read().await.clone();
+        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
+        for writer in writers {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            if let Ok(dc) = i16::try_from(writer.writer_dc) {
+                *live_writers_by_dc.entry(dc).or_insert(0) += 1;
+            }
+        }
+
+        for dc in endpoints_by_dc.keys() {
+            let alive = live_writers_by_dc.get(dc).copied().unwrap_or(0);
+            if alive == 0 {
+                return false;
+            }
+        }
+
+        true
+    }
+
+    #[allow(dead_code)]
+    pub(crate) async fn admission_ready_full_floor(&self) -> bool {
+        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+
+        if endpoints_by_dc.is_empty() {
+            return false;
+        }
+
+        let writers = self.writers.read().await.clone();
+        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
+        for writer in writers {
+            if writer.draining.load(Ordering::Relaxed) {
+                continue;
+            }
+            if let Ok(dc) = i16::try_from(writer.writer_dc) {
+                *live_writers_by_dc.entry(dc).or_insert(0) += 1;
+            }
+        }
+
+        for (dc, endpoints) in endpoints_by_dc {
+            let endpoint_count = endpoints.len();
+            if endpoint_count == 0 {
+                return false;
+            }
+            let required = self.required_writers_for_dc_with_floor_mode(endpoint_count, false);
+            let alive = live_writers_by_dc.get(&dc).copied().unwrap_or(0);
+            if alive < required {
+                return false;
+            }
+        }
+
+        true
+    }
+
+    pub(crate) async fn api_status_snapshot(&self) -> MeApiStatusSnapshot {
+        let now_epoch_secs = Self::now_epoch_secs();
+        let active_generation = self.current_generation();
+        let drain_ttl_secs = self.me_pool_drain_ttl_secs.load(Ordering::Relaxed);
+
+        let mut endpoints_by_dc = BTreeMap::<i16, BTreeSet<SocketAddr>>::new();
+        if self.decision.ipv4_me {
+            let map = self.proxy_map_v4.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+        if self.decision.ipv6_me {
+            let map = self.proxy_map_v6.read().await.clone();
+            extend_signed_endpoints(&mut endpoints_by_dc, map);
+        }
+
+        let configured_dc_groups = endpoints_by_dc.len();
+        let configured_endpoints = endpoints_by_dc.values().map(BTreeSet::len).sum();
+
+        let required_writers = endpoints_by_dc
+            .values()
+            .map(|endpoints| self.required_writers_for_dc_with_floor_mode(endpoints.len(), false))
+            .sum();
+
+        let idle_since = self.registry.writer_idle_since_snapshot().await;
+        let activity = self.registry.writer_activity_snapshot().await;
+        let rtt = self.rtt_stats.lock().await.clone();
+        let writers = self.writers.read().await.clone();
+
+        let mut live_writers_by_dc_endpoint = HashMap::<(i16, SocketAddr), usize>::new();
+        let mut live_writers_by_dc = HashMap::<i16, usize>::new();
+        let mut fresh_writers_by_dc = HashMap::<i16, usize>::new();
+        let mut dc_rtt_agg = HashMap::<i16, (f64, u64)>::new();
+        let mut writer_rows = Vec::<MeApiWriterStatusSnapshot>::with_capacity(writers.len());
+
+        for writer in writers {
+            let endpoint = writer.addr;
+            let dc = i16::try_from(writer.writer_dc).ok();
+            let draining = writer.draining.load(Ordering::Relaxed);
+            let degraded = writer.degraded.load(Ordering::Relaxed);
+            let matches_active_generation = writer.generation == active_generation;
+            let in_desired_map = dc
+                .and_then(|dc_idx| endpoints_by_dc.get(&dc_idx))
+                .is_some_and(|endpoints| endpoints.contains(&endpoint));
+            let bound_clients = activity
+                .bound_clients_by_writer
+                .get(&writer.id)
+                .copied()
+                .unwrap_or(0);
+            let idle_for_secs = idle_since
+                .get(&writer.id)
+                .map(|idle_ts| now_epoch_secs.saturating_sub(*idle_ts));
+            let rtt_ema_ms = rtt.get(&writer.id).map(|(_, ema)| *ema);
+            let allow_drain_fallback = writer.allow_drain_fallback.load(Ordering::Relaxed);
+            let drain_started_at_epoch_secs = writer
+                .draining_started_at_epoch_secs
+                .load(Ordering::Relaxed);
+            let drain_deadline_epoch_secs = writer
+                .drain_deadline_epoch_secs
+                .load(Ordering::Relaxed);
+            let drain_started_at_epoch_secs =
+                (drain_started_at_epoch_secs != 0).then_some(drain_started_at_epoch_secs);
+            let drain_deadline_epoch_secs =
+                (drain_deadline_epoch_secs != 0).then_some(drain_deadline_epoch_secs);
+            let drain_over_ttl = draining
+                && drain_ttl_secs > 0
+                && drain_started_at_epoch_secs
+                    .is_some_and(|started| now_epoch_secs.saturating_sub(started) > drain_ttl_secs);
+            let state = match WriterContour::from_u8(writer.contour.load(Ordering::Relaxed)) {
+                WriterContour::Warm => "warm",
+                WriterContour::Active => "active",
+                WriterContour::Draining => "draining",
+            };
+
+            if !draining {
+                if let Some(dc_idx) = dc {
+                    *live_writers_by_dc_endpoint
+                        .entry((dc_idx, endpoint))
+                        .or_insert(0) += 1;
+                    *live_writers_by_dc.entry(dc_idx).or_insert(0) += 1;
+                    if let Some(ema_ms) = rtt_ema_ms {
+                        let entry = dc_rtt_agg.entry(dc_idx).or_insert((0.0, 0));
+                        entry.0 += ema_ms;
+                        entry.1 += 1;
+                    }
+                    if matches_active_generation && in_desired_map {
+                        *fresh_writers_by_dc.entry(dc_idx).or_insert(0) += 1;
+                    }
+                }
+            }
+
+            writer_rows.push(MeApiWriterStatusSnapshot {
+                writer_id: writer.id,
+                dc,
+                endpoint,
+                generation: writer.generation,
+                state,
+                draining,
+                degraded,
+                bound_clients,
+                idle_for_secs,
+                rtt_ema_ms,
+                matches_active_generation,
+                in_desired_map,
+                allow_drain_fallback,
+                drain_started_at_epoch_secs,
+                drain_deadline_epoch_secs,
+                drain_over_ttl,
+            });
+        }
+
+        writer_rows.sort_by_key(|row| (row.dc.unwrap_or(i16::MAX), row.endpoint, row.writer_id));
+
+        let mut dcs = Vec::<MeApiDcStatusSnapshot>::with_capacity(endpoints_by_dc.len());
+        let mut available_endpoints = 0usize;
+        let mut alive_writers = 0usize;
+        let mut fresh_alive_writers = 0usize;
+        let floor_mode = self.floor_mode();
+        let adaptive_cpu_cores = (self
+            .me_adaptive_floor_cpu_cores_effective
+            .load(Ordering::Relaxed) as usize)
+            .max(1);
+        for (dc, endpoints) in endpoints_by_dc {
+            let endpoint_count = endpoints.len();
+            let dc_available_endpoints = endpoints
+                .iter()
+                .filter(|endpoint| live_writers_by_dc_endpoint.contains_key(&(dc, **endpoint)))
+                .count();
+            let base_required = self.required_writers_for_dc(endpoint_count);
+            let dc_required_writers =
+                self.required_writers_for_dc_with_floor_mode(endpoint_count, false);
+            let floor_min = if endpoint_count <= 1 {
+                (self
+                    .me_adaptive_floor_min_writers_single_endpoint
+                    .load(Ordering::Relaxed) as usize)
+                    .max(1)
+                    .min(base_required.max(1))
+            } else {
+                (self
+                    .me_adaptive_floor_min_writers_multi_endpoint
+                    .load(Ordering::Relaxed) as usize)
+                    .max(1)
+                    .min(base_required.max(1))
+            };
+            let extra_per_core = if endpoint_count <= 1 {
+                self.me_adaptive_floor_max_extra_writers_single_per_core
+                    .load(Ordering::Relaxed) as usize
+            } else {
+                self.me_adaptive_floor_max_extra_writers_multi_per_core
+                    .load(Ordering::Relaxed) as usize
+            };
+            let floor_max = base_required.saturating_add(adaptive_cpu_cores.saturating_mul(extra_per_core));
+            let floor_capped = matches!(floor_mode, MeFloorMode::Adaptive)
+                && dc_required_writers < base_required;
+            let dc_alive_writers = live_writers_by_dc.get(&dc).copied().unwrap_or(0);
+            let dc_fresh_alive_writers = fresh_writers_by_dc.get(&dc).copied().unwrap_or(0);
+            let dc_load = activity
+                .active_sessions_by_target_dc
+                .get(&dc)
+                .copied()
+                .unwrap_or(0);
+            let dc_rtt_ms = dc_rtt_agg
+                .get(&dc)
+                .and_then(|(sum, count)| (*count > 0).then_some(*sum / (*count as f64)));
+
+            available_endpoints += dc_available_endpoints;
+            alive_writers += dc_alive_writers;
+            fresh_alive_writers += dc_fresh_alive_writers;
+
+            dcs.push(MeApiDcStatusSnapshot {
+                dc,
+                endpoint_writers: endpoints
+                    .iter()
+                    .map(|endpoint| MeApiDcEndpointWriterSnapshot {
+                        endpoint: *endpoint,
+                        active_writers: live_writers_by_dc_endpoint
+                            .get(&(dc, *endpoint))
+                            .copied()
+                            .unwrap_or(0),
+                    })
+                    .collect(),
+                endpoints: endpoints.into_iter().collect(),
+                available_endpoints: dc_available_endpoints,
+                available_pct: ratio_pct(dc_available_endpoints, endpoint_count),
+                required_writers: dc_required_writers,
+                floor_min,
+                floor_target: dc_required_writers,
+                floor_max,
+                floor_capped,
+                alive_writers: dc_alive_writers,
+                coverage_pct: ratio_pct(dc_alive_writers, dc_required_writers),
+                fresh_alive_writers: dc_fresh_alive_writers,
+                fresh_coverage_pct: ratio_pct(dc_fresh_alive_writers, dc_required_writers),
+                rtt_ms: dc_rtt_ms,
+                load: dc_load,
+            });
+        }
+
+        MeApiStatusSnapshot {
+            generated_at_epoch_secs: now_epoch_secs,
+            configured_dc_groups,
+            configured_endpoints,
+            available_endpoints,
+            available_pct: ratio_pct(available_endpoints, configured_endpoints),
+            required_writers,
+            alive_writers,
+            coverage_pct: ratio_pct(alive_writers, required_writers),
+            fresh_alive_writers,
+            fresh_coverage_pct: ratio_pct(fresh_alive_writers, required_writers),
+            writers: writer_rows,
+            dcs,
+        }
+    }
+
+    pub(crate) async fn api_runtime_snapshot(&self) -> MeApiRuntimeSnapshot {
+        let now = Instant::now();
+        let now_epoch_secs = Self::now_epoch_secs();
+        let pending_started_at = self
+            .pending_hardswap_started_at_epoch_secs
+            .load(Ordering::Relaxed);
+        let pending_hardswap_age_secs = (pending_started_at > 0)
+            .then_some(now_epoch_secs.saturating_sub(pending_started_at));
+
+        let mut quarantined_endpoints = Vec::<MeApiQuarantinedEndpointSnapshot>::new();
+        {
+            let guard = self.endpoint_quarantine.lock().await;
+            for (endpoint, expires_at) in guard.iter() {
+                if *expires_at <= now {
+                    continue;
+                }
+                let remaining_ms = expires_at.duration_since(now).as_millis() as u64;
+                quarantined_endpoints.push(MeApiQuarantinedEndpointSnapshot {
+                    endpoint: *endpoint,
+                    remaining_ms,
+                });
+            }
+        }
+        quarantined_endpoints.sort_by_key(|entry| entry.endpoint);
+
+        let mut network_path = Vec::<MeApiDcPathSnapshot>::new();
+        if let Some(upstream) = &self.upstream {
+            for dc in 1..=5 {
+                let dc_idx = dc as i16;
+                let ip_preference = upstream
+                    .get_dc_ip_preference(dc_idx)
+                    .await
+                    .map(ip_preference_label);
+                let selected_addr_v4 = upstream.get_dc_addr(dc_idx, false).await;
+                let selected_addr_v6 = upstream.get_dc_addr(dc_idx, true).await;
+                network_path.push(MeApiDcPathSnapshot {
+                    dc: dc_idx,
+                    ip_preference,
+                    selected_addr_v4,
+                    selected_addr_v6,
+                });
+            }
+        }
+
+        MeApiRuntimeSnapshot {
+            active_generation: self.active_generation.load(Ordering::Relaxed),
+            warm_generation: self.warm_generation.load(Ordering::Relaxed),
+            pending_hardswap_generation: self.pending_hardswap_generation.load(Ordering::Relaxed),
+            pending_hardswap_age_secs,
+            hardswap_enabled: self.hardswap.load(Ordering::Relaxed),
+            floor_mode: floor_mode_label(self.floor_mode()),
+            adaptive_floor_idle_secs: self.me_adaptive_floor_idle_secs.load(Ordering::Relaxed),
+            adaptive_floor_min_writers_single_endpoint: self
+                .me_adaptive_floor_min_writers_single_endpoint
+                .load(Ordering::Relaxed),
+            adaptive_floor_min_writers_multi_endpoint: self
+                .me_adaptive_floor_min_writers_multi_endpoint
+                .load(Ordering::Relaxed),
+            adaptive_floor_recover_grace_secs: self
+                .me_adaptive_floor_recover_grace_secs
+                .load(Ordering::Relaxed),
+            adaptive_floor_writers_per_core_total: self
+                .me_adaptive_floor_writers_per_core_total
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_cpu_cores_override: self
+                .me_adaptive_floor_cpu_cores_override
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_max_extra_writers_single_per_core: self
+                .me_adaptive_floor_max_extra_writers_single_per_core
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_max_extra_writers_multi_per_core: self
+                .me_adaptive_floor_max_extra_writers_multi_per_core
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_max_active_writers_per_core: self
+                .me_adaptive_floor_max_active_writers_per_core
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_max_warm_writers_per_core: self
+                .me_adaptive_floor_max_warm_writers_per_core
+                .load(Ordering::Relaxed) as u16,
+            adaptive_floor_max_active_writers_global: self
+                .me_adaptive_floor_max_active_writers_global
+                .load(Ordering::Relaxed),
+            adaptive_floor_max_warm_writers_global: self
+                .me_adaptive_floor_max_warm_writers_global
+                .load(Ordering::Relaxed),
+            adaptive_floor_cpu_cores_detected: self
+                .me_adaptive_floor_cpu_cores_detected
+                .load(Ordering::Relaxed),
+            adaptive_floor_cpu_cores_effective: self
+                .me_adaptive_floor_cpu_cores_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_global_cap_raw: self
+                .me_adaptive_floor_global_cap_raw
+                .load(Ordering::Relaxed),
+            adaptive_floor_global_cap_effective: self
+                .me_adaptive_floor_global_cap_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_target_writers_total: self
+                .me_adaptive_floor_target_writers_total
+                .load(Ordering::Relaxed),
+            adaptive_floor_active_cap_configured: self
+                .me_adaptive_floor_active_cap_configured
+                .load(Ordering::Relaxed),
+            adaptive_floor_active_cap_effective: self
+                .me_adaptive_floor_active_cap_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_warm_cap_configured: self
+                .me_adaptive_floor_warm_cap_configured
+                .load(Ordering::Relaxed),
+            adaptive_floor_warm_cap_effective: self
+                .me_adaptive_floor_warm_cap_effective
+                .load(Ordering::Relaxed),
+            adaptive_floor_active_writers_current: self
+                .me_adaptive_floor_active_writers_current
+                .load(Ordering::Relaxed),
+            adaptive_floor_warm_writers_current: self
+                .me_adaptive_floor_warm_writers_current
+                .load(Ordering::Relaxed),
+            me_keepalive_enabled: self.me_keepalive_enabled,
+            me_keepalive_interval_secs: self.me_keepalive_interval.as_secs(),
+            me_keepalive_jitter_secs: self.me_keepalive_jitter.as_secs(),
+            me_keepalive_payload_random: self.me_keepalive_payload_random,
+            rpc_proxy_req_every_secs: self.rpc_proxy_req_every_secs.load(Ordering::Relaxed),
+            me_reconnect_max_concurrent_per_dc: self.me_reconnect_max_concurrent_per_dc,
+            me_reconnect_backoff_base_ms: self.me_reconnect_backoff_base.as_millis() as u64,
+            me_reconnect_backoff_cap_ms: self.me_reconnect_backoff_cap.as_millis() as u64,
+            me_reconnect_fast_retry_count: self.me_reconnect_fast_retry_count,
+            me_pool_drain_ttl_secs: self.me_pool_drain_ttl_secs.load(Ordering::Relaxed),
+            me_pool_force_close_secs: self.me_pool_force_close_secs.load(Ordering::Relaxed),
+            me_pool_min_fresh_ratio: Self::permille_to_ratio(
+                self.me_pool_min_fresh_ratio_permille.load(Ordering::Relaxed),
+            ),
+            me_bind_stale_mode: bind_stale_mode_label(self.bind_stale_mode()),
+            me_bind_stale_ttl_secs: self.me_bind_stale_ttl_secs.load(Ordering::Relaxed),
+            me_single_endpoint_shadow_writers: self
+                .me_single_endpoint_shadow_writers
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_mode_enabled: self
+                .me_single_endpoint_outage_mode_enabled
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_disable_quarantine: self
+                .me_single_endpoint_outage_disable_quarantine
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_backoff_min_ms: self
+                .me_single_endpoint_outage_backoff_min_ms
+                .load(Ordering::Relaxed),
+            me_single_endpoint_outage_backoff_max_ms: self
+                .me_single_endpoint_outage_backoff_max_ms
+                .load(Ordering::Relaxed),
+            me_single_endpoint_shadow_rotate_every_secs: self
+                .me_single_endpoint_shadow_rotate_every_secs
+                .load(Ordering::Relaxed),
+            me_deterministic_writer_sort: self
+                .me_deterministic_writer_sort
+                .load(Ordering::Relaxed),
+            me_writer_pick_mode: writer_pick_mode_label(self.writer_pick_mode()),
+            me_writer_pick_sample_size: self.writer_pick_sample_size() as u8,
+            me_socks_kdf_policy: socks_kdf_policy_label(self.socks_kdf_policy()),
+            quarantined_endpoints,
+            network_path,
+        }
+    }
+}
+
+fn ratio_pct(part: usize, total: usize) -> f64 {
+    if total == 0 {
+        return 0.0;
+    }
+    let pct = ((part as f64) / (total as f64)) * 100.0;
+    pct.clamp(0.0, 100.0)
+}
+
+fn extend_signed_endpoints(
+    endpoints_by_dc: &mut BTreeMap<i16, BTreeSet<SocketAddr>>,
+    map: HashMap<i32, Vec<(IpAddr, u16)>>,
+) {
+    for (dc, addrs) in map {
+        if dc == 0 {
+            continue;
+        }
+        let Ok(dc_idx) = i16::try_from(dc) else {
+            continue;
+        };
+        let entry = endpoints_by_dc.entry(dc_idx).or_default();
+        for (ip, port) in addrs {
+            entry.insert(SocketAddr::new(ip, port));
+        }
+    }
+}
+
+fn floor_mode_label(mode: MeFloorMode) -> &'static str {
+    match mode {
+        MeFloorMode::Static => "static",
+        MeFloorMode::Adaptive => "adaptive",
+    }
+}
+
+fn bind_stale_mode_label(mode: MeBindStaleMode) -> &'static str {
+    match mode {
+        MeBindStaleMode::Never => "never",
+        MeBindStaleMode::Ttl => "ttl",
+        MeBindStaleMode::Always => "always",
+    }
+}
+
+fn writer_pick_mode_label(mode: crate::config::MeWriterPickMode) -> &'static str {
+    match mode {
+        crate::config::MeWriterPickMode::SortedRr => "sorted_rr",
+        crate::config::MeWriterPickMode::P2c => "p2c",
+    }
+}
+
+fn socks_kdf_policy_label(policy: MeSocksKdfPolicy) -> &'static str {
+    match policy {
+        MeSocksKdfPolicy::Strict => "strict",
+        MeSocksKdfPolicy::Compat => "compat",
+    }
+}
+
+fn ip_preference_label(preference: IpPreference) -> &'static str {
+    match preference {
+        IpPreference::Unknown => "unknown",
+        IpPreference::PreferV6 => "prefer_v6",
+        IpPreference::PreferV4 => "prefer_v4",
+        IpPreference::BothWork => "both",
+        IpPreference::Unavailable => "unavailable",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::ratio_pct;
+
+    #[test]
+    fn ratio_pct_is_zero_when_denominator_is_zero() {
+        assert_eq!(ratio_pct(1, 0), 0.0);
+    }
+
+    #[test]
+    fn ratio_pct_is_capped_at_100() {
+        assert_eq!(ratio_pct(7, 3), 100.0);
+    }
+
+    #[test]
+    fn ratio_pct_reports_expected_value() {
+        assert_eq!(ratio_pct(1, 4), 25.0);
+    }
+}