Merge pull request #479 from telemt/bump

Update Cargo.toml

.github/codeql/codeql-config.yml

@@ -0,0 +1,19 @@
+name: "Rust without tests"
+
+disable-default-queries: false
+
+queries:
+  - uses: security-extended
+  - uses: security-and-quality
+  - uses: ./.github/codeql/queries
+
+query-filters:
+  - exclude:
+      id:
+        - rust/unwrap-on-option
+        - rust/unwrap-on-result
+        - rust/expect-used
+
+analysis:
+  dataflow:
+    default-precision: high

.github/codeql/queries/common/ProductionOnly.qll

@@ -0,0 +1,20 @@
+import rust
+
+predicate isTestOnly(Item i) {
+  exists(ConditionalCompilation cc |
+    cc.getItem() = i and
+    cc.getCfg().toString() = "test"
+  )
+}
+
+predicate hasTestAttribute(Item i) {
+  exists(Attribute a |
+    a.getItem() = i and
+    a.getName() = "test"
+  )
+}
+
+predicate isProductionCode(Item i) {
+  not isTestOnly(i) and
+  not hasTestAttribute(i)
+}

.github/codeql/queries/qlpack.yml

@@ -0,0 +1,4 @@
+name: rust-production-only
+version: 0.0.1
+dependencies:
+  codeql/rust-all: "*"

.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.**

.github/workflows/codeql.yml

@@ -0,0 +1,45 @@
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "*" ]
+  pull_request:
+    branches: [ "*" ]
+  schedule:
+    - cron: '0 0 * * 0'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: rust
+            build-mode: none
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          config-file: .github/codeql/codeql-config.yml
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/release.yml

@@ -0,0 +1,139 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    name: Build ${{ matrix.target }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            artifact_name: telemt
+            asset_name: telemt-x86_64-linux-gnu
+          - target: aarch64-unknown-linux-gnu
+            artifact_name: telemt
+            asset_name: telemt-aarch64-linux-gnu
+          - target: x86_64-unknown-linux-musl
+            artifact_name: telemt
+            asset_name: telemt-x86_64-linux-musl
+          - target: aarch64-unknown-linux-musl
+            artifact_name: telemt
+            asset_name: telemt-aarch64-linux-musl
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@v1
+        with:
+          toolchain: stable
+          targets: ${{ matrix.target }}
+
+      - name: Install cross-compilation tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu
+
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-${{ matrix.target }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ matrix.target }}-cargo-
+
+      - name: Install cross
+        run: cargo install cross --git https://github.com/cross-rs/cross
+
+      - name: Build Release
+        env:
+          RUSTFLAGS: ${{ contains(matrix.target, 'musl') && '-C target-feature=+crt-static' || '' }}
+        run: cross build --release --target ${{ matrix.target }}
+
+      - name: Package binary
+        run: |
+          cd target/${{ matrix.target }}/release
+          tar -czvf ${{ matrix.asset_name }}.tar.gz ${{ matrix.artifact_name }}
+          sha256sum ${{ matrix.asset_name }}.tar.gz > ${{ matrix.asset_name }}.sha256
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.asset_name }}
+          path: |
+            target/${{ matrix.target }}/release/${{ matrix.asset_name }}.tar.gz
+            target/${{ matrix.target }}/release/${{ matrix.asset_name }}.sha256
+
+  build-docker-image:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version
+        id: vars
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:${{ steps.vars.outputs.VERSION }}
+            ghcr.io/${{ github.repository }}:latest
+
+  release:
+    name: Create Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/**/*
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref, '-rc') || contains(github.ref, '-beta') || contains(github.ref, '-alpha') }}

.github/workflows/rust.yml

@@ -2,18 +2,23 @@ name: Rust
 
 on:
   push:
-    branches: [ main ]
+    branches: [ "*" ]
   pull_request:
-    branches: [ main ]
+    branches: [ "*" ]
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  build-and-test:
-    name: Build & Test
+  build:
+    name: Build
     runs-on: ubuntu-latest
 
+    permissions:
+      contents: read
+      actions: write
+      checks: write
+
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
@@ -37,5 +42,13 @@ jobs:
     - name: Build Release
       run: cargo build --release --verbose
 
+    - name: Run tests
+      run: cargo test --verbose
+
+# clippy dont fail on warnings because of active development of telemt 
+# and many warnings
+    - name: Run clippy
+      run: cargo clippy -- --cap-lints warn
+
     - name: Check for unused dependencies
       run: cargo udeps || true

.gitignore

@@ -19,3 +19,5 @@ target
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+proxy-secret

.kilocode/rules-architect/AGENTS.md

@@ -0,0 +1,58 @@
+# Architect Mode Rules for Telemt
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph Entry
+        Client[Clients] --> Listener[TCP/Unix Listener]
+    end
+    
+    subgraph Proxy Layer
+        Listener --> ClientHandler[ClientHandler]
+        ClientHandler --> Handshake[Handshake Validator]
+        Handshake --> |Valid| Relay[Relay Layer]
+        Handshake --> |Invalid| Masking[Masking/TLS Fronting]
+    end
+    
+    subgraph Transport
+        Relay --> MiddleProxy[Middle-End Proxy Pool]
+        Relay --> DirectRelay[Direct DC Relay]
+        MiddleProxy --> TelegramDC[Telegram DCs]
+        DirectRelay --> TelegramDC
+    end
+```
+
+## Module Dependencies
+- [`src/main.rs`](src/main.rs) - Entry point, spawns all async tasks
+- [`src/config/`](src/config/) - Configuration loading with auto-migration
+- [`src/error.rs`](src/error.rs) - Error types, must be used by all modules
+- [`src/crypto/`](src/crypto/) - AES, SHA, random number generation
+- [`src/protocol/`](src/protocol/) - MTProto constants, frame encoding, obfuscation
+- [`src/stream/`](src/stream/) - Stream wrappers, buffer pool, frame codecs
+- [`src/proxy/`](src/proxy/) - Client handling, handshake, relay logic
+- [`src/transport/`](src/transport/) - Upstream management, middle-proxy, SOCKS support
+- [`src/stats/`](src/stats/) - Statistics and replay protection
+- [`src/ip_tracker.rs`](src/ip_tracker.rs) - Per-user IP tracking
+
+## Key Architectural Constraints
+
+### Middle-End Proxy Mode
+- Requires public IP on interface OR 1:1 NAT with STUN probing
+- Uses separate `proxy-secret` from Telegram (NOT user secrets)
+- Falls back to direct mode automatically on STUN mismatch
+
+### TLS Fronting
+- Invalid handshakes are transparently proxied to `mask_host`
+- This is critical for DPI evasion - do not change this behavior
+- `mask_unix_sock` and `mask_host` are mutually exclusive
+
+### Stream Architecture
+- Buffer pool is shared globally via Arc - prevents allocation storms
+- Frame codecs implement tokio-util Encoder/Decoder traits
+- State machine in [`src/stream/state.rs`](src/stream/state.rs) manages stream transitions
+
+### Configuration Migration
+- [`ProxyConfig::load()`](src/config/mod.rs:641) mutates config in-place
+- New fields must have sensible defaults
+- DC203 override is auto-injected for CDN/media support

.kilocode/rules-code/AGENTS.md

@@ -0,0 +1,23 @@
+# Code Mode Rules for Telemt
+
+## Error Handling
+- Always use [`ProxyError`](src/error.rs:168) from [`src/error.rs`](src/error.rs) for proxy operations
+- [`HandshakeResult<T,R,W>`](src/error.rs:292) returns streams on bad client - these MUST be returned for masking, never dropped
+- Use [`Recoverable`](src/error.rs:110) trait to check if errors are retryable
+
+## Configuration Changes
+- [`ProxyConfig::load()`](src/config/mod.rs:641) auto-mutates config - new fields should have defaults
+- DC203 override is auto-injected if missing - do not remove this behavior
+- When adding config fields, add migration logic in [`ProxyConfig::load()`](src/config/mod.rs:641)
+
+## Crypto Code
+- [`SecureRandom`](src/crypto/random.rs) from [`src/crypto/random.rs`](src/crypto/random.rs) must be used for all crypto operations
+- Never use `rand::thread_rng()` directly - use the shared `Arc<SecureRandom>`
+
+## Stream Handling
+- Buffer pool [`BufferPool`](src/stream/buffer_pool.rs) is shared via Arc - always use it instead of allocating
+- Frame codecs in [`src/stream/frame_codec.rs`](src/stream/frame_codec.rs) implement tokio-util's Encoder/Decoder traits
+
+## Testing
+- Tests are inline in modules using `#[cfg(test)]`
+- Use `cargo test --lib <module_name>` to run tests for specific modules

.kilocode/rules-debug/AGENTS.md

@@ -0,0 +1,27 @@
+# Debug Mode Rules for Telemt
+
+## Logging
+- `RUST_LOG` environment variable takes absolute priority over all config log levels
+- Log levels: `trace`, `debug`, `info`, `warn`, `error`
+- Use `RUST_LOG=debug cargo run` for detailed operational logs
+- Use `RUST_LOG=trace cargo run` for full protocol-level debugging
+
+## Middle-End Proxy Debugging
+- Set `ME_DIAG=1` environment variable for high-precision cryptography diagnostics
+- STUN probe results are logged at startup - check for mismatch between local and reflected IP
+- If Middle-End fails, check `proxy_secret_path` points to valid file from https://core.telegram.org/getProxySecret
+
+## Connection Issues
+- DC connectivity is logged at startup with RTT measurements
+- If DC ping fails, check `dc_overrides` for custom addresses
+- Use `prefer_ipv6=false` in config if IPv6 is unreliable
+
+## TLS Fronting Issues
+- Invalid handshakes are proxied to `mask_host` - check this host is reachable
+- `mask_unix_sock` and `mask_host` are mutually exclusive - only one can be set
+- If `mask_unix_sock` is set, socket must exist before connections arrive
+
+## Common Errors
+- `ReplayAttack` - client replayed a handshake nonce, potential attack
+- `TimeSkew` - client clock is off, can disable with `ignore_time_skew=true`
+- `TgHandshakeTimeout` - upstream DC connection failed, check network

AGENTS.md

@@ -0,0 +1,410 @@
+## System Prompt — Production Rust Codebase: Modification and Architecture Guidelines
+
+You are a senior Rust Engineer and pricipal Rust Architect acting as a strict code reviewer and implementation partner. 
+Your responses are precise, minimal, and architecturally sound. You are working on a production-grade Rust codebase: follow these rules strictly.
+
+---
+
+### 0. Priority Resolution — Scope Control
+
+This section resolves conflicts between code quality enforcement and scope limitation.
+
+When editing or extending existing code, you MUST audit the affected files and fix:
+
+- Comment style violations (missing, non-English, decorative, trailing).
+- Missing or incorrect documentation on public items.
+- Comment placement issues (trailing comments → move above the code).
+
+These are **coordinated changes** — they are always in scope.
+
+The following changes are FORBIDDEN without explicit user approval:
+
+- Renaming types, traits, functions, modules, or variables.
+- Altering business logic, control flow, or data transformations.
+- Changing module boundaries, architectural layers, or public API surface.
+- Adding or removing functions, structs, enums, or trait implementations.
+- Fixing compiler warnings or removing unused code.
+
+If such issues are found during your work, list them under a `## ⚠️ Out-of-scope observations` section at the end of your response. Include file path, context, and a brief description. Do not apply these changes.
+
+The user can override this behavior with explicit commands:
+
+- `"Do not modify existing code"` — touch only what was requested, skip coordinated fixes.
+- `"Make minimal changes"` — no coordinated fixes, narrowest possible diff.
+- `"Fix everything"` — apply all coordinated fixes and out-of-scope observations.
+
+### Core Rule
+
+The codebase must never enter an invalid intermediate state.
+No response may leave the repository in a condition that requires follow-up fixes.
+
+---
+
+### 1. Comments and Documentation
+
+- All comments MUST be written in English.
+- Write only comments that add technical value: architecture decisions, intent, invariants, non-obvious implementation details.
+- Place all comments on separate lines above the relevant code.
+- Use `///` doc-comments for public items. Use `//` for internal clarifications.
+
+Correct example:
+
+```rust
+// Handles MTProto client authentication and establishes encrypted session state.
+fn handle_authenticated_client(...) { ... }
+```
+
+Incorrect examples:
+
+```rust
+let x = 5; // set x to 5
+```
+
+```rust
+// This function does stuff
+fn do_stuff() { ... }
+```
+
+---
+
+### 2. File Size and Module Structure
+
+- Files MUST NOT exceed 350–550 lines.
+- If a file exceeds this limit, split it into submodules organized by responsibility (e.g., protocol, transport, state, handlers).
+- Parent modules MUST declare and describe their submodules.
+- Maintain clear architectural boundaries between modules.
+
+Correct example:
+
+```rust
+// Client connection handling logic.
+// Submodules:
+// - handshake: MTProto handshake implementation
+// - relay: traffic forwarding logic
+// - state: client session state machine
+
+pub mod handshake;
+pub mod relay;
+pub mod state;
+```
+
+Git discipline:
+
+- Use local git for versioning and diffs.
+- Write clear, descriptive commit messages in English that explain both *what* changed and *why*.
+
+---
+
+### 3. Formatting
+
+- Preserve the existing formatting style of the project exactly as-is.
+- Reformat code only when explicitly instructed to do so.
+- Do not run `cargo fmt` unless explicitly instructed.
+
+---
+
+### 4. Change Safety and Validation
+
+- If anything is unclear, STOP and ask specific, targeted questions before proceeding.
+- List exactly what is ambiguous and offer possible interpretations for the user to choose from.
+- Prefer clarification over assumptions. Do not guess intent, behavior, or missing requirements.
+- Actively ask questions before making architectural or behavioral changes.
+
+---
+
+### 5. Warnings and Unused Code
+
+- Leave all warnings, unused variables, functions, imports, and dead code untouched unless explicitly instructed to modify them.
+- These may be intentional or part of work-in-progress code.
+- `todo!()` and `unimplemented!()` are permitted and should not be removed or replaced unless explicitly instructed.
+
+---
+
+### 6. Architectural Integrity
+
+- Preserve existing architecture unless explicitly instructed to refactor.
+- Do not introduce hidden behavioral changes.
+- Do not introduce implicit refactors.
+- Keep changes minimal, isolated, and intentional.
+
+---
+
+### 7. When Modifying Code
+
+You MUST:
+
+- Maintain architectural consistency with the existing codebase.
+- Document non-obvious logic with comments that describe *why*, not *what*.
+- Limit changes strictly to the requested scope (plus coordinated fixes per Section 0).
+- Keep all existing symbol names unless renaming is explicitly requested.
+- Preserve global formatting as-is
+- Result every modification in a self-contained, compilable, runnable state of the codebase
+
+You MUST NOT:
+
+- Use placeholders: no `// ... rest of code`, no `// implement here`, no `/* TODO */` stubs that replace existing working code. Write full, working implementation. If the implementation is unclear, ask first
+- Refactor code outside the requested scope
+- Make speculative improvements
+- Spawn multiple agents for EDITING
+- Produce partial changes
+- Introduce references to entities that are not yet implemented
+- Leave TODO placeholders in production paths
+
+Note: `todo!()` and `unimplemented!()` are allowed as idiomatic Rust markers for genuinely unfinished code paths.
+
+Every change must:
+   - compile,
+   - pass type checks,
+   - have no broken imports,
+   - preserve invariants,
+   - not rely on future patches.
+
+If the task requires multiple phases:
+   - either implement all required phases,
+   - or explicitly refuse and explain missing dependencies.
+
+---
+
+### 8. Decision Process for Complex Changes
+
+When facing a non-trivial modification, follow this sequence:
+
+1. **Clarify**: Restate the task in one sentence to confirm understanding.
+2. **Assess impact**: Identify which modules, types, and invariants are affected.
+3. **Propose**: Describe the intended change before implementing it.
+4. **Implement**: Make the minimal, isolated change.
+5. **Verify**: Explain why the change preserves existing behavior and architectural integrity.
+
+---
+
+### 9. Context Awareness
+
+- When provided with partial code, assume the rest of the codebase exists and functions correctly unless stated otherwise.
+- Reference existing types, functions, and module structures by their actual names as shown in the provided code.
+- When the provided context is insufficient to make a safe change, request the missing context explicitly.
+- Spawn multiple agents for SEARCHING information, code, functions
+
+---
+
+### 10. Response Format
+
+#### Language Policy
+
+- Code, comments, commit messages, documentation ONLY ON **English**!
+- Reasoning and explanations in response text on language from promt
+
+#### Response Structure
+
+Your response MUST consist of two sections:
+
+**Section 1: `## Reasoning`**
+
+- What needs to be done and why.
+- Which files and modules are affected.
+- Architectural decisions and their rationale.
+- Potential risks or side effects.
+
+**Section 2: `## Changes`**
+
+- For each modified or created file: the filename on a separate line in backticks, followed by the code block.
+- For files **under 200 lines**: return the full file with all changes applied.
+- For files **over 200 lines**: return only the changed functions/blocks with at least 3 lines of surrounding context above and below. If the user requests the full file, provide it.
+- New files: full file content.
+- End with a suggested git commit message in English.
+
+#### Reporting Out-of-Scope Issues
+
+If during modification you discover issues outside the requested scope (potential bugs, unsafe code, architectural concerns, missing error handling, unused imports, dead code):
+
+- Do not fix them silently.
+- List them under `## ⚠️ Out-of-scope observations` at the end of your response.
+- Include: file path, line/function context, brief description of the issue, and severity estimate.
+
+#### Splitting Protocol
+
+If the response exceeds the output limit:
+
+1. End the current part with: **SPLIT: PART N — CONTINUE? (remaining: file_list)**
+2. List the files that will be provided in subsequent parts.
+3. Wait for user confirmation before continuing.
+4. No single file may be split across parts.
+
+## 11. Anti-LLM Degeneration Safeguards (Principal-Paranoid, Visionary)
+
+This section exists to prevent common LLM failure modes: scope creep, semantic drift, cargo-cult refactors, performance regressions, contract breakage, and hidden behavior changes.
+
+### 11.1 Non-Negotiable Invariants
+
+- **No semantic drift:** Do not reinterpret requirements, rename concepts, or change meaning of existing terms.
+- **No “helpful refactors”:** Any refactor not explicitly requested is forbidden.
+- **No architectural drift:** Do not introduce new layers, patterns, abstractions, or “clean architecture” migrations unless requested.
+- **No dependency drift:** Do not add crates, features, or versions unless explicitly requested.
+- **No behavior drift:** If a change could alter runtime behavior, you MUST call it out explicitly in `## Reasoning` and justify it.
+
+### 11.2 Minimal Surface Area Rule
+
+- Touch the smallest number of files possible.
+- Prefer local changes over cross-cutting edits.
+- Do not “align style” across a file/module—only adjust the modified region.
+- Do not reorder items, imports, or code unless required for correctness.
+
+### 11.3 No Implicit Contract Changes
+
+Contracts include:
+- public APIs, trait bounds, visibility, error types, timeouts/retries, logging semantics, metrics semantics,
+- protocol formats, framing, padding, keepalive cadence, state machine transitions,
+- concurrency guarantees, cancellation behavior, backpressure behavior.
+
+Rule:
+- If you change a contract, you MUST update all dependents in the same patch AND document the contract delta explicitly.
+
+### 11.4 Hot-Path Preservation (Performance Paranoia)
+
+- Do not introduce extra allocations, cloning, or formatting in hot paths.
+- Do not add logging/metrics on hot paths unless requested.
+- Do not add new locks or broaden lock scope.
+- Prefer `&str` / slices / borrowed data where the codebase already does so.
+- Avoid `String` building for errors/logs if it changes current patterns.
+
+If you cannot prove performance neutrality, label it as risk in `## Reasoning`.
+
+### 11.5 Async / Concurrency Safety (Cancellation & Backpressure)
+
+- No blocking calls inside async contexts.
+- Preserve cancellation safety: do not introduce `await` between lock acquisition and critical invariants unless already present.
+- Preserve backpressure: do not replace bounded channels with unbounded, do not remove flow control.
+- Do not change task lifecycle semantics (spawn patterns, join handles, shutdown order) unless requested.
+- Do not introduce `tokio::spawn` / background tasks unless explicitly requested.
+
+### 11.6 Error Semantics Integrity
+
+- Do not replace structured errors with generic strings.
+- Do not widen/narrow error types or change error categories without explicit approval.
+- Avoid introducing panics in production paths (`unwrap`, `expect`) unless the codebase already treats that path as impossible and documented.
+
+### 11.7 “No New Abstractions” Default
+
+Default stance:
+- No new traits, generics, macros, builder patterns, type-level cleverness, or “frameworking”.
+- If abstraction is necessary, prefer the smallest possible local helper (private function) and justify it.
+
+### 11.8 Negative-Diff Protection
+
+Avoid “diff inflation” patterns:
+- mass edits,
+- moving code between files,
+- rewrapping long lines,
+- rearranging module order,
+- renaming for aesthetics.
+
+If a diff becomes large, STOP and ask before proceeding.
+
+### 11.9 Consistency with Existing Style (But Not Style Refactors)
+
+- Follow existing conventions of the touched module (naming, error style, return patterns).
+- Do not enforce global “best practices” that the codebase does not already use.
+
+### 11.10 Two-Phase Safety Gate (Plan → Patch)
+
+For non-trivial changes:
+1) Provide a micro-plan (1–5 bullets): what files, what functions, what invariants, what risks.
+2) Implement exactly that plan—no extra improvements.
+
+### 11.11 Pre-Response Checklist (Hard Gate)
+
+Before final output, verify internally:
+
+- No unresolved symbols / broken imports.
+- No partially updated call sites.
+- No new public surface changes unless requested.
+- No transitional states / TODO placeholders replacing working code.
+- Changes are atomic: the repository remains buildable and runnable.
+- Any behavior change is explicitly stated.
+
+If any check fails: fix it before responding.
+
+### 11.12 Truthfulness Policy (No Hallucinated Claims)
+
+- Do not claim “this compiles” or “tests pass” unless you actually verified with the available tooling/context.
+- If verification is not possible, state: “Not executed; reasoning-based consistency check only.”
+
+### 11.13 Visionary Guardrail: Preserve Optionality
+
+When multiple valid designs exist, prefer the one that:
+- minimally constrains future evolution,
+- preserves existing extension points,
+- avoids locking the project into a new paradigm,
+- keeps interfaces stable and implementation local.
+
+Default to reversible changes.
+
+### 11.14 Stop Conditions
+
+STOP and ask targeted questions if:
+- required context is missing,
+- a change would cross module boundaries,
+- a contract might change,
+- concurrency/protocol invariants are unclear,
+- the diff is growing beyond a minimal patch.
+
+No guessing.
+
+### 12. Invariant Preservation
+
+You MUST explicitly preserve:
+- Thread-safety guarantees (`Send` / `Sync` expectations).
+- Memory safety assumptions (no hidden `unsafe` expansions).
+- Lock ordering and deadlock invariants.
+- State machine correctness (no new invalid transitions).
+- Backward compatibility of serialized formats (if applicable).
+
+If a change touches concurrency, networking, protocol logic, or state machines,
+you MUST explain why existing invariants remain valid.
+
+### 13. Error Handling Policy
+
+- Do not replace structured errors with generic strings.
+- Preserve existing error propagation semantics.
+- Do not widen or narrow error types without approval.
+- Avoid introducing panics in production paths.
+- Prefer explicit error mapping over implicit conversions.
+
+### 14. Test Safety
+
+- Do not modify existing tests unless the task explicitly requires it.
+- Do not weaken assertions.
+- Preserve determinism in testable components.
+
+### 15. Security Constraints
+
+- Do not weaken cryptographic assumptions.
+- Do not modify key derivation logic without explicit request.
+- Do not change constant-time behavior.
+- Do not introduce logging of secrets.
+- Preserve TLS/MTProto protocol correctness.
+
+### 16. Logging Policy
+
+- Do not introduce excessive logging in hot paths.
+- Do not log sensitive data.
+- Preserve existing log levels and style.
+
+### 17. Pre-Response Verification Checklist
+
+Before producing the final answer, verify internally:
+
+- The change compiles conceptually.
+- No unresolved symbols exist.
+- All modified call sites are updated.
+- No accidental behavioral changes were introduced.
+- Architectural boundaries remain intact.
+
+### 18. Atomic Change Principle
+Every patch must be **atomic and production-safe**.
+* **Self-contained** — no dependency on future patches or unimplemented components.
+* **Build-safe** — the project must compile successfully after the change.
+* **Contract-consistent** — no partial interface or behavioral changes; all dependent code must be updated within the same patch.
+* **No transitional states** — no placeholders, incomplete refactors, or temporary inconsistencies.
+
+**Invariant:** After any single patch, the repository remains fully functional and buildable.
+

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Issues - Rules
+## What it is not
+- NOT Question and Answer
+- NOT Helpdesk
+
+# Pull Requests - Rules
+## General
+- ONLY signed and verified commits
+- ONLY from your name
+- DO NOT commit with `codex` or `claude` as author/commiter
+- PREFER `flow` branch for development, not `main`
+
+## AI
+We are not against modern tools, like AI, where you act as a principal or architect, but we consider it important:
+
+- you really understand what you're doing
+- you understand the relationships and dependencies of the components being modified
+- you understand the architecture of Telegram MTProto, MTProxy, Middle-End KDF at least generically
+- you DO NOT commit for the sake of commits, but to help the community, core-developers and ordinary users

Cargo.toml

@@ -1,16 +1,15 @@
 [package]
 name = "telemt"
-version = "1.0.0"
-edition = "2021"
-rust-version = "1.75"
+version = "3.3.21"
+edition = "2024"
 
 [dependencies]
 # C
 libc = "0.2"
 
 # Async runtime
-tokio = { version = "1.35", features = ["full", "tracing"] }
-tokio-util = { version = "0.7", features = ["codec"] }
+tokio = { version = "1.42", features = ["full", "tracing"] }
+tokio-util = { version = "0.7", features = ["full"] }
 
 # Crypto
 aes = "0.8"
@@ -20,42 +19,60 @@ sha2 = "0.10"
 sha1 = "0.10"
 md-5 = "0.10"
 hmac = "0.12"
-crc32fast = "1.3"
+crc32fast = "1.4"
+crc32c = "0.6"
+zeroize = { version = "1.8", features = ["derive"] }
 
 # Network
 socket2 = { version = "0.5", features = ["all"] }
-rustls = "0.22"
+nix = { version = "0.28", default-features = false, features = ["net"] }
 
-# Serial
+# Serialization
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 toml = "0.8"
+x509-parser = "0.15"
 
 # Utils
-bytes = "1.5"
-thiserror = "1.0"
+bytes = "1.9"
+thiserror = "2.0"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 parking_lot = "0.12"
 dashmap = "5.5"
-lru = "0.12"
-rand = "0.8"
+lru = "0.16"
+rand = "0.9"
 chrono = { version = "0.4", features = ["serde"] }
 hex = "0.4"
-base64 = "0.21"
+base64 = "0.22"
 url = "2.5"
-regex = "1.10"
-once_cell = "1.19"
+regex = "1.11"
 crossbeam-queue = "0.3"
+num-bigint = "0.4"
+num-traits = "0.2"
+anyhow = "1.0"
 
 # HTTP
-reqwest = { version = "0.11", features = ["rustls-tls"], default-features = false }
+reqwest = { version = "0.12", features = ["rustls-tls"], default-features = false }
+notify = { version = "6", features = ["macos_fsevent"] }
+ipnetwork = "0.20"
+hyper = { version = "1", features = ["server", "http1"] }
+hyper-util = { version = "0.1", features = ["tokio", "server-auto"] }
+http-body-util = "0.1"
+httpdate = "1.0"
+tokio-rustls = { version = "0.26", default-features = false, features = ["tls12"] }
+rustls = { version = "0.23", default-features = false, features = ["std", "tls12", "ring"] }
+webpki-roots = "0.26"
 
 [dev-dependencies]
 tokio-test = "0.4"
 criterion = "0.5"
 proptest = "1.4"
+futures = "0.3"
 
 [[bench]]
 name = "crypto_bench"
-harness = false
+harness = false
+
+[profile.release]
+lto = "thin"

Dockerfile

@@ -0,0 +1,43 @@
+# ==========================
+# Stage 1: Build
+# ==========================
+FROM rust:1.88-slim-bookworm AS builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /build
+
+COPY Cargo.toml Cargo.lock* ./
+RUN mkdir src && echo 'fn main() {}' > src/main.rs && \
+    cargo build --release 2>/dev/null || true && \
+    rm -rf src
+
+COPY . .
+RUN cargo build --release && strip target/release/telemt
+
+# ==========================
+# Stage 2: Runtime
+# ==========================
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -r -s /usr/sbin/nologin telemt
+
+WORKDIR /app
+
+COPY --from=builder /build/target/release/telemt /app/telemt
+COPY config.toml /app/config.toml
+
+RUN chown -R telemt:telemt /app
+USER telemt
+
+EXPOSE 443
+EXPOSE 9090
+
+ENTRYPOINT ["/app/telemt"]
+CMD ["config.toml"]

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

@@ -0,0 +1,12 @@
+# LICENSING
+## Licenses for Versions
+| 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 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,28 +1,71 @@
 # 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***
 
-# 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)
-  - [Telegram Calls](#telegram-calls-via-mtproxy)
-  - [DPI](#how-does-dpi-see-mtproxy-tls)
-  - [Whitelist on Network Level](#whitelist-on-ip)
-- [Build](#build)
-- [Why Rust?](#why-rust)
+**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
 
-## Features
+[**Telemt Chat in Telegram**](https://t.me/telemtrs)
+
+## NEWS and EMERGENCY
+### ✈️ Telemt 3 is released!
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🇷🇺 RU
+
+#### Релиз 3.3.15 Semistable
+
+[3.3.15](https://github.com/telemt/telemt/releases/tag/3.3.15) по итогам работы в продакшн признан одним из самых стабильных и рекомендуется к использованию, когда cutting-edge фичи некритичны!
+
+Будем рады вашему фидбеку и предложениям по улучшению — особенно в части **API**, **статистики**, **UX**
+
+---
+
+Если у вас есть компетенции в:
+
+- Асинхронных сетевых приложениях  
+- Анализе трафика  
+- Реверс-инжиниринге  
+- Сетевых расследованиях  
+
+Мы открыты к архитектурным предложениям, идеям и pull requests
+</td>
+<td width="50%" valign="top">
+
+### 🇬🇧 EN
+
+#### Release 3.3.15 Semistable
+
+[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 are looking forward to your feedback and improvement proposals — especially regarding **API**, **statistics**, **UX**
+
+---
+
+If you have expertise in:
+
+- Asynchronous network applications  
+- Traffic analysis  
+- Reverse engineering  
+- Network forensics  
+
+We welcome ideas, architectural feedback, and pull requests.
+</td>
+</tr>
+</table>
+
+# Features
+💥 The configuration structure has changed since version 1.1.0.0. change it in your environment!
+
+⚓ Our implementation of **TLS-fronting** is one of the most deeply debugged, focused, advanced and *almost* **"behaviorally consistent to real"**:  we are confident we have it right - [see evidence on our validation and traces](#recognizability-for-dpi-and-crawler)
+
+⚓ Our ***Middle-End Pool*** is fastest by design in standard scenarios, compared to other implementations of connecting to the Middle-End Proxy: non dramatically, but usual
 
 - Full support for all official MTProto proxy modes:
   - Classic
@@ -34,158 +77,120 @@
 - 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 https://github.com/telemt/telemt/releases/latest/download/telemt
-```
-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
-
-[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
-
-## Configuration
-### Minimal Configuration for First Start
-```toml
-port = 443                              # Listening port
-show_links = ["tele", "hello"]          # Specify users, for whom will be displayed the links
-
-[users]
-tele = "00000000000000000000000000000000" # Replace the secret with one generated before
-hello = "00000000000000000000000000000000" # Replace the secret with one generated before
-
-[modes]
-classic = false                         # Plain obfuscated mode
-secure = false                          # dd-prefix mode
-tls = true                              # Fake TLS - ee-prefix
-
-tls_domain = "petrovich.ru"             # Domain for ee-secret and masking
-mask = true                             # Enable masking of bad traffic
-mask_host = "petrovich.ru"              # Optional override for mask destination
-mask_port = 443                         # Port for masking
-
-prefer_ipv6 = false                     # Try IPv6 DCs first if true
-fast_mode = true                        # Use "fast" obfuscation variant
-
-client_keepalive = 600                  # Seconds
-client_ack_timeout = 300                # Seconds
-```
-### Advanced
-#### Adtag
-To use channel advertising and usage statistics from Telegram, get Adtag from [@mtproxybot](https://t.me/mtproxybot), add this parameter to the end of config.toml and specify it
-```toml
-ad_tag = "00000000000000000000000000000000" # Replace zeros to your adtag from @mtproxybot
-```
-#### Listening and Announce IPs
-To specify listening address and/or address in links, add to the end of config.toml:
-```toml
-[[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 the end 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!
+
+- We consider this a breakthrough aspect, which has no stable analogues today
+- Based on this: if `telemt` configured correctly, **TLS mode is completely identical to real-life handshake + communication** with a specified host
+- Here is our evidence:
+    - 212.220.88.77 - "dummy" host, running `telemt`
+    - `petrovich.ru` - `tls` + `masking` host, in HEX: `706574726f766963682e7275`
+    - **No MITM + No Fake Certificates/Crypto** = pure transparent *TCP Splice* to "best" upstream: MTProxy or tls/mask-host:
+      - DPI see legitimate HTTPS to `tls_host`, including *valid chain-of-trust* and entropy
+      - Crawlers completely satisfied receiving responses from `mask_host`
+  #### Client WITH secret-key accesses the MTProxy resource:
+  
+  <img width="360" height="439" alt="telemt" src="https://github.com/user-attachments/assets/39352afb-4a11-4ecc-9d91-9e8cfb20607d" />
+  
+  #### Client WITHOUT secret-key gets transparent access to the specified resource:
+    - with trusted certificate
+    - with original handshake
+    - with full request-response way
+    - with low-latency overhead
+```bash
+root@debian:~/telemt# curl -v -I --resolve petrovich.ru:443:212.220.88.77 https://petrovich.ru/
+* Added petrovich.ru:443:212.220.88.77 to DNS cache
+* Hostname petrovich.ru was found in DNS cache
+*   Trying 212.220.88.77:443...
+* Connected to petrovich.ru (212.220.88.77) port 443 (#0)
+* ALPN: offers h2,http/1.1
+* TLSv1.3 (OUT), TLS handshake, Client hello (1):
+*  CAfile: /etc/ssl/certs/ca-certificates.crt
+*  CApath: /etc/ssl/certs
+* TLSv1.3 (IN), TLS handshake, Server hello (2):
+* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
+* TLSv1.3 (IN), TLS handshake, Certificate (11):
+* TLSv1.3 (IN), TLS handshake, CERT verify (15):
+* TLSv1.3 (IN), TLS handshake, Finished (20):
+* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
+* TLSv1.3 (OUT), TLS handshake, Finished (20):
+* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
+* ALPN: server did not agree on a protocol. Uses default.
+* Server certificate:
+*  subject: C=RU; ST=Saint Petersburg; L=Saint Petersburg; O=STD Petrovich; CN=*.petrovich.ru
+*  start date: Jan 28 11:21:01 2025 GMT
+*  expire date: Mar  1 11:21:00 2026 GMT
+*  subjectAltName: host "petrovich.ru" matched cert's "petrovich.ru"
+*  issuer: C=BE; O=GlobalSign nv-sa; CN=GlobalSign RSA OV SSL CA 2018
+*  SSL certificate verify ok.
+* using HTTP/1.x
+> HEAD / HTTP/1.1
+> Host: petrovich.ru
+> User-Agent: curl/7.88.1
+> Accept: */*
+> 
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
+* old SSL session ID is stale, removing
+< HTTP/1.1 200 OK
+HTTP/1.1 200 OK
+< Server: Variti/0.9.3a
+Server: Variti/0.9.3a
+< Date: Thu, 01 Jan 2026 00:0000 GMT
+Date: Thu, 01 Jan 2026 00:0000 GMT
+< Access-Control-Allow-Origin: *
+Access-Control-Allow-Origin: *
+< Content-Type: text/html
+Content-Type: text/html
+< Cache-Control: no-store
+Cache-Control: no-store
+< Expires: Thu, 01 Jan 2026 00:0000 GMT
+Expires: Thu, 01 Jan 2026 00:0000 GMT
+< Pragma: no-cache
+Pragma: no-cache
+< Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+Set-Cookie: ipp_uid=XXXXX/XXXXX/XXXXX==; Expires=Tue, 31 Dec 2040 23:59:59 GMT; Domain=.petrovich.ru; Path=/
+< Content-Type: text/html
+Content-Type: text/html
+< Content-Length: 31253
+Content-Length: 31253
+< Connection: keep-alive
+Connection: keep-alive
+< Keep-Alive: timeout=60
+Keep-Alive: timeout=60
+
+< 
+* Connection #0 to host petrovich.ru left intact
+
+```
+- We challenged ourselves, we kept trying and we didn't only *beat the air*: now, we have something to show you
+  - Do not just take our word for it? - This is great and we respect that: you can build your own `telemt` or download a build and check it right now
 ### Telegram Calls via MTProxy
 - Telegram architecture **does NOT allow calls via MTProxy**, but only via SOCKS5, which cannot be obfuscated
 ### How does DPI see MTProxy TLS?
@@ -206,6 +211,23 @@ enabled = true
   - in China behind the Great Firewall
   - in Russia on mobile networks, less in wired networks
   - in Iran during "activity"
+### Too many open files
+- On a fresh Linux install the default open file limit is low; under load `telemt` may fail with `Accept error: Too many open files`
+- **Systemd**: add `LimitNOFILE=65536` to the `[Service]` section (already included in the example above)
+- **Docker**: add `--ulimit nofile=65536:65536` to your `docker run` command, or in `docker-compose.yml`:
+```yaml
+ulimits:
+  nofile:
+    soft: 65536
+    hard: 65536
+```
+- **System-wide** (optional): add to `/etc/security/limits.conf`:
+```
+*       soft    nofile  1048576
+*       hard    nofile  1048576
+root    soft    nofile  1048576
+root    hard    nofile  1048576
+```
 
 
 ## Build
@@ -216,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
@@ -224,13 +251,23 @@ chmod +x /bin/telemt
 telemt config.toml
 ```
 
+### 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.
+
+
 ## Why Rust?
 - Long-running reliability and idempotent behavior
-- Rust’s deterministic resource management - RAII 
+- Rust's deterministic resource management - RAII 
 - No garbage collector
 - Memory safety and reduced attack surface
 - Tokio's asynchronous architecture
 
+## Issues
+- ✅ [SOCKS5 as Upstream](https://github.com/telemt/telemt/issues/1) -> added Upstream Management
+- ✅ [iOS - Media Upload Hanging-in-Loop](https://github.com/telemt/telemt/issues/2)
+
 ## Roadmap
 - Public IP in links
 - Config Reload-on-fly

ROADMAP.md

@@ -0,0 +1,34 @@
+### 3.0.0 Anschluss
+- **Middle Proxy now is stable**, confirmed on canary-deploy over ~20 users
+- Ad-tag now is working
+- DC=203/CDN now is working over ME
+- `getProxyConfig` and `ProxySecret` are automated
+- Version order is now in format `3.0.0` - without Windows-style "microfixes"
+
+### 3.0.1 Kabelsammler
+- Handshake timeouts fixed
+- Connectivity logging refactored
+- Docker: tmpfs for ProxyConfig and ProxySecret
+- Public Host and Port in config
+- ME Relays Head-of-Line Blocking fixed
+- ME Ping
+
+### 3.0.2 Microtrencher
+- New [network] section
+- ME Fixes
+- Small bugs coverage
+
+### 3.0.3 Ausrutscher
+- ME as stateful, no conn-id migration
+- No `flush()` on datapath after RpcWriter
+- Hightech parser for IPv6 without regexp
+- `nat_probe = true` by default
+- Timeout for `recv()` in STUN-client
+- ConnRegistry review
+- Dualstack emergency reconnect
+
+### 3.0.4 Schneeflecken
+- Only WARN and Links in Normal log
+- Consistent IP-family detection
+- Includes for config
+- `nonce_frame_hex` in log only with `DEBUG`

config.toml

@@ -1,13 +1,58 @@
-port = 443
+### Telemt Based Config.toml
+# We believe that these settings are sufficient for most scenarios 
+# where cutting-egde methods and parameters or special solutions are not needed
 
-[users]
-user1 = "00000000000000000000000000000000"
+# === General Settings ===
+[general]
+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)
 
-[modes]
-classic = true
-secure = true
+# === Log Level ===
+# Log level: debug | verbose | normal | silent
+# Can be overridden with --silent or --log-level CLI flags
+# RUST_LOG env var takes absolute priority over all of these
+log_level = "normal"
+
+[general.modes]
+classic = false
+secure = false
 tls = true
 
-tls_domain = "www.github.com"
-fast_mode = true
-prefer_ipv6 = false
+[general.links]
+show = "*"
+# show = ["alice", "bob"] # Only show links for alice and bob
+# show = "*"              # Show links for all users
+# public_host = "proxy.example.com"  # Host (IP or domain) for tg:// links
+# public_port = 443                  # Port for tg:// links (default: server.port)
+
+# === Server Binding ===
+[server]
+port = 443
+# proxy_protocol = false           # Enable if behind HAProxy/nginx with PROXY protocol
+# metrics_port = 9090
+# metrics_listen = "0.0.0.0:9090"  # Listen address for metrics (overrides metrics_port)
+# metrics_whitelist = ["127.0.0.1", "::1", "0.0.0.0/0"]
+
+[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"
+
+# === Anti-Censorship & Masking ===
+[censorship]
+tls_domain = "petrovich.ru"
+mask = true
+tls_emulation = true        # Fetch real cert lengths and emulate TLS records
+tls_front_dir = "tlsfront"   # Cache directory for TLS emulation
+
+[access.users]
+# format: "username" = "32_hex_chars_secret"
+hello = "00000000000000000000000000000000"

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

@@ -0,0 +1,30 @@
+services:
+  telemt:
+    image: ghcr.io/telemt/telemt:latest
+    build: .
+    container_name: telemt
+    restart: unless-stopped
+    ports:
+      - "443:443"
+      - "127.0.0.1:9090:9090"
+    # Allow caching 'proxy-secret' in read-only container
+    working_dir: /run/telemt
+    volumes:
+      - ./config.toml:/run/telemt/config.toml:ro
+    tmpfs:
+      - /run/telemt:rw,mode=1777,size=1m
+    environment:
+      - RUST_LOG=info
+    # Uncomment this line if you want to use host network for IPv6, but bridge is default and usually better
+    # network_mode: host
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE   # allow binding to port 443
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    ulimits:
+      nofile:
+        soft: 65536
+        hard: 65536

docs/CONFIG_PARAMS.en.md

@@ -0,0 +1,289 @@
+# Telemt Config Parameters Reference
+
+This document lists all configuration keys accepted by `config.toml`.
+
+> [!WARNING]
+> 
+> The configuration parameters detailed in this document are intended for advanced users and fine-tuning purposes. Modifying these settings without a clear understanding of their function may lead to application instability or other unexpected behavior. Please proceed with caution and at your own risk.
+
+## Top-level keys
+
+| Parameter | Type | Description |
+|---|---|---|
+| include | `String` (special directive) | Includes another TOML file with `include = "relative/or/absolute/path.toml"`; includes are processed recursively before parsing. |
+| show_link | `"*" \| String[]` | Legacy top-level link visibility selector (`"*"` for all users or explicit usernames list). |
+| dc_overrides | `Map<String, String[]>` | Overrides DC endpoints for non-standard DCs; key is DC id string, value is `ip:port` list. |
+| default_dc | `u8` | Default DC index used for unmapped non-standard DCs. |
+
+## [general]
+
+| Parameter | Type | Description |
+|---|---|---|
+| data_path | `String` | Optional runtime data directory path. |
+| prefer_ipv6 | `bool` | Prefer IPv6 where applicable in runtime logic. |
+| fast_mode | `bool` | Enables fast-path optimizations for traffic processing. |
+| use_middle_proxy | `bool` | Enables Middle Proxy mode. |
+| proxy_secret_path | `String` | Path to proxy secret binary; can be auto-downloaded if absent. |
+| proxy_config_v4_cache_path | `String` | Optional cache path for raw `getProxyConfig` (IPv4) snapshot. |
+| proxy_config_v6_cache_path | `String` | Optional cache path for raw `getProxyConfigV6` (IPv6) snapshot. |
+| ad_tag | `String` | Global fallback ad tag (32 hex characters). |
+| middle_proxy_nat_ip | `IpAddr` | Explicit public IP override for NAT environments. |
+| middle_proxy_nat_probe | `bool` | Enables NAT probing for Middle Proxy KDF/public address discovery. |
+| middle_proxy_nat_stun | `String` | Deprecated legacy single STUN server for NAT probing. |
+| middle_proxy_nat_stun_servers | `String[]` | Deprecated legacy STUN list for NAT probing fallback. |
+| stun_nat_probe_concurrency | `usize` | Maximum concurrent STUN probes during NAT detection. |
+| middle_proxy_pool_size | `usize` | Target size of active Middle Proxy writer pool. |
+| middle_proxy_warm_standby | `usize` | Number of warm standby Middle-End connections. |
+| me_init_retry_attempts | `u32` | Startup retries for ME pool initialization (`0` means unlimited). |
+| me2dc_fallback | `bool` | Allows fallback from ME mode to direct DC when ME startup fails. |
+| me_keepalive_enabled | `bool` | Enables ME keepalive padding frames. |
+| me_keepalive_interval_secs | `u64` | Keepalive interval in seconds. |
+| me_keepalive_jitter_secs | `u64` | Keepalive jitter in seconds. |
+| me_keepalive_payload_random | `bool` | Randomizes keepalive payload bytes instead of zero payload. |
+| rpc_proxy_req_every | `u64` | Interval for service `RPC_PROXY_REQ` activity signals (`0` disables). |
+| me_writer_cmd_channel_capacity | `usize` | Capacity of per-writer command channel. |
+| me_route_channel_capacity | `usize` | Capacity of per-connection ME response route channel. |
+| me_c2me_channel_capacity | `usize` | Capacity of per-client command queue (client reader -> ME sender). |
+| me_reader_route_data_wait_ms | `u64` | Bounded wait for routing ME DATA to per-connection queue (`0` = no wait). |
+| me_d2c_flush_batch_max_frames | `usize` | Max ME->client frames coalesced before flush. |
+| me_d2c_flush_batch_max_bytes | `usize` | Max ME->client payload bytes coalesced before flush. |
+| me_d2c_flush_batch_max_delay_us | `u64` | Max microsecond wait for coalescing more ME->client frames (`0` disables timed coalescing). |
+| me_d2c_ack_flush_immediate | `bool` | Flushes client writer immediately after quick-ack write. |
+| direct_relay_copy_buf_c2s_bytes | `usize` | Copy buffer size for client->DC direction in direct relay. |
+| direct_relay_copy_buf_s2c_bytes | `usize` | Copy buffer size for DC->client direction in direct relay. |
+| crypto_pending_buffer | `usize` | Max pending ciphertext buffer per client writer (bytes). |
+| max_client_frame | `usize` | Maximum allowed client MTProto frame size (bytes). |
+| desync_all_full | `bool` | Emits full crypto-desync forensic logs for every event. |
+| beobachten | `bool` | Enables per-IP forensic observation buckets. |
+| beobachten_minutes | `u64` | Retention window (minutes) for per-IP observation buckets. |
+| beobachten_flush_secs | `u64` | Snapshot flush interval (seconds) for observation output file. |
+| beobachten_file | `String` | Observation snapshot output file path. |
+| hardswap | `bool` | Enables hard-swap generation switching for ME pool updates. |
+| me_warmup_stagger_enabled | `bool` | Enables staggered warmup for extra ME writers. |
+| me_warmup_step_delay_ms | `u64` | Base delay between warmup connections (ms). |
+| me_warmup_step_jitter_ms | `u64` | Jitter for warmup delay (ms). |
+| me_reconnect_max_concurrent_per_dc | `u32` | Max concurrent reconnect attempts per DC. |
+| me_reconnect_backoff_base_ms | `u64` | Base reconnect backoff in ms. |
+| me_reconnect_backoff_cap_ms | `u64` | Cap reconnect backoff in ms. |
+| me_reconnect_fast_retry_count | `u32` | Number of fast retry attempts before backoff. |
+| me_single_endpoint_shadow_writers | `u8` | Additional reserve writers for one-endpoint DC groups. |
+| me_single_endpoint_outage_mode_enabled | `bool` | Enables aggressive outage recovery for one-endpoint DC groups. |
+| me_single_endpoint_outage_disable_quarantine | `bool` | Ignores endpoint quarantine in one-endpoint outage mode. |
+| me_single_endpoint_outage_backoff_min_ms | `u64` | Minimum reconnect backoff in outage mode (ms). |
+| me_single_endpoint_outage_backoff_max_ms | `u64` | Maximum reconnect backoff in outage mode (ms). |
+| me_single_endpoint_shadow_rotate_every_secs | `u64` | Periodic shadow writer rotation interval (`0` disables). |
+| me_floor_mode | `"static" \| "adaptive"` | Writer floor policy mode. |
+| me_adaptive_floor_idle_secs | `u64` | Idle time before adaptive floor may reduce one-endpoint target. |
+| me_adaptive_floor_min_writers_single_endpoint | `u8` | Minimum adaptive writer target for one-endpoint DC groups. |
+| me_adaptive_floor_min_writers_multi_endpoint | `u8` | Minimum adaptive writer target for multi-endpoint DC groups. |
+| me_adaptive_floor_recover_grace_secs | `u64` | Grace period to hold static floor after activity. |
+| me_adaptive_floor_writers_per_core_total | `u16` | Global writer budget per logical CPU core in adaptive mode. |
+| me_adaptive_floor_cpu_cores_override | `u16` | Manual CPU core count override (`0` uses auto-detection). |
+| me_adaptive_floor_max_extra_writers_single_per_core | `u16` | Per-core max extra writers above base floor for one-endpoint DCs. |
+| me_adaptive_floor_max_extra_writers_multi_per_core | `u16` | Per-core max extra writers above base floor for multi-endpoint DCs. |
+| me_adaptive_floor_max_active_writers_per_core | `u16` | Hard cap for active ME writers per logical CPU core. |
+| me_adaptive_floor_max_warm_writers_per_core | `u16` | Hard cap for warm ME writers per logical CPU core. |
+| me_adaptive_floor_max_active_writers_global | `u32` | Hard global cap for active ME writers. |
+| me_adaptive_floor_max_warm_writers_global | `u32` | Hard global cap for warm ME writers. |
+| upstream_connect_retry_attempts | `u32` | Connect attempts for selected upstream before error/fallback. |
+| upstream_connect_retry_backoff_ms | `u64` | Delay between upstream connect attempts (ms). |
+| upstream_connect_budget_ms | `u64` | Total wall-clock budget for one upstream connect request (ms). |
+| upstream_unhealthy_fail_threshold | `u32` | Consecutive failed requests before upstream is marked unhealthy. |
+| upstream_connect_failfast_hard_errors | `bool` | Skips additional retries for hard non-transient connect errors. |
+| stun_iface_mismatch_ignore | `bool` | Ignores STUN/interface mismatch and keeps Middle Proxy mode. |
+| unknown_dc_log_path | `String` | File path for unknown-DC request logging (`null` disables file path). |
+| unknown_dc_file_log_enabled | `bool` | Enables unknown-DC file logging. |
+| log_level | `"debug" \| "verbose" \| "normal" \| "silent"` | Runtime logging verbosity. |
+| disable_colors | `bool` | Disables ANSI colors in logs. |
+| me_socks_kdf_policy | `"strict" \| "compat"` | SOCKS-bound KDF fallback policy for ME handshake. |
+| me_route_backpressure_base_timeout_ms | `u64` | Base backpressure timeout for route-channel send (ms). |
+| me_route_backpressure_high_timeout_ms | `u64` | High backpressure timeout when queue occupancy exceeds watermark (ms). |
+| me_route_backpressure_high_watermark_pct | `u8` | Queue occupancy threshold (%) for high timeout mode. |
+| me_health_interval_ms_unhealthy | `u64` | Health monitor interval while writer coverage is degraded (ms). |
+| me_health_interval_ms_healthy | `u64` | Health monitor interval while writer coverage is healthy (ms). |
+| me_admission_poll_ms | `u64` | Poll interval for conditional-admission checks (ms). |
+| me_warn_rate_limit_ms | `u64` | Cooldown for repetitive ME warning logs (ms). |
+| me_route_no_writer_mode | `"async_recovery_failfast" \| "inline_recovery_legacy" \| "hybrid_async_persistent"` | Route behavior when no writer is immediately available. |
+| me_route_no_writer_wait_ms | `u64` | Max wait in async-recovery failfast mode (ms). |
+| me_route_inline_recovery_attempts | `u32` | Inline recovery attempts in legacy mode. |
+| me_route_inline_recovery_wait_ms | `u64` | Max inline recovery wait in legacy mode (ms). |
+| fast_mode_min_tls_record | `usize` | Minimum TLS record size when fast-mode coalescing is enabled (`0` disables). |
+| update_every | `u64` | Unified interval for config/secret updater tasks. |
+| me_reinit_every_secs | `u64` | Periodic ME pool reinitialization interval (seconds). |
+| me_hardswap_warmup_delay_min_ms | `u64` | Minimum delay between hardswap warmup connects (ms). |
+| me_hardswap_warmup_delay_max_ms | `u64` | Maximum delay between hardswap warmup connects (ms). |
+| me_hardswap_warmup_extra_passes | `u8` | Additional warmup passes per hardswap cycle. |
+| me_hardswap_warmup_pass_backoff_base_ms | `u64` | Base backoff between hardswap warmup passes (ms). |
+| me_config_stable_snapshots | `u8` | Number of identical config snapshots required before apply. |
+| me_config_apply_cooldown_secs | `u64` | Cooldown between applied ME map updates (seconds). |
+| me_snapshot_require_http_2xx | `bool` | Requires 2xx HTTP responses for applying config snapshots. |
+| me_snapshot_reject_empty_map | `bool` | Rejects empty config snapshots. |
+| me_snapshot_min_proxy_for_lines | `u32` | Minimum parsed `proxy_for` rows required to accept snapshot. |
+| proxy_secret_stable_snapshots | `u8` | Number of identical secret snapshots required before runtime rotation. |
+| proxy_secret_rotate_runtime | `bool` | Enables runtime proxy-secret rotation from remote source. |
+| me_secret_atomic_snapshot | `bool` | Keeps selector and secret bytes from the same snapshot atomically. |
+| proxy_secret_len_max | `usize` | Maximum allowed proxy-secret length (bytes). |
+| me_pool_drain_ttl_secs | `u64` | Drain TTL for stale ME writers after endpoint-map changes (seconds). |
+| me_pool_drain_threshold | `u64` | Max draining stale writers before batch force-close (`0` disables threshold cleanup). |
+| me_bind_stale_mode | `"never" \| "ttl" \| "always"` | Policy for new binds on stale draining writers. |
+| me_bind_stale_ttl_secs | `u64` | TTL for stale bind allowance when stale mode is `ttl`. |
+| me_pool_min_fresh_ratio | `f32` | Minimum desired-DC fresh coverage ratio before draining stale writers. |
+| me_reinit_drain_timeout_secs | `u64` | Force-close timeout for stale writers after endpoint-map changes (`0` disables force-close). |
+| proxy_secret_auto_reload_secs | `u64` | Deprecated legacy secret reload interval (fallback when `update_every` is not set). |
+| proxy_config_auto_reload_secs | `u64` | Deprecated legacy config reload interval (fallback when `update_every` is not set). |
+| me_reinit_singleflight | `bool` | Serializes ME reinit cycles across trigger sources. |
+| me_reinit_trigger_channel | `usize` | Trigger queue capacity for reinit scheduler. |
+| me_reinit_coalesce_window_ms | `u64` | Trigger coalescing window before starting reinit (ms). |
+| me_deterministic_writer_sort | `bool` | Enables deterministic candidate sort for writer binding path. |
+| me_writer_pick_mode | `"sorted_rr" \| "p2c"` | Writer selection mode for route bind path. |
+| me_writer_pick_sample_size | `u8` | Number of candidates sampled by picker in `p2c` mode. |
+| ntp_check | `bool` | Enables NTP drift check at startup. |
+| ntp_servers | `String[]` | NTP servers used for drift check. |
+| auto_degradation_enabled | `bool` | Enables automatic degradation from ME to direct DC. |
+| degradation_min_unavailable_dc_groups | `u8` | Minimum unavailable ME DC groups required before degrading. |
+
+## [general.modes]
+
+| Parameter | Type | Description |
+|---|---|---|
+| classic | `bool` | Enables classic MTProxy mode. |
+| secure | `bool` | Enables secure mode. |
+| tls | `bool` | Enables TLS mode. |
+
+## [general.links]
+
+| Parameter | Type | Description |
+|---|---|---|
+| show | `"*" \| String[]` | Selects users whose tg:// links are shown at startup. |
+| public_host | `String` | Public hostname/IP override for generated tg:// links. |
+| public_port | `u16` | Public port override for generated tg:// links. |
+
+## [general.telemetry]
+
+| Parameter | Type | Description |
+|---|---|---|
+| core_enabled | `bool` | Enables core hot-path telemetry counters. |
+| user_enabled | `bool` | Enables per-user telemetry counters. |
+| me_level | `"silent" \| "normal" \| "debug"` | Middle-End telemetry verbosity level. |
+
+## [network]
+
+| Parameter | Type | Description |
+|---|---|---|
+| ipv4 | `bool` | Enables IPv4 networking. |
+| ipv6 | `bool` | Enables/disables IPv6 (`null` = auto-detect availability). |
+| prefer | `u8` | Preferred IP family for selection (`4` or `6`). |
+| multipath | `bool` | Enables multipath behavior where supported. |
+| stun_use | `bool` | Global switch for STUN probing. |
+| stun_servers | `String[]` | STUN server list for public IP detection. |
+| stun_tcp_fallback | `bool` | Enables TCP STUN fallback when UDP STUN is blocked. |
+| http_ip_detect_urls | `String[]` | HTTP endpoints used as fallback public IP detectors. |
+| cache_public_ip_path | `String` | File path for caching detected public IP. |
+| dns_overrides | `String[]` | Runtime DNS overrides in `host:port:ip` format. |
+
+## [server]
+
+| Parameter | Type | Description |
+|---|---|---|
+| port | `u16` | Main proxy listen port. |
+| listen_addr_ipv4 | `String` | IPv4 bind address for TCP listener. |
+| listen_addr_ipv6 | `String` | IPv6 bind address for TCP listener. |
+| listen_unix_sock | `String` | Unix socket path for listener. |
+| listen_unix_sock_perm | `String` | Unix socket permissions in octal string (e.g., `"0666"`). |
+| listen_tcp | `bool` | Explicit TCP listener enable/disable override. |
+| proxy_protocol | `bool` | Enables HAProxy PROXY protocol parsing on incoming client connections. |
+| proxy_protocol_header_timeout_ms | `u64` | Timeout for PROXY protocol header read/parse (ms). |
+| metrics_port | `u16` | Metrics endpoint port (enables metrics listener). |
+| metrics_listen | `String` | Full metrics bind address (`IP:PORT`), overrides `metrics_port`. |
+| metrics_whitelist | `IpNetwork[]` | CIDR whitelist for metrics endpoint access. |
+| max_connections | `u32` | Max concurrent client connections (`0` = unlimited). |
+
+## [server.api]
+
+| Parameter | Type | Description |
+|---|---|---|
+| enabled | `bool` | Enables control-plane REST API. |
+| listen | `String` | API bind address in `IP:PORT` format. |
+| whitelist | `IpNetwork[]` | CIDR whitelist allowed to access API. |
+| auth_header | `String` | Exact expected `Authorization` header value (empty = disabled). |
+| request_body_limit_bytes | `usize` | Maximum accepted HTTP request body size. |
+| minimal_runtime_enabled | `bool` | Enables minimal runtime snapshots endpoint logic. |
+| minimal_runtime_cache_ttl_ms | `u64` | Cache TTL for minimal runtime snapshots (ms; `0` disables cache). |
+| runtime_edge_enabled | `bool` | Enables runtime edge endpoints. |
+| runtime_edge_cache_ttl_ms | `u64` | Cache TTL for runtime edge aggregation payloads (ms). |
+| runtime_edge_top_n | `usize` | Top-N size for edge connection leaderboard. |
+| runtime_edge_events_capacity | `usize` | Ring-buffer capacity for runtime edge events. |
+| read_only | `bool` | Rejects mutating API endpoints when enabled. |
+
+## [[server.listeners]]
+
+| Parameter | Type | Description |
+|---|---|---|
+| ip | `IpAddr` | Listener bind IP. |
+| announce | `String` | Public IP/domain announced in proxy links (priority over `announce_ip`). |
+| announce_ip | `IpAddr` | Deprecated legacy announce IP (migrated to `announce` if needed). |
+| proxy_protocol | `bool` | Per-listener override for PROXY protocol enable flag. |
+| reuse_allow | `bool` | Enables `SO_REUSEPORT` for multi-instance bind sharing. |
+
+## [timeouts]
+
+| Parameter | Type | Description |
+|---|---|---|
+| client_handshake | `u64` | Client handshake timeout. |
+| tg_connect | `u64` | Upstream Telegram connect timeout. |
+| client_keepalive | `u64` | Client keepalive timeout. |
+| client_ack | `u64` | Client ACK timeout. |
+| me_one_retry | `u8` | Quick ME reconnect attempts for single-address DC. |
+| me_one_timeout_ms | `u64` | Timeout per quick attempt for single-address DC (ms). |
+
+## [censorship]
+
+| Parameter | Type | Description |
+|---|---|---|
+| tls_domain | `String` | Primary TLS domain used in fake TLS handshake profile. |
+| tls_domains | `String[]` | Additional TLS domains for generating multiple links. |
+| mask | `bool` | Enables masking/fronting relay mode. |
+| mask_host | `String` | Upstream mask host for TLS fronting relay. |
+| mask_port | `u16` | Upstream mask port for TLS fronting relay. |
+| mask_unix_sock | `String` | Unix socket path for mask backend instead of TCP host/port. |
+| fake_cert_len | `usize` | Length of synthetic certificate payload when emulation data is unavailable. |
+| tls_emulation | `bool` | Enables certificate/TLS behavior emulation from cached real fronts. |
+| tls_front_dir | `String` | Directory path for TLS front cache storage. |
+| server_hello_delay_min_ms | `u64` | Minimum server_hello delay for anti-fingerprint behavior (ms). |
+| server_hello_delay_max_ms | `u64` | Maximum server_hello delay for anti-fingerprint behavior (ms). |
+| tls_new_session_tickets | `u8` | Number of `NewSessionTicket` messages to emit after handshake. |
+| tls_full_cert_ttl_secs | `u64` | TTL for sending full cert payload per (domain, client IP) tuple. |
+| alpn_enforce | `bool` | Enforces ALPN echo behavior based on client preference. |
+| mask_proxy_protocol | `u8` | PROXY protocol mode for mask backend (`0` disabled, `1` v1, `2` v2). |
+
+## [access]
+
+| Parameter | Type | Description |
+|---|---|---|
+| users | `Map<String, String>` | Username -> 32-hex secret mapping. |
+| user_ad_tags | `Map<String, String>` | Per-user ad tags (32 hex chars). |
+| user_max_tcp_conns | `Map<String, usize>` | Per-user maximum concurrent TCP connections. |
+| user_expirations | `Map<String, DateTime<Utc>>` | Per-user account expiration timestamps. |
+| user_data_quota | `Map<String, u64>` | Per-user data quota limits. |
+| user_max_unique_ips | `Map<String, usize>` | Per-user unique source IP limits. |
+| user_max_unique_ips_global_each | `usize` | Global fallback per-user unique IP limit when no per-user override exists. |
+| user_max_unique_ips_mode | `"active_window" \| "time_window" \| "combined"` | Unique source IP limit accounting mode. |
+| user_max_unique_ips_window_secs | `u64` | Recent-window size for unique IP accounting (seconds). |
+| replay_check_len | `usize` | Replay check storage length. |
+| replay_window_secs | `u64` | Replay protection time window in seconds. |
+| ignore_time_skew | `bool` | Ignores client/server timestamp skew in replay validation. |
+
+## [[upstreams]]
+
+| Parameter | Type | Description |
+|---|---|---|
+| type | `"direct" \| "socks4" \| "socks5"` | Upstream transport type selector. |
+| weight | `u16` | Weighted selection coefficient for this upstream. |
+| enabled | `bool` | Enables/disables this upstream entry. |
+| scopes | `String` | Comma-separated scope tags for routing. |
+| interface | `String` | Optional outgoing interface name (`direct`, `socks4`, `socks5`). |
+| bind_addresses | `String[]` | Optional source bind addresses for `direct` upstream. |
+| address | `String` | Upstream proxy address (`host:port`) for SOCKS upstreams. |
+| user_id | `String` | SOCKS4 user ID (only for `type = "socks4"`). |
+| username | `String` | SOCKS5 username (only for `type = "socks5"`). |
+| password | `String` | SOCKS5 password (only for `type = "socks5"`). |

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

@@ -0,0 +1,123 @@
+## Как настроить канал "спонсор прокси" и статистику через бота @MTProxybot
+
+1. Зайти в бота @MTProxybot.
+2. Ввести команду `/newproxy`
+3. Отправить IP и порт сервера. Например: 1.2.3.4:443
+4. Открыть конфиг `nano /etc/telemt.toml`.
+5. Скопировать и отправить боту секрет пользователя из раздела [access.users].
+6. Скопировать полученный tag у бота. Например 1234567890abcdef1234567890abcdef.
+> [!WARNING]
+> Ссылка, которую выдает бот, не будет работать. Не копируйте и не используйте её!
+7. Раскомментировать параметр ad_tag и вписать tag, полученный у бота.
+8. Раскомментировать/добавить параметр use_middle_proxy = true.
+
+Пример конфига:
+```toml
+[general]
+ad_tag = "1234567890abcdef1234567890abcdef"
+use_middle_proxy = true
+```
+9.  Сохранить конфиг. Ctrl+S -> Ctrl+X.
+10. Перезапустить telemt `systemctl restart telemt`.
+11. В боте отправить команду /myproxies и выбрать добавленный сервер.
+12. Нажать кнопку "Set promotion".
+13. Отправить **публичную ссылку** на канал. Приватный канал добавить нельзя!
+14. Подождать примерно 1 час, пока информация обновится на серверах Telegram.
+> [!WARNING]
+> У вас не будет отображаться "спонсор прокси" если вы уже подписаны на канал.
+
+**Также вы можете настроить разные каналы для разных пользователей.**
+```toml
+[access.user_ad_tags]
+hello = "ad_tag"
+hello2 = "ad_tag2"
+```
+
+## Сколько человек может пользоваться 1 ссылкой
+
+По умолчанию 1 ссылкой может пользоваться сколько угодно человек.  
+Вы можете ограничить число IP, использующих прокси.
+```toml
+[access.user_max_unique_ips]
+hello = 1
+```
+Этот параметр ограничивает, сколько уникальных IP может использовать 1 ссылку одновременно. Если один пользователь отключится, второй сможет подключиться. Также с одного IP может сидеть несколько пользователей.
+
+## Как сделать несколько разных ссылок
+
+1. Сгенерируйте нужное число секретов `openssl rand -hex 16`
+2. Открыть конфиг `nano /etc/telemt.toml`
+3. Добавить новых пользователей.
+```toml
+[access.users]
+user1 = "00000000000000000000000000000001"
+user2 = "00000000000000000000000000000002"
+user3 = "00000000000000000000000000000003"
+```
+4. Сохранить конфиг. Ctrl+S -> Ctrl+X. Перезапускать telemt не нужно.
+5. Получить ссылки через
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
+
+## Как посмотреть метрики
+
+1. Открыть конфиг `nano /etc/telemt.toml`
+2. Добавить следующие параметры
+```toml
+[server]
+metrics_port = 9090
+metrics_whitelist = ["127.0.0.1/32", "::1/128", "0.0.0.0/0"]
+```
+3. Сохранить конфиг. Ctrl+S -> Ctrl+X.
+4. Метрики доступны по адресу SERVER_IP:9090/metrics. 
+> [!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

@@ -0,0 +1,190 @@
+# Telemt via Systemd
+
+## Installation
+
+This software is designed for Debian-based OS: in addition to Debian, these are Ubuntu, Mint, Kali, MX and many other Linux
+
+**1. Download**
+```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 the Bin folder**
+```bash
+mv telemt /bin
+```
+**3. Make the file executable**
+```bash
+chmod +x /bin/telemt
+```
+
+## How to use?
+
+**This guide "assumes" that you:**
+- logged in as root or executed `su -` / `sudo su`
+- Already have the "telemt" executable file in the /bin folder. Read the **[Installation](#Installation)** section.
+
+---
+
+**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())'
+```
+Save the obtained result somewhere. You will need it later!
+
+---
+
+**1. Place your config to /etc/telemt/telemt.toml**
+
+Create config directory:
+```bash
+mkdir /etc/telemt
+```
+
+Open nano
+```bash
+nano /etc/telemt/telemt.toml
+```
+paste your config
+
+```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"
+
+[access.users]
+# format: "username" = "32_hex_chars_secret"
+hello = "00000000000000000000000000000000"
+```
+
+then Ctrl+S -> Ctrl+X to save
+
+> [!WARNING]
+> Replace the value of the hello parameter with the value you obtained in step 0. 
+> Replace the value of the tls_domain parameter with another website.
+
+---
+
+**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
+nano /etc/systemd/system/telemt.service
+```
+
+paste this Systemd Module
+```bash
+[Unit]
+Description=Telemt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+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
+```
+
+**4.** To start it, enter the command `systemctl start telemt`
+
+**5.** To get status information, enter `systemctl status telemt`
+
+**6.** For automatic startup at system boot, enter `systemctl enable telemt`
+
+**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.
+
+---
+
+# Telemt via Docker Compose
+
+**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
+```
+> [!NOTE]
+> - `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
+```

docs/QUICK_START_GUIDE.ru.md

@@ -0,0 +1,192 @@
+# Telemt через Systemd
+
+## Установка
+
+Это программное обеспечение разработано для ОС на базе Debian: помимо Debian, это Ubuntu, Mint, Kali, MX и многие другие Linux
+
+**1. Скачать**
+```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. Переместить в папку Bin**
+```bash
+mv telemt /bin
+```
+**3. Сделать файл исполняемым**
+```bash
+chmod +x /bin/telemt
+```
+
+## Как правильно использовать?
+
+**Эта инструкция "предполагает", что вы:**
+- Авторизовались как пользователь root или выполнил `su -` / `sudo su`
+- У вас уже есть исполняемый файл "telemt" в папке /bin. Читайте раздел **[Установка](#установка)**
+
+---
+
+**0. Проверьте порт и сгенерируйте секреты**
+
+Порт, который вы выбрали для использования, должен отсутствовать в списке:
+```bash
+netstat -lnp
+```
+
+Сгенерируйте 16 bytes/32 символа в шестнадцатеричном формате с помощью OpenSSL или другим способом:
+```bash
+openssl rand -hex 16
+```
+ИЛИ
+```bash
+xxd -l 16 -p /dev/urandom
+```
+ИЛИ
+```bash
+python3 -c 'import os; print(os.urandom(16).hex())'
+```
+Полученный результат сохраняем где-нибудь. Он понадобиться вам дальше!
+
+---
+
+**1. Поместите свою конфигурацию в файл /etc/telemt/telemt.toml**
+
+Создаём директорию для конфига:
+```bash
+mkdir /etc/telemt
+```
+
+Открываем nano
+```bash
+nano /etc/telemt/telemt.toml
+```
+Вставьте свою конфигурацию
+
+```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"
+
+[access.users]
+# format: "username" = "32_hex_chars_secret"
+hello = "00000000000000000000000000000000"
+```
+
+Затем нажмите Ctrl+S -> Ctrl+X, чтобы сохранить
+
+> [!WARNING]
+> Замените значение параметра hello на значение, которое вы получили в пункте 0.  
+> Так же замените значение параметра tls_domain на другой сайт.
+
+---
+
+**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
+nano /etc/systemd/system/telemt.service
+```
+
+Вставьте этот модуль Systemd
+```bash
+[Unit]
+Description=Telemt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+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
+```
+
+**4.** Для запуска введите команду `systemctl start telemt`
+
+**5.** Для получения информации о статусе введите `systemctl status telemt`
+
+**6.** Для автоматического запуска при запуске системы в введите `systemctl enable telemt`
+
+**7.** Для получения ссылки/ссылок введите 
+```bash
+curl -s http://127.0.0.1:9091/v1/users | jq
+```
+> Одной ссылкой может пользоваться сколько угодно человек.
+
+> [!WARNING]
+> Рабочую ссылку может выдать только команда из 7 пункта. Не пытайтесь делать ее самостоятельно или копировать откуда-либо если вы не уверены в том, что делаете!
+
+---
+
+# Telemt через Docker Compose
+
+**1. Отредактируйте `config.toml` в корневом каталоге репозитория (как минимум: порт, пользовательские секреты, tls_domain)**  
+**2. Запустите контейнер:**
+```bash
+docker compose up -d --build
+```
+**3. Проверьте логи:**
+```bash
+docker compose logs -f telemt
+```
+**4. Остановите контейнер:**
+```bash
+docker compose down
+```
+> [!NOTE]
+> - В `docker-compose.yml` файл `./config.toml` монтируется в `/app/config.toml` (доступно только для чтения)  
+> - По умолчанию публикуются порты 443:443, а контейнер запускается со сброшенными привилегиями (добавлена только `NET_BIND_SERVICE`)  
+> - Если вам действительно нужна сеть хоста (обычно это требуется только для некоторых конфигураций IPv6), раскомментируйте `network_mode: host`
+
+**Запуск в Docker 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
+```

docs/TUNING.de.md

@@ -0,0 +1,219 @@
+# Telemt Tuning-Leitfaden: Middle-End und Upstreams
+
+Dieses Dokument beschreibt das aktuelle Laufzeitverhalten für Middle-End (ME) und Upstream-Routing basierend auf:
+- `src/config/types.rs`
+- `src/config/defaults.rs`
+- `src/config/load.rs`
+- `src/transport/upstream.rs`
+
+Die unten angegebenen `Default`-Werte sind Code-Defaults (bei fehlendem Schlüssel), nicht zwingend die Werte aus `config.full.toml`.
+
+## Middle-End-Parameter
+
+### 1) ME-Grundmodus, NAT und STUN
+
+| Parameter | Typ | Default | Einschränkungen / Validierung | Laufzeiteffekt | Beispiel |
+|---|---|---:|---|---|---|
+| `general.use_middle_proxy` | `bool` | `true` | keine | Aktiviert den ME-Transportmodus. Bei `false` wird Direct-Modus verwendet. | `use_middle_proxy = true` |
+| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | Pfad kann `null` sein | Pfad zur Telegram-Infrastrukturdatei `proxy-secret`. | `proxy_secret_path = "proxy-secret"` |
+| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | gültige IP bei gesetztem Wert | Manueller Override der öffentlichen NAT-IP für ME-Adressmaterial. | `middle_proxy_nat_ip = "203.0.113.10"` |
+| `general.middle_proxy_nat_probe` | `bool` | `true` | wird auf `true` erzwungen, wenn `use_middle_proxy=true` | Aktiviert NAT-Probing für ME. | `middle_proxy_nat_probe = true` |
+| `general.stun_nat_probe_concurrency` | `usize` | `8` | muss `> 0` sein | Maximale parallele STUN-Probes während NAT-Erkennung. | `stun_nat_probe_concurrency = 16` |
+| `network.stun_use` | `bool` | `true` | keine | Globaler STUN-Schalter. Bei `false` wird STUN deaktiviert. | `stun_use = true` |
+| `network.stun_servers` | `Vec<String>` | integrierter öffentlicher Pool | Duplikate/leer werden entfernt | Primäre STUN-Serverliste für NAT/Public-Endpoint-Erkennung. | `stun_servers = ["stun1.l.google.com:19302"]` |
+| `network.stun_tcp_fallback` | `bool` | `true` | keine | Aktiviert TCP-Fallback, wenn UDP-STUN blockiert ist. | `stun_tcp_fallback = true` |
+| `network.http_ip_detect_urls` | `Vec<String>` | `ifconfig.me` + `api.ipify.org` | keine | HTTP-Fallback zur öffentlichen IPv4-Erkennung, falls STUN ausfällt. | `http_ip_detect_urls = ["https://api.ipify.org"]` |
+| `general.stun_iface_mismatch_ignore` | `bool` | `false` | keine | Reserviertes Feld in der aktuellen Revision (derzeit kein aktiver Runtime-Verbrauch). | `stun_iface_mismatch_ignore = false` |
+| `timeouts.me_one_retry` | `u8` | `12` | keine | Anzahl schneller Reconnect-Versuche bei Single-Endpoint-DC-Fällen. | `me_one_retry = 6` |
+| `timeouts.me_one_timeout_ms` | `u64` | `1200` | keine | Timeout pro schnellem Einzelversuch (ms). | `me_one_timeout_ms = 1500` |
+
+### 2) Poolgröße, Keepalive und Reconnect-Policy
+
+| Parameter | Typ | Default | Einschränkungen / Validierung | Laufzeiteffekt | Beispiel |
+|---|---|---:|---|---|---|
+| `general.middle_proxy_pool_size` | `usize` | `8` | keine | Zielgröße des aktiven ME-Writer-Pools. | `middle_proxy_pool_size = 12` |
+| `general.middle_proxy_warm_standby` | `usize` | `16` | keine | Reserviertes Kompatibilitätsfeld in der aktuellen Revision (kein aktiver Runtime-Consumer). | `middle_proxy_warm_standby = 16` |
+| `general.me_keepalive_enabled` | `bool` | `true` | keine | Aktiviert periodischen ME-Keepalive/Ping-Traffic. | `me_keepalive_enabled = true` |
+| `general.me_keepalive_interval_secs` | `u64` | `25` | keine | Basisintervall für Keepalive (Sekunden). | `me_keepalive_interval_secs = 20` |
+| `general.me_keepalive_jitter_secs` | `u64` | `5` | keine | Keepalive-Jitter zur Vermeidung synchroner Peaks. | `me_keepalive_jitter_secs = 3` |
+| `general.me_keepalive_payload_random` | `bool` | `true` | keine | Randomisiert Keepalive-Payload-Bytes. | `me_keepalive_payload_random = true` |
+| `general.me_warmup_stagger_enabled` | `bool` | `true` | keine | Aktiviert gestaffeltes Warmup zusätzlicher ME-Verbindungen. | `me_warmup_stagger_enabled = true` |
+| `general.me_warmup_step_delay_ms` | `u64` | `500` | keine | Basisverzögerung zwischen Warmup-Schritten (ms). | `me_warmup_step_delay_ms = 300` |
+| `general.me_warmup_step_jitter_ms` | `u64` | `300` | keine | Zusätzlicher zufälliger Warmup-Jitter (ms). | `me_warmup_step_jitter_ms = 200` |
+| `general.me_reconnect_max_concurrent_per_dc` | `u32` | `8` | keine | Begrenzung paralleler Reconnect-Worker pro DC. | `me_reconnect_max_concurrent_per_dc = 12` |
+| `general.me_reconnect_backoff_base_ms` | `u64` | `500` | keine | Initiales Reconnect-Backoff (ms). | `me_reconnect_backoff_base_ms = 250` |
+| `general.me_reconnect_backoff_cap_ms` | `u64` | `30000` | keine | Maximales Reconnect-Backoff (ms). | `me_reconnect_backoff_cap_ms = 10000` |
+| `general.me_reconnect_fast_retry_count` | `u32` | `16` | keine | Budget für Sofort-Retries vor längerem Backoff. | `me_reconnect_fast_retry_count = 8` |
+
+### 3) Reinit/Hardswap, Secret-Rotation und Degradation
+
+| Parameter | Typ | Default | Einschränkungen / Validierung | Laufzeiteffekt | Beispiel |
+|---|---|---:|---|---|---|
+| `general.hardswap` | `bool` | `true` | keine | Aktiviert generation-basierte Hardswap-Strategie für den ME-Pool. | `hardswap = true` |
+| `general.me_reinit_every_secs` | `u64` | `900` | muss `> 0` sein | Intervall für periodische ME-Reinitialisierung. | `me_reinit_every_secs = 600` |
+| `general.me_hardswap_warmup_delay_min_ms` | `u64` | `1000` | muss `<= me_hardswap_warmup_delay_max_ms` sein | Untere Grenze für Warmup-Dial-Abstände. | `me_hardswap_warmup_delay_min_ms = 500` |
+| `general.me_hardswap_warmup_delay_max_ms` | `u64` | `2000` | muss `> 0` sein | Obere Grenze für Warmup-Dial-Abstände. | `me_hardswap_warmup_delay_max_ms = 1200` |
+| `general.me_hardswap_warmup_extra_passes` | `u8` | `3` | Bereich `[0,10]` | Zusätzliche Warmup-Pässe nach dem Basispass. | `me_hardswap_warmup_extra_passes = 2` |
+| `general.me_hardswap_warmup_pass_backoff_base_ms` | `u64` | `500` | muss `> 0` sein | Basis-Backoff zwischen zusätzlichen Warmup-Pässen. | `me_hardswap_warmup_pass_backoff_base_ms = 400` |
+| `general.me_config_stable_snapshots` | `u8` | `2` | muss `> 0` sein | Anzahl identischer ME-Config-Snapshots vor Apply. | `me_config_stable_snapshots = 3` |
+| `general.me_config_apply_cooldown_secs` | `u64` | `300` | keine | Cooldown zwischen angewendeten ME-Map-Updates. | `me_config_apply_cooldown_secs = 120` |
+| `general.proxy_secret_stable_snapshots` | `u8` | `2` | muss `> 0` sein | Anzahl identischer Secret-Snapshots vor Rotation. | `proxy_secret_stable_snapshots = 3` |
+| `general.proxy_secret_rotate_runtime` | `bool` | `true` | keine | Aktiviert Runtime-Rotation des Proxy-Secrets. | `proxy_secret_rotate_runtime = true` |
+| `general.proxy_secret_len_max` | `usize` | `256` | Bereich `[32,4096]` | Obergrenze für akzeptierte Secret-Länge. | `proxy_secret_len_max = 512` |
+| `general.update_every` | `Option<u64>` | `300` | wenn gesetzt: `> 0`; bei `null`: Legacy-Min-Fallback | Einheitliches Refresh-Intervall für ME-Config + Secret-Updater. | `update_every = 300` |
+| `general.me_pool_drain_ttl_secs` | `u64` | `90` | keine | Zeitraum, in dem stale Writer noch als Fallback zulässig sind. | `me_pool_drain_ttl_secs = 120` |
+| `general.me_pool_min_fresh_ratio` | `f32` | `0.8` | Bereich `[0.0,1.0]` | Coverage-Schwelle vor Drain der alten Generation. | `me_pool_min_fresh_ratio = 0.9` |
+| `general.me_reinit_drain_timeout_secs` | `u64` | `120` | `0` = kein Force-Close; wenn `>0 && < TTL`, dann auf TTL angehoben | Force-Close-Timeout für draining stale Writer. | `me_reinit_drain_timeout_secs = 0` |
+| `general.auto_degradation_enabled` | `bool` | `true` | keine | Reserviertes Kompatibilitätsfeld in aktueller Revision (kein aktiver Runtime-Consumer). | `auto_degradation_enabled = true` |
+| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | keine | Reservierter Kompatibilitäts-Schwellenwert in aktueller Revision (kein aktiver Runtime-Consumer). | `degradation_min_unavailable_dc_groups = 2` |
+
+## Deprecated / Legacy Parameter
+
+| Parameter | Status | Ersatz | Aktuelles Verhalten | Migrationshinweis |
+|---|---|---|---|---|
+| `general.middle_proxy_nat_stun` | Deprecated | `network.stun_servers` | Wird nur dann in `network.stun_servers` gemerged, wenn `network.stun_servers` nicht explizit gesetzt ist. | Wert nach `network.stun_servers` verschieben, Legacy-Key entfernen. |
+| `general.middle_proxy_nat_stun_servers` | Deprecated | `network.stun_servers` | Wird nur dann in `network.stun_servers` gemerged, wenn `network.stun_servers` nicht explizit gesetzt ist. | Werte nach `network.stun_servers` verschieben, Legacy-Key entfernen. |
+| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Nur aktiv, wenn `update_every = null` (Legacy-Fallback). | `general.update_every` explizit setzen, Legacy-Key entfernen. |
+| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Nur aktiv, wenn `update_every = null` (Legacy-Fallback). | `general.update_every` explizit setzen, Legacy-Key entfernen. |
+
+## Wie Upstreams konfiguriert werden
+
+### Upstream-Schema
+
+| Feld | Gilt für | Typ | Pflicht | Default | Bedeutung |
+|---|---|---|---|---|---|
+| `[[upstreams]].type` | alle Upstreams | `"direct" \| "socks4" \| "socks5"` | ja | n/a | Upstream-Transporttyp. |
+| `[[upstreams]].weight` | alle Upstreams | `u16` | nein | `1` | Basisgewicht für weighted-random Auswahl. |
+| `[[upstreams]].enabled` | alle Upstreams | `bool` | nein | `true` | Deaktivierte Einträge werden beim Start ignoriert. |
+| `[[upstreams]].scopes` | alle Upstreams | `String` | nein | `""` | Komma-separierte Scope-Tags für Request-Routing. |
+| `interface` | `direct` | `Option<String>` | nein | `null` | Interface-Name (z. B. `eth0`) oder lokale Literal-IP. |
+| `bind_addresses` | `direct` | `Option<Vec<IpAddr>>` | nein | `null` | Explizite Source-IP-Kandidaten (strikter Vorrang vor `interface`). |
+| `address` | `socks4` | `String` | ja | n/a | SOCKS4-Server (`ip:port` oder `host:port`). |
+| `interface` | `socks4` | `Option<String>` | nein | `null` | Wird nur genutzt, wenn `address` als `ip:port` angegeben ist. |
+| `user_id` | `socks4` | `Option<String>` | nein | `null` | SOCKS4 User-ID für CONNECT. |
+| `address` | `socks5` | `String` | ja | n/a | SOCKS5-Server (`ip:port` oder `host:port`). |
+| `interface` | `socks5` | `Option<String>` | nein | `null` | Wird nur genutzt, wenn `address` als `ip:port` angegeben ist. |
+| `username` | `socks5` | `Option<String>` | nein | `null` | SOCKS5 Benutzername. |
+| `password` | `socks5` | `Option<String>` | nein | `null` | SOCKS5 Passwort. |
+
+### Runtime-Regeln (wichtig)
+
+1. Wenn `[[upstreams]]` fehlt, injiziert der Loader einen Default-`direct`-Upstream.
+2. Scope-Filterung basiert auf exaktem Token-Match:
+- mit Request-Scope -> nur Einträge, deren `scopes` genau dieses Token enthält;
+- ohne Request-Scope -> nur Einträge mit leerem `scopes`.
+3. Unter healthy Upstreams erfolgt die Auswahl per weighted random: `weight * latency_factor`.
+4. Gibt es im gefilterten Set keinen healthy Upstream, wird zufällig aus dem gefilterten Set gewählt.
+5. `direct`-Bind-Auflösung:
+- zuerst `bind_addresses` (nur gleiche IP-Familie wie Target);
+- bei `interface` (Name) + `bind_addresses` wird jede Candidate-IP gegen Interface-Adressen validiert;
+- ungültige Kandidaten werden mit `WARN` verworfen;
+- bleiben keine gültigen Kandidaten übrig, erfolgt unbound direct connect (`bind_ip=None`);
+- wenn `bind_addresses` nicht passt, wird `interface` verwendet (Literal-IP oder Interface-Primäradresse).
+6. Für `socks4/socks5` mit Hostname-`address` ist Interface-Binding nicht unterstützt und wird mit Warnung ignoriert.
+7. Runtime DNS Overrides werden für Hostname-Auflösung bei Upstream-Verbindungen genutzt.
+8. Im ME-Modus wird der gewählte Upstream auch für den ME-TCP-Dial-Pfad verwendet.
+9. Im ME-Modus ist bei `direct` mit bind/interface die STUN-Reflection bind-aware für KDF-Adressmaterial.
+10. Im ME-Modus werden bei SOCKS-Upstream `BND.ADDR/BND.PORT` für KDF verwendet, wenn gültig/öffentlich und gleiche IP-Familie.
+
+## Upstream-Konfigurationsbeispiele
+
+### Beispiel 1: Minimaler direct Upstream
+
+```toml
+[[upstreams]]
+type = "direct"
+weight = 1
+enabled = true
+```
+
+### Beispiel 2: direct mit Interface + expliziten bind IPs
+
+```toml
+[[upstreams]]
+type = "direct"
+interface = "eth0"
+bind_addresses = ["192.168.1.100", "192.168.1.101"]
+weight = 3
+enabled = true
+```
+
+### Beispiel 3: SOCKS5 Upstream mit Authentifizierung
+
+```toml
+[[upstreams]]
+type = "socks5"
+address = "198.51.100.30:1080"
+username = "proxy-user"
+password = "proxy-pass"
+weight = 2
+enabled = true
+```
+
+### Beispiel 4: Gemischte Upstreams mit Scopes
+
+```toml
+[[upstreams]]
+type = "direct"
+weight = 5
+enabled = true
+scopes = ""
+
+[[upstreams]]
+type = "socks5"
+address = "203.0.113.40:1080"
+username = "edge"
+password = "edgepass"
+weight = 3
+enabled = true
+scopes = "premium,me"
+```
+
+### Beispiel 5: ME-orientiertes Tuning-Profil
+
+```toml
+[general]
+use_middle_proxy = true
+proxy_secret_path = "proxy-secret"
+middle_proxy_nat_probe = true
+stun_nat_probe_concurrency = 16
+middle_proxy_pool_size = 12
+me_keepalive_enabled = true
+me_keepalive_interval_secs = 20
+me_keepalive_jitter_secs = 4
+me_reconnect_max_concurrent_per_dc = 12
+me_reconnect_backoff_base_ms = 300
+me_reconnect_backoff_cap_ms = 10000
+me_reconnect_fast_retry_count = 10
+hardswap = true
+me_reinit_every_secs = 600
+me_hardswap_warmup_delay_min_ms = 500
+me_hardswap_warmup_delay_max_ms = 1200
+me_hardswap_warmup_extra_passes = 2
+me_hardswap_warmup_pass_backoff_base_ms = 400
+me_config_stable_snapshots = 3
+me_config_apply_cooldown_secs = 120
+proxy_secret_stable_snapshots = 3
+proxy_secret_rotate_runtime = true
+proxy_secret_len_max = 512
+update_every = 300
+me_pool_drain_ttl_secs = 120
+me_pool_min_fresh_ratio = 0.9
+me_reinit_drain_timeout_secs = 180
+
+[timeouts]
+me_one_retry = 8
+me_one_timeout_ms = 1200
+
+[network]
+stun_use = true
+stun_tcp_fallback = true
+stun_servers = [
+  "stun1.l.google.com:19302",
+  "stun2.l.google.com:19302"
+]
+http_ip_detect_urls = [
+  "https://api.ipify.org",
+  "https://ifconfig.me/ip"
+]
+```

docs/TUNING.en.md

@@ -0,0 +1,219 @@
+# Telemt Tuning Guide: Middle-End and Upstreams
+
+This document describes the current runtime behavior for Middle-End (ME) and upstream routing based on:
+- `src/config/types.rs`
+- `src/config/defaults.rs`
+- `src/config/load.rs`
+- `src/transport/upstream.rs`
+
+Defaults below are code defaults (used when a key is omitted), not necessarily values from `config.full.toml` examples.
+
+## Middle-End Parameters
+
+### 1) Core ME mode, NAT, and STUN
+
+| Parameter | Type | Default | Constraints / validation | Runtime effect | Example |
+|---|---|---:|---|---|---|
+| `general.use_middle_proxy` | `bool` | `true` | none | Enables ME transport mode. If `false`, Direct mode is used. | `use_middle_proxy = true` |
+| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | path may be `null` | Path to Telegram infrastructure proxy-secret file. | `proxy_secret_path = "proxy-secret"` |
+| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | valid IP when set | Manual public NAT IP override for ME address material. | `middle_proxy_nat_ip = "203.0.113.10"` |
+| `general.middle_proxy_nat_probe` | `bool` | `true` | auto-forced to `true` when `use_middle_proxy=true` | Enables ME NAT probing. | `middle_proxy_nat_probe = true` |
+| `general.stun_nat_probe_concurrency` | `usize` | `8` | must be `> 0` | Max parallel STUN probes during NAT discovery. | `stun_nat_probe_concurrency = 16` |
+| `network.stun_use` | `bool` | `true` | none | Global STUN switch. If `false`, STUN probing is disabled. | `stun_use = true` |
+| `network.stun_servers` | `Vec<String>` | built-in public pool | deduplicated + empty values removed | Primary STUN server list for NAT/public endpoint discovery. | `stun_servers = ["stun1.l.google.com:19302"]` |
+| `network.stun_tcp_fallback` | `bool` | `true` | none | Enables TCP fallback path when UDP STUN is blocked. | `stun_tcp_fallback = true` |
+| `network.http_ip_detect_urls` | `Vec<String>` | `ifconfig.me` + `api.ipify.org` | none | HTTP fallback for public IPv4 detection if STUN is unavailable. | `http_ip_detect_urls = ["https://api.ipify.org"]` |
+| `general.stun_iface_mismatch_ignore` | `bool` | `false` | none | Reserved flag in current revision (not consumed by runtime path). | `stun_iface_mismatch_ignore = false` |
+| `timeouts.me_one_retry` | `u8` | `12` | none | Fast reconnect attempts for single-endpoint DC cases. | `me_one_retry = 6` |
+| `timeouts.me_one_timeout_ms` | `u64` | `1200` | none | Timeout per quick single-endpoint attempt (ms). | `me_one_timeout_ms = 1500` |
+
+### 2) Pool size, keepalive, and reconnect policy
+
+| Parameter | Type | Default | Constraints / validation | Runtime effect | Example |
+|---|---|---:|---|---|---|
+| `general.middle_proxy_pool_size` | `usize` | `8` | none | Target active ME writer pool size. | `middle_proxy_pool_size = 12` |
+| `general.middle_proxy_warm_standby` | `usize` | `16` | none | Reserved compatibility field in current revision (no active runtime consumer). | `middle_proxy_warm_standby = 16` |
+| `general.me_keepalive_enabled` | `bool` | `true` | none | Enables periodic ME keepalive/ping traffic. | `me_keepalive_enabled = true` |
+| `general.me_keepalive_interval_secs` | `u64` | `25` | none | Base keepalive interval (seconds). | `me_keepalive_interval_secs = 20` |
+| `general.me_keepalive_jitter_secs` | `u64` | `5` | none | Keepalive jitter to avoid synchronization bursts. | `me_keepalive_jitter_secs = 3` |
+| `general.me_keepalive_payload_random` | `bool` | `true` | none | Randomizes keepalive payload bytes. | `me_keepalive_payload_random = true` |
+| `general.me_warmup_stagger_enabled` | `bool` | `true` | none | Staggers extra ME warmup dials to avoid spikes. | `me_warmup_stagger_enabled = true` |
+| `general.me_warmup_step_delay_ms` | `u64` | `500` | none | Base delay between warmup dial steps (ms). | `me_warmup_step_delay_ms = 300` |
+| `general.me_warmup_step_jitter_ms` | `u64` | `300` | none | Additional random delay for warmup steps (ms). | `me_warmup_step_jitter_ms = 200` |
+| `general.me_reconnect_max_concurrent_per_dc` | `u32` | `8` | none | Limits concurrent reconnect workers per DC in health recovery. | `me_reconnect_max_concurrent_per_dc = 12` |
+| `general.me_reconnect_backoff_base_ms` | `u64` | `500` | none | Initial reconnect backoff (ms). | `me_reconnect_backoff_base_ms = 250` |
+| `general.me_reconnect_backoff_cap_ms` | `u64` | `30000` | none | Maximum reconnect backoff (ms). | `me_reconnect_backoff_cap_ms = 10000` |
+| `general.me_reconnect_fast_retry_count` | `u32` | `16` | none | Immediate retry budget before long backoff behavior. | `me_reconnect_fast_retry_count = 8` |
+
+### 3) Reinit/hardswap, secret rotation, and degradation
+
+| Parameter | Type | Default | Constraints / validation | Runtime effect | Example |
+|---|---|---:|---|---|---|
+| `general.hardswap` | `bool` | `true` | none | Enables generation-based ME hardswap strategy. | `hardswap = true` |
+| `general.me_reinit_every_secs` | `u64` | `900` | must be `> 0` | Periodic ME reinit interval. | `me_reinit_every_secs = 600` |
+| `general.me_hardswap_warmup_delay_min_ms` | `u64` | `1000` | must be `<= me_hardswap_warmup_delay_max_ms` | Lower bound for hardswap warmup dial spacing. | `me_hardswap_warmup_delay_min_ms = 500` |
+| `general.me_hardswap_warmup_delay_max_ms` | `u64` | `2000` | must be `> 0` | Upper bound for hardswap warmup dial spacing. | `me_hardswap_warmup_delay_max_ms = 1200` |
+| `general.me_hardswap_warmup_extra_passes` | `u8` | `3` | must be within `[0,10]` | Additional warmup passes after base pass. | `me_hardswap_warmup_extra_passes = 2` |
+| `general.me_hardswap_warmup_pass_backoff_base_ms` | `u64` | `500` | must be `> 0` | Base backoff between extra warmup passes. | `me_hardswap_warmup_pass_backoff_base_ms = 400` |
+| `general.me_config_stable_snapshots` | `u8` | `2` | must be `> 0` | Number of identical ME config snapshots required before apply. | `me_config_stable_snapshots = 3` |
+| `general.me_config_apply_cooldown_secs` | `u64` | `300` | none | Cooldown between applied ME map updates. | `me_config_apply_cooldown_secs = 120` |
+| `general.proxy_secret_stable_snapshots` | `u8` | `2` | must be `> 0` | Number of identical proxy-secret snapshots required before rotation. | `proxy_secret_stable_snapshots = 3` |
+| `general.proxy_secret_rotate_runtime` | `bool` | `true` | none | Enables runtime proxy-secret rotation. | `proxy_secret_rotate_runtime = true` |
+| `general.proxy_secret_len_max` | `usize` | `256` | must be within `[32,4096]` | Upper limit for accepted proxy-secret length. | `proxy_secret_len_max = 512` |
+| `general.update_every` | `Option<u64>` | `300` | if set: must be `> 0`; if `null`: legacy min fallback | Unified refresh interval for ME config + secret updater. | `update_every = 300` |
+| `general.me_pool_drain_ttl_secs` | `u64` | `90` | none | Time window where stale writers remain fallback-eligible. | `me_pool_drain_ttl_secs = 120` |
+| `general.me_pool_min_fresh_ratio` | `f32` | `0.8` | must be within `[0.0,1.0]` | Coverage threshold before stale generation can be drained. | `me_pool_min_fresh_ratio = 0.9` |
+| `general.me_reinit_drain_timeout_secs` | `u64` | `120` | `0` means no force-close; if `>0 && < TTL` it is bumped to TTL | Force-close timeout for draining stale writers. | `me_reinit_drain_timeout_secs = 0` |
+| `general.auto_degradation_enabled` | `bool` | `true` | none | Reserved compatibility flag in current revision (no active runtime consumer). | `auto_degradation_enabled = true` |
+| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | none | Reserved compatibility threshold in current revision (no active runtime consumer). | `degradation_min_unavailable_dc_groups = 2` |
+
+## Deprecated / Legacy Parameters
+
+| Parameter | Status | Replacement | Current behavior | Migration recommendation |
+|---|---|---|---|---|
+| `general.middle_proxy_nat_stun` | Deprecated | `network.stun_servers` | Merged into `network.stun_servers` only when `network.stun_servers` is not explicitly set. | Move value into `network.stun_servers` and remove legacy key. |
+| `general.middle_proxy_nat_stun_servers` | Deprecated | `network.stun_servers` | Merged into `network.stun_servers` only when `network.stun_servers` is not explicitly set. | Move values into `network.stun_servers` and remove legacy key. |
+| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Used only when `update_every = null` (legacy fallback path). | Set `general.update_every` explicitly and remove legacy key. |
+| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Used only when `update_every = null` (legacy fallback path). | Set `general.update_every` explicitly and remove legacy key. |
+
+## How Upstreams Are Configured
+
+### Upstream schema
+
+| Field | Applies to | Type | Required | Default | Meaning |
+|---|---|---|---|---|---|
+| `[[upstreams]].type` | all upstreams | `"direct" \| "socks4" \| "socks5"` | yes | n/a | Upstream transport type. |
+| `[[upstreams]].weight` | all upstreams | `u16` | no | `1` | Base weight for weighted-random selection. |
+| `[[upstreams]].enabled` | all upstreams | `bool` | no | `true` | Disabled entries are ignored at startup. |
+| `[[upstreams]].scopes` | all upstreams | `String` | no | `""` | Comma-separated scope tags for request-level routing. |
+| `interface` | `direct` | `Option<String>` | no | `null` | Interface name (e.g. `eth0`) or literal local IP for bind selection. |
+| `bind_addresses` | `direct` | `Option<Vec<IpAddr>>` | no | `null` | Explicit local source IP candidates (strict priority over `interface`). |
+| `address` | `socks4` | `String` | yes | n/a | SOCKS4 server endpoint (`ip:port` or `host:port`). |
+| `interface` | `socks4` | `Option<String>` | no | `null` | Used only for SOCKS server `ip:port` dial path. |
+| `user_id` | `socks4` | `Option<String>` | no | `null` | SOCKS4 user ID for CONNECT request. |
+| `address` | `socks5` | `String` | yes | n/a | SOCKS5 server endpoint (`ip:port` or `host:port`). |
+| `interface` | `socks5` | `Option<String>` | no | `null` | Used only for SOCKS server `ip:port` dial path. |
+| `username` | `socks5` | `Option<String>` | no | `null` | SOCKS5 username auth. |
+| `password` | `socks5` | `Option<String>` | no | `null` | SOCKS5 password auth. |
+
+### Runtime rules (important)
+
+1. If `[[upstreams]]` is omitted, loader injects one default `direct` upstream.
+2. Scope filtering is exact-token based:
+- when request scope is set -> only entries whose `scopes` contains that exact token;
+- when request scope is not set -> only entries with empty `scopes`.
+3. Healthy upstreams are selected by weighted random using: `weight * latency_factor`.
+4. If no healthy upstream exists in filtered set, random selection is used among filtered entries.
+5. `direct` bind resolution order:
+- `bind_addresses` candidates (same IP family as target) first;
+- if `interface` is an interface name and `bind_addresses` is set, each candidate IP is validated against addresses currently assigned to that interface;
+- invalid candidates are dropped with `WARN`;
+- if no valid candidate remains, connection falls back to unbound direct connect (`bind_ip=None`);
+- if no `bind_addresses` candidate, `interface` is used (literal IP or resolved interface primary IP).
+6. For `socks4/socks5` with `address` as hostname, interface binding is not supported and is ignored with warning.
+7. Runtime DNS overrides are used for upstream hostname resolution.
+8. In ME mode, the selected upstream is also used for ME TCP dial path.
+9. In ME mode for `direct` upstream with bind/interface, STUN reflection logic is bind-aware for KDF source material.
+10. In ME mode for SOCKS upstream, SOCKS `BND.ADDR/BND.PORT` is used for KDF when it is valid/public for the same family.
+
+## Upstream Configuration Examples
+
+### Example 1: Minimal direct upstream
+
+```toml
+[[upstreams]]
+type = "direct"
+weight = 1
+enabled = true
+```
+
+### Example 2: Direct with interface + explicit bind addresses
+
+```toml
+[[upstreams]]
+type = "direct"
+interface = "eth0"
+bind_addresses = ["192.168.1.100", "192.168.1.101"]
+weight = 3
+enabled = true
+```
+
+### Example 3: SOCKS5 upstream with authentication
+
+```toml
+[[upstreams]]
+type = "socks5"
+address = "198.51.100.30:1080"
+username = "proxy-user"
+password = "proxy-pass"
+weight = 2
+enabled = true
+```
+
+### Example 4: Mixed upstreams with scopes
+
+```toml
+[[upstreams]]
+type = "direct"
+weight = 5
+enabled = true
+scopes = ""
+
+[[upstreams]]
+type = "socks5"
+address = "203.0.113.40:1080"
+username = "edge"
+password = "edgepass"
+weight = 3
+enabled = true
+scopes = "premium,me"
+```
+
+### Example 5: ME-focused tuning profile
+
+```toml
+[general]
+use_middle_proxy = true
+proxy_secret_path = "proxy-secret"
+middle_proxy_nat_probe = true
+stun_nat_probe_concurrency = 16
+middle_proxy_pool_size = 12
+me_keepalive_enabled = true
+me_keepalive_interval_secs = 20
+me_keepalive_jitter_secs = 4
+me_reconnect_max_concurrent_per_dc = 12
+me_reconnect_backoff_base_ms = 300
+me_reconnect_backoff_cap_ms = 10000
+me_reconnect_fast_retry_count = 10
+hardswap = true
+me_reinit_every_secs = 600
+me_hardswap_warmup_delay_min_ms = 500
+me_hardswap_warmup_delay_max_ms = 1200
+me_hardswap_warmup_extra_passes = 2
+me_hardswap_warmup_pass_backoff_base_ms = 400
+me_config_stable_snapshots = 3
+me_config_apply_cooldown_secs = 120
+proxy_secret_stable_snapshots = 3
+proxy_secret_rotate_runtime = true
+proxy_secret_len_max = 512
+update_every = 300
+me_pool_drain_ttl_secs = 120
+me_pool_min_fresh_ratio = 0.9
+me_reinit_drain_timeout_secs = 180
+
+[timeouts]
+me_one_retry = 8
+me_one_timeout_ms = 1200
+
+[network]
+stun_use = true
+stun_tcp_fallback = true
+stun_servers = [
+  "stun1.l.google.com:19302",
+  "stun2.l.google.com:19302"
+]
+http_ip_detect_urls = [
+  "https://api.ipify.org",
+  "https://ifconfig.me/ip"
+]
+```

docs/TUNING.ru.md

@@ -0,0 +1,219 @@
+# Руководство по тюнингу Telemt: Middle-End и Upstreams
+
+Документ описывает актуальное поведение Middle-End (ME) и маршрутизации через upstream на основе:
+- `src/config/types.rs`
+- `src/config/defaults.rs`
+- `src/config/load.rs`
+- `src/transport/upstream.rs`
+
+Значения `Default` ниже — это значения из кода при отсутствии ключа в конфиге, а не обязательно значения из примеров `config.full.toml`.
+
+## Параметры Middle-End
+
+### 1) Базовый режим ME, NAT и STUN
+
+| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
+|---|---|---:|---|---|---|
+| `general.use_middle_proxy` | `bool` | `true` | нет | Включает транспорт ME. При `false` используется Direct-режим. | `use_middle_proxy = true` |
+| `general.proxy_secret_path` | `Option<String>` | `"proxy-secret"` | путь может быть `null` | Путь к инфраструктурному proxy-secret Telegram. | `proxy_secret_path = "proxy-secret"` |
+| `general.middle_proxy_nat_ip` | `Option<IpAddr>` | `null` | валидный IP при задании | Ручной override публичного NAT IP для адресного материала ME. | `middle_proxy_nat_ip = "203.0.113.10"` |
+| `general.middle_proxy_nat_probe` | `bool` | `true` | авто-принудительно `true`, если `use_middle_proxy=true` | Включает NAT probing для ME. | `middle_proxy_nat_probe = true` |
+| `general.stun_nat_probe_concurrency` | `usize` | `8` | должно быть `> 0` | Максимум параллельных STUN-проб при NAT-детекте. | `stun_nat_probe_concurrency = 16` |
+| `network.stun_use` | `bool` | `true` | нет | Глобальный переключатель STUN. При `false` STUN отключен. | `stun_use = true` |
+| `network.stun_servers` | `Vec<String>` | встроенный публичный пул | удаляются дубликаты и пустые значения | Основной список STUN-серверов для NAT/public endpoint discovery. | `stun_servers = ["stun1.l.google.com:19302"]` |
+| `network.stun_tcp_fallback` | `bool` | `true` | нет | Включает TCP fallback, если UDP STUN недоступен. | `stun_tcp_fallback = true` |
+| `network.http_ip_detect_urls` | `Vec<String>` | `ifconfig.me` + `api.ipify.org` | нет | HTTP fallback для определения публичного IPv4 при недоступности STUN. | `http_ip_detect_urls = ["https://api.ipify.org"]` |
+| `general.stun_iface_mismatch_ignore` | `bool` | `false` | нет | Зарезервированный флаг в текущей ревизии (runtime его не использует). | `stun_iface_mismatch_ignore = false` |
+| `timeouts.me_one_retry` | `u8` | `12` | нет | Количество быстрых reconnect-попыток для DC с одним endpoint. | `me_one_retry = 6` |
+| `timeouts.me_one_timeout_ms` | `u64` | `1200` | нет | Таймаут одной быстрой попытки (мс). | `me_one_timeout_ms = 1500` |
+
+### 2) Размер пула, keepalive и reconnect-политика
+
+| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
+|---|---|---:|---|---|---|
+| `general.middle_proxy_pool_size` | `usize` | `8` | нет | Целевой размер активного пула ME-writer соединений. | `middle_proxy_pool_size = 12` |
+| `general.middle_proxy_warm_standby` | `usize` | `16` | нет | Зарезервированное поле совместимости в текущей ревизии (активного runtime-consumer нет). | `middle_proxy_warm_standby = 16` |
+| `general.me_keepalive_enabled` | `bool` | `true` | нет | Включает периодические keepalive/ping кадры ME. | `me_keepalive_enabled = true` |
+| `general.me_keepalive_interval_secs` | `u64` | `25` | нет | Базовый интервал keepalive (сек). | `me_keepalive_interval_secs = 20` |
+| `general.me_keepalive_jitter_secs` | `u64` | `5` | нет | Джиттер keepalive для предотвращения синхронных всплесков. | `me_keepalive_jitter_secs = 3` |
+| `general.me_keepalive_payload_random` | `bool` | `true` | нет | Рандомизирует payload keepalive-кадров. | `me_keepalive_payload_random = true` |
+| `general.me_warmup_stagger_enabled` | `bool` | `true` | нет | Включает staggered warmup дополнительных ME-коннектов. | `me_warmup_stagger_enabled = true` |
+| `general.me_warmup_step_delay_ms` | `u64` | `500` | нет | Базовая задержка между шагами warmup (мс). | `me_warmup_step_delay_ms = 300` |
+| `general.me_warmup_step_jitter_ms` | `u64` | `300` | нет | Дополнительный случайный warmup-джиттер (мс). | `me_warmup_step_jitter_ms = 200` |
+| `general.me_reconnect_max_concurrent_per_dc` | `u32` | `8` | нет | Ограничивает параллельные reconnect worker'ы на один DC. | `me_reconnect_max_concurrent_per_dc = 12` |
+| `general.me_reconnect_backoff_base_ms` | `u64` | `500` | нет | Начальный backoff reconnect (мс). | `me_reconnect_backoff_base_ms = 250` |
+| `general.me_reconnect_backoff_cap_ms` | `u64` | `30000` | нет | Верхняя граница backoff reconnect (мс). | `me_reconnect_backoff_cap_ms = 10000` |
+| `general.me_reconnect_fast_retry_count` | `u32` | `16` | нет | Бюджет быстрых retry до длинного backoff. | `me_reconnect_fast_retry_count = 8` |
+
+### 3) Reinit/hardswap, ротация секрета и деградация
+
+| Параметр | Тип | Default | Ограничения / валидация | Влияние на runtime | Пример |
+|---|---|---:|---|---|---|
+| `general.hardswap` | `bool` | `true` | нет | Включает generation-based стратегию hardswap для ME-пула. | `hardswap = true` |
+| `general.me_reinit_every_secs` | `u64` | `900` | должно быть `> 0` | Интервал периодического reinit ME-пула. | `me_reinit_every_secs = 600` |
+| `general.me_hardswap_warmup_delay_min_ms` | `u64` | `1000` | должно быть `<= me_hardswap_warmup_delay_max_ms` | Нижняя граница пауз между warmup dial попытками. | `me_hardswap_warmup_delay_min_ms = 500` |
+| `general.me_hardswap_warmup_delay_max_ms` | `u64` | `2000` | должно быть `> 0` | Верхняя граница пауз между warmup dial попытками. | `me_hardswap_warmup_delay_max_ms = 1200` |
+| `general.me_hardswap_warmup_extra_passes` | `u8` | `3` | диапазон `[0,10]` | Дополнительные warmup-проходы после базового. | `me_hardswap_warmup_extra_passes = 2` |
+| `general.me_hardswap_warmup_pass_backoff_base_ms` | `u64` | `500` | должно быть `> 0` | Базовый backoff между extra-pass в warmup. | `me_hardswap_warmup_pass_backoff_base_ms = 400` |
+| `general.me_config_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Количество одинаковых snapshot перед применением ME map update. | `me_config_stable_snapshots = 3` |
+| `general.me_config_apply_cooldown_secs` | `u64` | `300` | нет | Cooldown между применёнными обновлениями ME map. | `me_config_apply_cooldown_secs = 120` |
+| `general.proxy_secret_stable_snapshots` | `u8` | `2` | должно быть `> 0` | Количество одинаковых snapshot перед runtime-rotation proxy-secret. | `proxy_secret_stable_snapshots = 3` |
+| `general.proxy_secret_rotate_runtime` | `bool` | `true` | нет | Включает runtime-ротацию proxy-secret. | `proxy_secret_rotate_runtime = true` |
+| `general.proxy_secret_len_max` | `usize` | `256` | диапазон `[32,4096]` | Верхний лимит длины принимаемого proxy-secret. | `proxy_secret_len_max = 512` |
+| `general.update_every` | `Option<u64>` | `300` | если задано: `> 0`; если `null`: fallback на legacy минимум | Единый интервал refresh для ME config + secret updater. | `update_every = 300` |
+| `general.me_pool_drain_ttl_secs` | `u64` | `90` | нет | Время, когда stale writer ещё может использоваться как fallback. | `me_pool_drain_ttl_secs = 120` |
+| `general.me_pool_min_fresh_ratio` | `f32` | `0.8` | диапазон `[0.0,1.0]` | Порог покрытия fresh-поколения перед drain старого поколения. | `me_pool_min_fresh_ratio = 0.9` |
+| `general.me_reinit_drain_timeout_secs` | `u64` | `120` | `0` = без force-close; если `>0 && < TTL`, поднимается до TTL | Таймаут force-close для draining stale writer. | `me_reinit_drain_timeout_secs = 0` |
+| `general.auto_degradation_enabled` | `bool` | `true` | нет | Зарезервированный флаг совместимости в текущей ревизии (активного runtime-consumer нет). | `auto_degradation_enabled = true` |
+| `general.degradation_min_unavailable_dc_groups` | `u8` | `2` | нет | Зарезервированный порог совместимости в текущей ревизии (активного runtime-consumer нет). | `degradation_min_unavailable_dc_groups = 2` |
+
+## Устаревшие / legacy параметры
+
+| Параметр | Статус | Замена | Текущее поведение | Рекомендация миграции |
+|---|---|---|---|---|
+| `general.middle_proxy_nat_stun` | Deprecated | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значение в `network.stun_servers`, legacy-ключ удалить. |
+| `general.middle_proxy_nat_stun_servers` | Deprecated | `network.stun_servers` | Добавляется в `network.stun_servers`, только если `network.stun_servers` не задан явно. | Перенести значения в `network.stun_servers`, legacy-ключ удалить. |
+| `general.proxy_secret_auto_reload_secs` | Deprecated | `general.update_every` | Используется только если `update_every = null` (legacy fallback). | Явно задать `general.update_every`, legacy-ключ удалить. |
+| `general.proxy_config_auto_reload_secs` | Deprecated | `general.update_every` | Используется только если `update_every = null` (legacy fallback). | Явно задать `general.update_every`, legacy-ключ удалить. |
+
+## Как конфигурируются Upstreams
+
+### Схема upstream
+
+| Поле | Применимость | Тип | Обязательно | Default | Назначение |
+|---|---|---|---|---|---|
+| `[[upstreams]].type` | все upstream | `"direct" \| "socks4" \| "socks5"` | да | n/a | Тип upstream транспорта. |
+| `[[upstreams]].weight` | все upstream | `u16` | нет | `1` | Базовый вес в weighted-random выборе. |
+| `[[upstreams]].enabled` | все upstream | `bool` | нет | `true` | Выключенные записи игнорируются на старте. |
+| `[[upstreams]].scopes` | все upstream | `String` | нет | `""` | Список scope-токенов через запятую для маршрутизации. |
+| `interface` | `direct` | `Option<String>` | нет | `null` | Имя интерфейса (например `eth0`) или literal локальный IP. |
+| `bind_addresses` | `direct` | `Option<Vec<IpAddr>>` | нет | `null` | Явные кандидаты source IP (имеют приоритет над `interface`). |
+| `address` | `socks4` | `String` | да | n/a | Адрес SOCKS4 сервера (`ip:port` или `host:port`). |
+| `interface` | `socks4` | `Option<String>` | нет | `null` | Используется только если `address` задан как `ip:port`. |
+| `user_id` | `socks4` | `Option<String>` | нет | `null` | SOCKS4 user ID в CONNECT-запросе. |
+| `address` | `socks5` | `String` | да | n/a | Адрес SOCKS5 сервера (`ip:port` или `host:port`). |
+| `interface` | `socks5` | `Option<String>` | нет | `null` | Используется только если `address` задан как `ip:port`. |
+| `username` | `socks5` | `Option<String>` | нет | `null` | Логин SOCKS5 auth. |
+| `password` | `socks5` | `Option<String>` | нет | `null` | Пароль SOCKS5 auth. |
+
+### Runtime-правила
+
+1. Если `[[upstreams]]` отсутствует, loader добавляет один upstream `direct` по умолчанию.
+2. Scope-фильтрация — по точному совпадению токена:
+- если scope запроса задан -> используются только записи, где `scopes` содержит такой же токен;
+- если scope запроса не задан -> используются только записи с пустым `scopes`.
+3. Среди healthy upstream используется weighted-random выбор: `weight * latency_factor`.
+4. Если в отфильтрованном наборе нет healthy upstream, выбирается случайный из отфильтрованных.
+5. Порядок выбора bind для `direct`:
+- сначала `bind_addresses` (только IP нужного семейства);
+- если одновременно заданы `interface` (имя) и `bind_addresses`, каждый IP проверяется на принадлежность интерфейсу;
+- несовпадающие IP отбрасываются с `WARN`;
+- если валидных IP не осталось, используется unbound direct connect (`bind_ip=None`);
+- если `bind_addresses` не подходит, применяется `interface` (literal IP или адрес интерфейса).
+6. Для `socks4/socks5` с `address` в виде hostname интерфейсный bind не поддерживается и игнорируется с предупреждением.
+7. Runtime DNS overrides применяются к резолвингу hostname в upstream-подключениях.
+8. В ME-режиме выбранный upstream также используется для ME TCP dial path.
+9. В ME-режиме для `direct` upstream с bind/interface STUN-рефлексия выполняется bind-aware для KDF материала.
+10. В ME-режиме для SOCKS upstream используются `BND.ADDR/BND.PORT` для KDF, если адрес валиден/публичен и соответствует IP family.
+
+## Примеры конфигурации Upstreams
+
+### Пример 1: минимальный direct upstream
+
+```toml
+[[upstreams]]
+type = "direct"
+weight = 1
+enabled = true
+```
+
+### Пример 2: direct с interface + явными bind IP
+
+```toml
+[[upstreams]]
+type = "direct"
+interface = "eth0"
+bind_addresses = ["192.168.1.100", "192.168.1.101"]
+weight = 3
+enabled = true
+```
+
+### Пример 3: SOCKS5 upstream с аутентификацией
+
+```toml
+[[upstreams]]
+type = "socks5"
+address = "198.51.100.30:1080"
+username = "proxy-user"
+password = "proxy-pass"
+weight = 2
+enabled = true
+```
+
+### Пример 4: смешанные upstream с scopes
+
+```toml
+[[upstreams]]
+type = "direct"
+weight = 5
+enabled = true
+scopes = ""
+
+[[upstreams]]
+type = "socks5"
+address = "203.0.113.40:1080"
+username = "edge"
+password = "edgepass"
+weight = 3
+enabled = true
+scopes = "premium,me"
+```
+
+### Пример 5: профиль тюнинга под ME
+
+```toml
+[general]
+use_middle_proxy = true
+proxy_secret_path = "proxy-secret"
+middle_proxy_nat_probe = true
+stun_nat_probe_concurrency = 16
+middle_proxy_pool_size = 12
+me_keepalive_enabled = true
+me_keepalive_interval_secs = 20
+me_keepalive_jitter_secs = 4
+me_reconnect_max_concurrent_per_dc = 12
+me_reconnect_backoff_base_ms = 300
+me_reconnect_backoff_cap_ms = 10000
+me_reconnect_fast_retry_count = 10
+hardswap = true
+me_reinit_every_secs = 600
+me_hardswap_warmup_delay_min_ms = 500
+me_hardswap_warmup_delay_max_ms = 1200
+me_hardswap_warmup_extra_passes = 2
+me_hardswap_warmup_pass_backoff_base_ms = 400
+me_config_stable_snapshots = 3
+me_config_apply_cooldown_secs = 120
+proxy_secret_stable_snapshots = 3
+proxy_secret_rotate_runtime = true
+proxy_secret_len_max = 512
+update_every = 300
+me_pool_drain_ttl_secs = 120
+me_pool_min_fresh_ratio = 0.9
+me_reinit_drain_timeout_secs = 180
+
+[timeouts]
+me_one_retry = 8
+me_one_timeout_ms = 1200
+
+[network]
+stun_use = true
+stun_tcp_fallback = true
+stun_servers = [
+  "stun1.l.google.com:19302",
+  "stun2.l.google.com:19302"
+]
+http_ip_detect_urls = [
+  "https://api.ipify.org",
+  "https://ifconfig.me/ip"
+]
+```

docs/XRAY-SINGBOX-ROUTING.ru.md

@@ -0,0 +1,321 @@
+# SNI-маршрутизация в xray-core / sing-box + TLS-fronting
+
+## Термины (в контексте этого кейса)
+
+- **TLS-fronting домен** — домен, который фигурирует в TLS ClientHello как **SNI** (например, `petrovich.ru`): он используется как "маска" на L7 и как ключ маршрутизации в прокси-роутере.
+- **xray-core / sing-box** — локальный или удалённый L7/TLS-роутер (прокси), который:
+  1) принимает входящее TCP/TLS-соединение,
+  2) читает TLS ClientHello,
+  3) извлекает SNI,
+  4) по SNI выбирает outbound/апстрим,
+  5) устанавливает новое TCP-соединение к целевому хосту уже **от себя**.
+- **SNI (Server Name Indication)** — поле в TLS ClientHello, где клиент Telegram сообщает доменное имя для "маскировки"
+- **DNS-resolve на стороне L7-роутера** — если выходной адрес задан доменом (или роутер решил "всё равно идти по SNI"), то DNS резолвится **на стороне xray/sing-box**, а не на стороне Telegram-клиента
+
+---
+
+## Ключевая идея: куда на самом деле идёт соединение решает не то, что вы указали клиенту, а то как L7-роутер трактует SNI
+
+Механика:
+
+1) Telegram-клиенту вы можете указать **IP/домен telemt**,как "сервер".
+2) Между клиентом и telemt стоит xray-core/sing-box, который принимает TCP, читает TLS ClientHello и видит **SNI=petrovich.ru**
+3) Дальше роутер говорит: "Вижу SNI - направить на апстрим/маршрут N"
+4) И устанавливает исходящее соединение не "по тому IP, который пользователь подразумевал", а **по домену из SNI** (или по сопоставлению SNI→outbound), используя для определния его IP собственный DNS-кеш или резолвер
+5) `petrovich.ru` по A-записи указывает **не на IP telemt**, а значит при L7-маршрутизации трафик уйдёт на "оригинальный" сайт за этим доменом, а не в telemt: Telegram-клиент, естественно, не сможет получить ожидаемое поведение, потому что ответить с handshake на той стороне некому
+
+---
+
+## Схема №1 "Как это НЕ работает"
+
+```text
+Telegram Client
+   |
+   |  (указан IP/домен telemt)
+   v
+telemt instance
+````
+
+Ожидание: "я указал telemt -> значит трафик попадёт в telemt" - **нет!**
+
+---
+
+## Схема №2. "Как это реально работает с TLS/L7-роутером и SNI"
+
+```text
+Telegram Client
+   |
+   | 1) TCP/TLS connection: 
+   |    - ClientHello: 
+   |      - SNI=petrovich.ru
+   v
+xray-core / sing-box / любой L7 router
+   |
+   | 2) читает ClientHello -> вытаскивает SNI
+   | 3) выбирает маршрут по SNI
+   | 4) делает DNS для petrovich.ru 
+   | 5) подключается к полученному IP по TLS с этим SNI
+   v
+"Оригинальный" сайт, A-запись которого не на telemt
+   |
+   X  не telemt -> Telegram-клиент не коннектится как ожидалось
+```
+
+---
+
+## Почему указанный в клиенте IP/домен telemt "не спасает"
+
+Потому что в таком режиме xray/sing-box выступает как **точка терминации TCP/TLS**, можно сказать - TLS-инспектор на уровне ClientHello, это означает:
+
+* TCP-сессия от Telegram-клиента заканчивается на xray/sing-box
+* Дальше создаётся **новая** TCP-сессия "от имени" xray/sing-box к апстриму
+* Выбор апстрима делается правилами роутинга, а в TLS-сценариях самый удобный и распространённый ключ — **SNI**
+
+То есть, "куда идти дальше" определяется логикой L7-роутера:
+
+* либо правилами вида `if SNI == petrovich.ru -> outbound X`,
+* либо более "автоматическим" поведением: `подключаться к тому хосту, который указан в SNI`,
+* плюс кэш DNS и собственные резолверы роутера
+
+---
+
+## Что именно извлекается из TLS ClientHello и почему этого достаточно
+
+TLS ClientHello отправляется **в начале** TLS-сессии и, в классическом TLS без ECH, содержит SNI в открытом виде.
+
+Упрощённо:
+
+```text
+ClientHello:
+  - supported_versions
+  - cipher_suites
+  - extensions:
+      - server_name: petrovich.ru   <-- SNI
+      - alpn: h2/http1.1/...
+      - ...
+```
+
+Роутеру не нужно расшифровывать трафик и завершать TLS "как сервер" — часто достаточно просто прочитать первые пакеты и распарсить ClientHello, чтобы получить SNI и принять решение
+
+---
+
+## Типовой алгоритм SNI-роутинга
+
+1. Принять входящий TCP.
+2. Подождать первые байты.
+3. Определить протокол:
+
+   * если видим TLS ClientHello → парсим SNI/ALPN
+4. Применить route rules:
+
+   * match по `server_name` / `domain` / `tls.sni`
+5. Выбрать outbound:
+
+   * direct / proxy / specific upstream / detour
+6. Установить исходящее соединение:
+
+   * либо на фиксированный IP:порт,
+   * либо на домен через DNS-resolve на стороне роутера
+7. Начать проксирование данных между входом и выходом
+
+---
+
+## Почему "A-запись фронтинг-домена не на telemt" ломает кейс
+
+### Ситуация
+
+* В ClientHello: `SNI = petrovich.ru`
+* DNS: `petrovich.ru -> 203.0.113.77`  - "оригинальный" сайт
+* telemt живёт на: `198.51.100.10`
+
+### Что делает роутер
+
+* Видит SNI `petrovich.ru`
+* Либо:
+
+  * (а) напрямую коннектится к `petrovich.ru:443`, резолвя A-запись в `203.0.113.77`,
+  * либо:
+  * (б) выбирает outbound, который указывает на `petrovich.ru` как destination,
+  * либо:
+  * (в) делает sniffing/override destination по SNI
+
+В итоге исходящий коннект идёт на `203.0.113.77:443`, а не на telemt!
+Другой сервер, другой протокол, другая логика, где telemt не участвует
+
+---
+
+## "Где именно происходит подмена destination на SNI"
+
+Это зависит от конфигурации, но типовые варианты:
+
+### Вариант A: outbound задан доменом (и он совпадает с SNI)
+
+Правило по SNI выбирает outbound, у которого destination задан доменом фронтинга, 
+тогда DNS резолвится на стороне роутера и вы уходите на "оригинальный" хост
+
+### Вариант B: destination override / sniffing
+
+Роутер "снифает" SNI и **перезаписывает** destination на домен из SNI (даже если вход изначально был на IP telemt),
+это особенно коварно: пользователь видит "я подключаюсь к IP telemt", но роутер после sniffing решает иначе
+
+### Вариант C: split DNS / кеш / независимый резолвер
+
+Даже если клиент "где-то" резолвит иначе, это не важно: конечный DNS для исходящего коннекта — на стороне xray/sing-box,
+который может иметь:
+
+* свой DoH/DoT,
+* свой кеш,
+* свои правила fake-ip / system resolver,
+* и, как следствие, своя "карта" **домен/SNI -> IP**
+
+---
+
+## Признаки того, что трафик "утёк на оригинал", а не попал в telemt
+
+* На стороне telemt отсутствуют входящие соединения/логи
+* На стороне роутера видно, что destination — домен фронтинга, а IP соответствует публичному сайту
+* TLS-метрики/сертификат на выходе соответствует "оригинальному" сайту в записах трафика
+* Telegram-клиент получает неожиданный тип ответов/ошибку handshaking/timeout в debug-режиме
+
+---
+
+## Best-practice решение для этого кейса: свой домен фронтинга + заглушка на telemt + Let's Encrypt
+
+### Цель
+
+Сделать так, чтобы:
+
+* SNI (фронтинг-домен) **резолвился в IP telemt**,
+* на IP telemt реально был TLS-сервис с валидным сертификатом под этот домен,
+* даже если кто-то "попробует открыть домен как сайт", он увидит нормальную заглушку, а не "пустоту"
+
+### Что это даёт
+
+* xray/sing-box, маршрутизируя по SNI, будет неизбежно приходить на telemt, потому что DNS(SNI-домен) → IP telemt
+* Внешний вид будет правдоподобным: обычный домен с обычным сертификатом
+* Устойчивость: меньше сюрпризов от DNS-кеша/перерезолва/"умных" правил роутера
+
+---
+
+## Рекомендуемая схема (целевое состояние)
+
+```text
+Telegram Client
+   |
+   | TLS ClientHello: SNI = hello.example.com
+   v
+xray-core / sing-box
+   |
+   | Route by SNI -> outbound -> connect to hello.example.com:443
+   | DNS(hello.example.com) = IP telemt
+   v
+telemt instance (IP telemt)
+   |
+   | TLS cert for hello.example.com (Let's Encrypt)
+   | + сайт-заглушка / health endpoint
+   v
+OK
+```
+
+---
+
+## Практический чеклист (минимальный)
+
+1. Купить/иметь домен: `hello.example.com`
+2. В DNS:
+
+   * `A hello.example.com -> <IP telemt>`
+   * (опционально) AAAA, если используете IPv6 и он стабилен
+3. На telemt-хосте:
+
+   * поднять TLS endpoint на 443 с валидным сертификатом LE под `hello.example.com`
+   * отдать "заглушку" (например, статический сайт), чтобы домен выглядел как обычный веб-сервис
+4. В xray/sing-box правилах:
+
+   * маршрутизировать нужный трафик по SNI = `hello.example.com` в "правильный" outbound (к telemt)
+   * избегать конфигураций, где destination override уводит на чужой домен
+5. Важно:
+
+   * если вы используете кеш DNS на роутере — сбросить/обновить его после смены A-записи
+
+---
+
+## Пояснение про сайт-заглушку
+
+Для эмуляции TLS, telemt имеет подсистему TLS-F в `src/tls_front`:
+- её модуль - fetcher, собирает TLS-профили, чтоб максимально поведенчески корректно повторять TLS конкретно указанного сайта
+
+Когда вы указываете сайт, который не отвечает по TLS:
+- fetcher не может собрать TLS-профиль и происходит fallback на `fake_cert_len` - примитивный алгоритм,
+- он забивает служебную информацию TLS рандомными байтами,
+- простые системы DPI не распознают это
+- однако, продвинутые системы, такие как nEdge или Fraud Control в сетях мобильной связи легко заблокируют или замедлят такой трафик
+
+Создав сайт-заглушку с Let's Encrypt сертификатом, вы даёте TLS-F возможность получить данные сертификата и корректно его "повторять" в дальнейшем
+
+---
+
+## Вариант конфиг-подхода: "SNI строго привязываем к telemt - фиксированный IP"
+
+Чтобы полностью исключить зависимость от DNS если вам это нужно, можно сделать outbound, который ходит на **фиксированный IP telemt**, но при этом выставляет SNI/Host как `hello.example.com`.
+
+Идея:
+
+* destination: `IP:443`
+* SNI: `hello.example.com`
+* сертификат на telemt именно под `hello.example.com`
+
+Так вы получаете:
+
+* TLS выглядит корректно, ведь SNI совпадает с сертификатом,
+* а routing никогда не уйдёт на "оригинал", потому что A-запись указывает на telemt и контроллируется вами!
+
+Но в вашем описании проблема как раз в том, что роутер "сам решает по SNI и резолвит домен", поэтому самый универсальный вариант — сделать так, чтобы DNS всегда приводил в telemt
+
+---
+
+## Пример логики правил на псевдоконфиге L7-роутера
+
+```text
+if inbound is TLS and sni == "hello.example.com":
+    route -> outbound "telemt"
+else:
+    route -> outbound "default"
+```
+
+Outbound `telemt`:
+
+* destination: `hello.example.com:443`
+* TLS enabled
+* SNI: `hello.example.com`
+
+---
+
+## Отдельно: что может неожиданно сломать даже "правильный" DNS
+
+* **Кеширование DNS** на xray/sing-box или на системном резолвере, особенно при смене A-записи
+* **Split-horizon DNS**: разные ответы внутри/снаружи, попытки подмены/терминирования в других точках
+* **IPv6**: если есть AAAA и он указывает не туда, роутер может предпочесть IPv6: помните, что поддержка v6 нестабильна и не рекомендуется в prod
+* **DoH/DoT** на роутере: он может резолвить не тем резолвером, которым вы проверяли
+
+Минимальная гигиена:
+
+* контролировать A/AAAA,
+* держать TTL разумным,
+* проверять, каким резолвером пользуется именно роутер,
+* при необходимости отключить/ограничить destination override
+
+---
+
+## Итог
+
+В режиме TLS-fronting с xray-core/sing-box как L7/TLS-роутером **SNI становится приоритетным "source-of-truth" для маршрутизации**
+
+Если фронтинг-домен по DNS указывает не на IP telemt, роутер честно уводит трафик на "оригинальный" сайт, потому что он строит исходящее соединение "по SNI"
+
+Надёжное решение для этого кейса:
+
+* использовать **свой домен** для фронтинга,
+* направить его **A/AAAA** на IP telemt,
+* поднять на telemt **TLS-сервис с Let’s Encrypt сертификатом** под этот домен,
+* (желательно) держать **сайт-заглушку**, чтобы 443 выглядел как обычный HTTPS

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

@@ -0,0 +1,278 @@
+# 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:
+
+```toml
+[censorship]
+tls_domain = "umweltschutz.de"
+```
+
+Этот домен используется клиентом как SNI в ClientHello
+
+### 3 Сервер-заглушка
+
+Вы поднимаете обычный HTTPS-сервер, например **nginx**, с сертификатом для этого домена.
+
+Он может работать:
+
+- на том же сервере
+- на другом сервере
+- на другом порту
+
+В конфигурации Telemt:
+
+```toml
+[censorship]
+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-режиме
+
+# Использование чужого домена
+
+Можно использовать и внешний сайт.
+
+Например:
+
+```toml
+[censorship]
+tls_domain = "github.com"
+mask_host = "github.com"
+mask_port = 443
+```
+
+или
+
+```toml
+[censorship]
+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/middle-end/KDF-internals/MIDDLE-END-KDF.de.md

@@ -0,0 +1,40 @@
+# Middle-End Proxy
+
+## KDF-Adressierung — Implementierungs-FAQ
+
+### Benötigt die C-Referenzimplementierung sowohl externe IP-Adresse als auch Port für die KDF?
+
+Ja.
+
+In der C-Referenzimplementierung werden **sowohl IP-Adresse als auch Port in die KDF einbezogen** — auf beiden Seiten der Verbindung.
+
+In `aes_create_keys()` enthält der KDF-Input:
+
+- `server_ip + client_port`
+- `client_ip + server_port`
+- sowie Secret / Nonces
+
+Für IPv6:
+
+- IPv4-Felder werden auf 0 gesetzt
+- IPv6-Adressen werden ergänzt
+
+Die **Ports bleiben weiterhin Bestandteil der KDF**.
+
+> Wenn sich externe IP oder Port (z. B. durch NAT, SOCKS oder Proxy) von den erwarteten Werten unterscheiden, entstehen unterschiedliche Schlüssel — der Handshake schlägt fehl.
+
+---
+
+### Kann der Port aus der KDF ausgeschlossen werden (z. B. durch Port = 0)?
+
+**Nein!**
+
+Die C-Referenzimplementierung enthält **keine Möglichkeit, den Port zu ignorieren**:
+- `client_port` und `server_port` sind fester Bestandteil der KDF
+- Es werden immer reale Socket-Ports übergeben:
+  - `c->our_port`
+  - `c->remote_port`
+
+Falls ein Port den Wert `0` hat, wird er dennoch als `0` in die KDF übernommen.
+
+Eine „Port-Ignore“-Logik existiert nicht.

docs/middle-end/KDF-internals/MIDDLE-END-KDF.en.md

@@ -0,0 +1,41 @@
+# Middle-End Proxy
+
+## KDF Addressing — Implementation FAQ
+
+### Does the C-implementation require both external IP address and port for the KDF?
+
+**Yes!**
+
+In the C reference implementation, **both IP address and port are included in the KDF input** from both sides of the connection.
+
+Inside `aes_create_keys()`, the KDF input explicitly contains:
+
+- `server_ip + client_port`
+- `client_ip + server_port`
+- followed by shared secret / nonces
+
+For IPv6:
+
+- IPv4 fields are zeroed
+- IPv6 addresses are inserted
+
+However, **client_port and server_port remain part of the KDF regardless of IP version**.
+
+> If externally observed IP or port (e.g. due to NAT, SOCKS, or proxy traversal) differs from what the peer expects, the derived keys will not match and the handshake will fail.
+
+---
+
+### Can port be excluded from KDF (e.g. by using port = 0)?
+
+**No!**
+
+The C-implementation provides **no mechanism to ignore the port**:
+
+- `client_port` and `server_port` are explicitly included in the KDF input
+- Real socket ports are always passed:
+  - `c->our_port`
+  - `c->remote_port`
+
+If a port is `0`, it is still incorporated into the KDF as `0`.
+
+There is **no conditional logic to exclude ports**

docs/middle-end/KDF-internals/MIDDLE-END-KDF.ru.md

@@ -0,0 +1,41 @@
+# Middle-End Proxy
+
+## KDF Addressing — FAQ по реализации
+
+### Требует ли C-референсная реализация KDF внешний IP и порт?
+
+**Да**
+
+В C-референсе **в KDF участвуют и IP-адрес, и порт** — с обеих сторон соединения.
+
+В `aes_create_keys()` в строку KDF входят:
+
+- `server_ip + client_port`
+- `client_ip + server_port`
+- далее secret / nonces
+
+Для IPv6:
+
+- IPv4-поля заполняются нулями
+- добавляются IPv6-адреса
+
+Однако **порты client_port и server_port всё равно участвуют в KDF**.
+
+> Если внешний IP или порт (например, из-за NAT, SOCKS или прокси) не совпадает с ожидаемым другой стороной — ключи расходятся и handshake ломается.
+
+---
+
+### Можно ли исключить порт из KDF (например, установив порт = 0)?
+
+**Нет.**
+
+В C-референсе **нет механики отключения порта**.
+
+- `client_port` и `server_port` явно включены в KDF
+- Передаются реальные порты сокета:
+  - `c->our_port`
+  - `c->remote_port`
+
+Если порт равен `0`, он всё равно попадёт в KDF как `0`.
+
+Отдельной логики «игнорировать порт» не предусмотрено.

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

@@ -0,0 +1,115 @@
+#!/bin/sh
+set -eu
+
+REPO="${REPO:-telemt/telemt}"
+BIN_NAME="${BIN_NAME:-telemt}"
+VERSION="${1:-${VERSION:-latest}}"
+INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}"
+
+say() {
+    printf '%s\n' "$*"
+}
+
+die() {
+    printf 'Error: %s\n' "$*" >&2
+    exit 1
+}
+
+need_cmd() {
+    command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"
+}
+
+detect_os() {
+    os="$(uname -s)"
+    case "$os" in
+        Linux) printf 'linux\n' ;;
+        OpenBSD) printf 'openbsd\n' ;;
+        *) printf '%s\n' "$os" ;;
+    esac
+}
+
+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
+}
+
+detect_libc() {
+    case "$(ldd --version 2>&1 || true)" in
+        *musl*) printf 'musl\n' ;;
+        *) printf 'gnu\n' ;;
+    esac
+}
+
+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
+}
+
+install_binary() {
+    src="$1"
+    dst="$2"
+
+    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
+}
+
+need_cmd uname
+need_cmd tar
+need_cmd mktemp
+need_cmd grep
+need_cmd install
+
+ARCH="$(detect_arch)"
+OS="$(detect_os)"
+
+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,496 @@
+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_drain_soft_evict_total: u64,
+    pub(super) pool_drain_soft_evict_writer_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_ratio: f64,
+    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_ratio: f64,
+    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_drain_soft_evict_enabled: bool,
+    pub(super) me_pool_drain_soft_evict_grace_secs: u64,
+    pub(super) me_pool_drain_soft_evict_per_writer: u8,
+    pub(super) me_pool_drain_soft_evict_budget_per_core: u16,
+    pub(super) me_pool_drain_soft_evict_cooldown_ms: 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,536 @@
+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_ratio: f64,
+    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_ratio: dc.coverage_ratio,
+                    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,548 @@
+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_drain_soft_evict_total: stats.get_pool_drain_soft_evict_total(),
+            pool_drain_soft_evict_writer_total: stats.get_pool_drain_soft_evict_writer_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_ratio: status.coverage_ratio,
+            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_ratio: entry.coverage_ratio,
+                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_drain_soft_evict_enabled: runtime.me_pool_drain_soft_evict_enabled,
+        me_pool_drain_soft_evict_grace_secs: runtime.me_pool_drain_soft_evict_grace_secs,
+        me_pool_drain_soft_evict_per_writer: runtime.me_pool_drain_soft_evict_per_writer,
+        me_pool_drain_soft_evict_budget_per_core: runtime.me_pool_drain_soft_evict_budget_per_core,
+        me_pool_drain_soft_evict_cooldown_ms: runtime.me_pool_drain_soft_evict_cooldown_ms,
+        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_ratio: 0.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/cli.rs

@@ -0,0 +1,315 @@
+//! CLI commands: --init (fire-and-forget setup)
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use rand::Rng;
+
+/// Options for the init command
+pub struct InitOptions {
+    pub port: u16,
+    pub domain: String,
+    pub secret: Option<String>,
+    pub username: String,
+    pub config_dir: PathBuf,
+    pub no_start: bool,
+}
+
+impl Default for InitOptions {
+    fn default() -> Self {
+        Self {
+            port: 443,
+            domain: "www.google.com".to_string(),
+            secret: None,
+            username: "user".to_string(),
+            config_dir: PathBuf::from("/etc/telemt"),
+            no_start: false,
+        }
+    }
+}
+
+/// Parse --init subcommand options from CLI args.
+///
+/// Returns `Some(InitOptions)` if `--init` was found, `None` otherwise.
+pub fn parse_init_args(args: &[String]) -> Option<InitOptions> {
+    if !args.iter().any(|a| a == "--init") {
+        return None;
+    }
+    
+    let mut opts = InitOptions::default();
+    let mut i = 0;
+    
+    while i < args.len() {
+        match args[i].as_str() {
+            "--port" => {
+                i += 1;
+                if i < args.len() {
+                    opts.port = args[i].parse().unwrap_or(443);
+                }
+            }
+            "--domain" => {
+                i += 1;
+                if i < args.len() {
+                    opts.domain = args[i].clone();
+                }
+            }
+            "--secret" => {
+                i += 1;
+                if i < args.len() {
+                    opts.secret = Some(args[i].clone());
+                }
+            }
+            "--user" => {
+                i += 1;
+                if i < args.len() {
+                    opts.username = args[i].clone();
+                }
+            }
+            "--config-dir" => {
+                i += 1;
+                if i < args.len() {
+                    opts.config_dir = PathBuf::from(&args[i]);
+                }
+            }
+            "--no-start" => {
+                opts.no_start = true;
+            }
+            _ => {}
+        }
+        i += 1;
+    }
+    
+    Some(opts)
+}
+
+/// Run the fire-and-forget setup.
+pub fn run_init(opts: InitOptions) -> Result<(), Box<dyn std::error::Error>> {
+    eprintln!("[telemt] Fire-and-forget setup");
+    eprintln!();
+    
+    // 1. Generate or validate secret
+    let secret = match opts.secret {
+        Some(s) => {
+            if s.len() != 32 || !s.chars().all(|c| c.is_ascii_hexdigit()) {
+                eprintln!("[error] Secret must be exactly 32 hex characters");
+                std::process::exit(1);
+            }
+            s
+        }
+        None => generate_secret(),
+    };
+    
+    eprintln!("[+] Secret: {}", secret);
+    eprintln!("[+] User:   {}", opts.username);
+    eprintln!("[+] Port:   {}", opts.port);
+    eprintln!("[+] Domain: {}", opts.domain);
+    
+    // 2. Create config directory
+    fs::create_dir_all(&opts.config_dir)?;
+    let config_path = opts.config_dir.join("config.toml");
+    
+    // 3. Write config
+    let config_content = generate_config(&opts.username, &secret, opts.port, &opts.domain);
+    fs::write(&config_path, &config_content)?;
+    eprintln!("[+] Config written to {}", config_path.display());
+    
+    // 4. Write systemd unit
+    let exe_path = std::env::current_exe()
+        .unwrap_or_else(|_| PathBuf::from("/usr/local/bin/telemt"));
+    
+    let unit_path = Path::new("/etc/systemd/system/telemt.service");
+    let unit_content = generate_systemd_unit(&exe_path, &config_path);
+    
+    match fs::write(unit_path, &unit_content) {
+        Ok(()) => {
+            eprintln!("[+] Systemd unit written to {}", unit_path.display());
+        }
+        Err(e) => {
+            eprintln!("[!] Cannot write systemd unit (run as root?): {}", e);
+            eprintln!("[!] Manual unit file content:");
+            eprintln!("{}", unit_content);
+            
+            // Still print links and config
+            print_links(&opts.username, &secret, opts.port, &opts.domain);
+            return Ok(());
+        }
+    }
+    
+    // 5. Reload systemd
+    run_cmd("systemctl", &["daemon-reload"]);
+    
+    // 6. Enable service
+    run_cmd("systemctl", &["enable", "telemt.service"]);
+    eprintln!("[+] Service enabled");
+    
+    // 7. Start service (unless --no-start)
+    if !opts.no_start {
+        run_cmd("systemctl", &["start", "telemt.service"]);
+        eprintln!("[+] Service started");
+        
+        // Brief delay then check status
+        std::thread::sleep(std::time::Duration::from_secs(1));
+        let status = Command::new("systemctl")
+            .args(["is-active", "telemt.service"])
+            .output();
+        
+        match status {
+            Ok(out) if out.status.success() => {
+                eprintln!("[+] Service is running");
+            }
+            _ => {
+                eprintln!("[!] Service may not have started correctly");
+                eprintln!("[!] Check: journalctl -u telemt.service -n 20");
+            }
+        }
+    } else {
+        eprintln!("[+] Service not started (--no-start)");
+        eprintln!("[+] Start manually: systemctl start telemt.service");
+    }
+    
+    eprintln!();
+    
+    // 8. Print links
+    print_links(&opts.username, &secret, opts.port, &opts.domain);
+    
+    Ok(())
+}
+
+fn generate_secret() -> String {
+    let mut rng = rand::rng();
+    let bytes: Vec<u8> = (0..16).map(|_| rng.random::<u8>()).collect();
+    hex::encode(bytes)
+}
+
+fn generate_config(username: &str, secret: &str, port: u16, domain: &str) -> String {
+    format!(
+r#"# Telemt MTProxy — auto-generated config
+# Re-run `telemt --init` to regenerate
+
+show_link = ["{username}"]
+
+[general]
+# prefer_ipv6 is deprecated; use [network].prefer
+prefer_ipv6 = false
+fast_mode = true
+use_middle_proxy = false
+log_level = "normal"
+desync_all_full = false
+update_every = 43200
+hardswap = false
+me_pool_drain_ttl_secs = 90
+me_pool_min_fresh_ratio = 0.8
+me_reinit_drain_timeout_secs = 120
+
+[network]
+ipv4 = true
+ipv6 = true
+prefer = 4
+multipath = false
+
+[general.modes]
+classic = false
+secure = false
+tls = true
+
+[server]
+port = {port}
+listen_addr_ipv4 = "0.0.0.0"
+listen_addr_ipv6 = "::"
+
+[[server.listeners]]
+ip = "0.0.0.0"
+# reuse_allow = false # Set true only when intentionally running multiple telemt instances on same port
+
+[[server.listeners]]
+ip = "::"
+
+[timeouts]
+client_handshake = 15
+tg_connect = 10
+client_keepalive = 60
+client_ack = 300
+
+[censorship]
+tls_domain = "{domain}"
+mask = true
+mask_port = 443
+fake_cert_len = 2048
+tls_full_cert_ttl_secs = 90
+
+[access]
+replay_check_len = 65536
+replay_window_secs = 1800
+ignore_time_skew = false
+
+[access.users]
+{username} = "{secret}"
+
+[[upstreams]]
+type = "direct"
+enabled = true
+weight = 10
+"#,
+        username = username,
+        secret = secret,
+        port = port,
+        domain = domain,
+    )
+}
+
+fn generate_systemd_unit(exe_path: &Path, config_path: &Path) -> String {
+    format!(
+r#"[Unit]
+Description=Telemt MTProxy
+Documentation=https://github.com/nicepkg/telemt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart={exe} {config}
+Restart=always
+RestartSec=5
+LimitNOFILE=65535
+# Security hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/etc/telemt
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+"#,
+        exe = exe_path.display(),
+        config = config_path.display(),
+    )
+}
+
+fn run_cmd(cmd: &str, args: &[&str]) {
+    match Command::new(cmd).args(args).output() {
+        Ok(output) => {
+            if !output.status.success() {
+                let stderr = String::from_utf8_lossy(&output.stderr);
+                eprintln!("[!] {} {} failed: {}", cmd, args.join(" "), stderr.trim());
+            }
+        }
+        Err(e) => {
+            eprintln!("[!] Failed to run {} {}: {}", cmd, args.join(" "), e);
+        }
+    }
+}
+
+fn print_links(username: &str, secret: &str, port: u16, domain: &str) {
+    let domain_hex = hex::encode(domain);
+    
+    println!("=== Proxy Links ===");
+    println!("[{}]", username);
+    println!("  EE-TLS:  tg://proxy?server=YOUR_SERVER_IP&port={}&secret=ee{}{}", 
+        port, secret, domain_hex);
+    println!();
+    println!("Replace YOUR_SERVER_IP with your server's public IP.");
+    println!("The proxy will auto-detect and display the correct link on startup.");
+    println!("Check: journalctl -u telemt.service | head -30");
+    println!("===================");
+}

src/config/defaults.rs

@@ -0,0 +1,703 @@
+use std::collections::HashMap;
+use ipnetwork::IpNetwork;
+use serde::Deserialize;
+
+// Helper defaults kept private to the config module.
+const DEFAULT_NETWORK_IPV6: Option<bool> = Some(false);
+const DEFAULT_STUN_TCP_FALLBACK: bool = true;
+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_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 = 500;
+const DEFAULT_ME_D2C_ACK_FLUSH_IMMEDIATE: bool = true;
+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_ME_POOL_DRAIN_SOFT_EVICT_ENABLED: bool = true;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_GRACE_SECS: u64 = 30;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_PER_WRITER: u8 = 1;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_BUDGET_PER_CORE: u16 = 8;
+const DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_COOLDOWN_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";
+
+pub(crate) fn default_true() -> bool {
+    true
+}
+
+pub(crate) fn default_port() -> u16 {
+    443
+}
+
+pub(crate) fn default_tls_domain() -> String {
+    "petrovich.ru".to_string()
+}
+
+pub(crate) fn default_mask_port() -> u16 {
+    443
+}
+
+pub(crate) fn default_fake_cert_len() -> usize {
+    2048
+}
+
+pub(crate) fn default_tls_front_dir() -> String {
+    "tlsfront".to_string()
+}
+
+pub(crate) fn default_replay_check_len() -> usize {
+    65_536
+}
+
+pub(crate) fn default_replay_window_secs() -> u64 {
+    1800
+}
+
+pub(crate) fn default_handshake_timeout() -> u64 {
+    30
+}
+
+pub(crate) fn default_connect_timeout() -> u64 {
+    10
+}
+
+pub(crate) fn default_keepalive() -> u64 {
+    15
+}
+
+pub(crate) fn default_ack_timeout() -> u64 {
+    90
+}
+pub(crate) fn default_me_one_retry() -> u8 {
+    12
+}
+
+pub(crate) fn default_me_one_timeout() -> u64 {
+    1200
+}
+
+pub(crate) fn default_listen_addr() -> String {
+    "0.0.0.0".to_string()
+}
+
+pub(crate) fn default_listen_addr_ipv4() -> Option<String> {
+    Some(default_listen_addr())
+}
+
+pub(crate) fn default_weight() -> u16 {
+    1
+}
+
+pub(crate) fn default_metrics_whitelist() -> Vec<IpNetwork> {
+    vec![
+        "127.0.0.1/32".parse().unwrap(),
+        "::1/128".parse().unwrap(),
+    ]
+}
+
+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
+}
+
+pub(crate) fn default_network_ipv6() -> Option<bool> {
+    DEFAULT_NETWORK_IPV6
+}
+
+pub(crate) fn default_stun_tcp_fallback() -> bool {
+    DEFAULT_STUN_TCP_FALLBACK
+}
+
+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
+}
+
+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
+}
+
+pub(crate) fn default_middle_proxy_nat_stun_servers() -> Vec<String> {
+    Vec::new()
+}
+
+pub(crate) fn default_stun_nat_probe_concurrency() -> usize {
+    8
+}
+
+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 {
+    8
+}
+
+pub(crate) fn default_keepalive_jitter() -> u64 {
+    2
+}
+
+pub(crate) fn default_warmup_step_delay_ms() -> u64 {
+    500
+}
+
+pub(crate) fn default_warmup_step_jitter_ms() -> u64 {
+    300
+}
+
+pub(crate) fn default_reconnect_backoff_base_ms() -> u64 {
+    500
+}
+
+pub(crate) fn default_reconnect_backoff_cap_ms() -> u64 {
+    30_000
+}
+
+pub(crate) fn default_me_reconnect_max_concurrent_per_dc() -> u32 {
+    DEFAULT_ME_RECONNECT_MAX_CONCURRENT_PER_DC
+}
+
+pub(crate) fn default_me_reconnect_fast_retry_count() -> u32 {
+    DEFAULT_ME_RECONNECT_FAST_RETRY_COUNT
+}
+
+pub(crate) fn default_me_single_endpoint_shadow_writers() -> u8 {
+    DEFAULT_ME_SINGLE_ENDPOINT_SHADOW_WRITERS
+}
+
+pub(crate) fn default_me_single_endpoint_outage_mode_enabled() -> bool {
+    true
+}
+
+pub(crate) fn default_me_single_endpoint_outage_disable_quarantine() -> bool {
+    true
+}
+
+pub(crate) fn default_me_single_endpoint_outage_backoff_min_ms() -> u64 {
+    250
+}
+
+pub(crate) fn default_me_single_endpoint_outage_backoff_max_ms() -> u64 {
+    3000
+}
+
+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 {
+    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
+}
+
+pub(crate) fn default_max_client_frame() -> usize {
+    16 * 1024 * 1024
+}
+
+pub(crate) fn default_desync_all_full() -> bool {
+    false
+}
+
+pub(crate) fn default_me_route_backpressure_base_timeout_ms() -> u64 {
+    25
+}
+
+pub(crate) fn default_me_route_backpressure_high_timeout_ms() -> u64 {
+    120
+}
+
+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
+}
+
+pub(crate) fn default_beobachten_flush_secs() -> u64 {
+    15
+}
+
+pub(crate) fn default_beobachten_file() -> String {
+    "cache/beobachten.txt".to_string()
+}
+
+pub(crate) fn default_tls_new_session_tickets() -> u8 {
+    0
+}
+
+pub(crate) fn default_tls_full_cert_ttl_secs() -> u64 {
+    90
+}
+
+pub(crate) fn default_server_hello_delay_min_ms() -> u64 {
+    0
+}
+
+pub(crate) fn default_server_hello_delay_max_ms() -> u64 {
+    0
+}
+
+pub(crate) fn default_alpn_enforce() -> bool {
+    true
+}
+
+pub(crate) fn default_stun_servers() -> Vec<String> {
+    vec![
+        "stun.l.google.com:5349".to_string(),
+        "stun1.l.google.com:3478".to_string(),
+        "stun.gmx.net:3478".to_string(),
+        "stun.l.google.com:19302".to_string(),
+        "stun.1und1.de:3478".to_string(),
+        "stun1.l.google.com:19302".to_string(),
+        "stun2.l.google.com:19302".to_string(),
+        "stun3.l.google.com:19302".to_string(),
+        "stun4.l.google.com:19302".to_string(),
+        "stun.services.mozilla.com:3478".to_string(),
+        "stun.stunprotocol.org:3478".to_string(),
+        "stun.nextcloud.com:3478".to_string(),
+        "stun.voip.eutelia.it:3478".to_string(),
+    ]
+}
+
+pub(crate) fn default_http_ip_detect_urls() -> Vec<String> {
+    vec![
+        "https://ifconfig.me/ip".to_string(),
+        "https://api.ipify.org".to_string(),
+    ]
+}
+
+pub(crate) fn default_cache_public_ip_path() -> String {
+    "cache/public_ip.txt".to_string()
+}
+
+pub(crate) fn default_proxy_secret_reload_secs() -> u64 {
+    60 * 60
+}
+
+pub(crate) fn default_proxy_config_reload_secs() -> u64 {
+    60 * 60
+}
+
+pub(crate) fn default_update_every_secs() -> u64 {
+    5 * 60
+}
+
+pub(crate) fn default_update_every() -> Option<u64> {
+    Some(default_update_every_secs())
+}
+
+pub(crate) fn default_me_reinit_every_secs() -> u64 {
+    15 * 60
+}
+
+pub(crate) fn default_me_reinit_singleflight() -> bool {
+    true
+}
+
+pub(crate) fn default_me_reinit_trigger_channel() -> usize {
+    64
+}
+
+pub(crate) fn default_me_reinit_coalesce_window_ms() -> u64 {
+    200
+}
+
+pub(crate) fn default_me_hardswap_warmup_delay_min_ms() -> u64 {
+    1000
+}
+
+pub(crate) fn default_me_hardswap_warmup_delay_max_ms() -> u64 {
+    2000
+}
+
+pub(crate) fn default_me_hardswap_warmup_extra_passes() -> u8 {
+    3
+}
+
+pub(crate) fn default_me_hardswap_warmup_pass_backoff_base_ms() -> u64 {
+    500
+}
+
+pub(crate) fn default_me_config_stable_snapshots() -> u8 {
+    2
+}
+
+pub(crate) fn default_me_config_apply_cooldown_secs() -> u64 {
+    300
+}
+
+pub(crate) fn default_me_snapshot_require_http_2xx() -> bool {
+    true
+}
+
+pub(crate) fn default_me_snapshot_reject_empty_map() -> bool {
+    true
+}
+
+pub(crate) fn default_me_snapshot_min_proxy_for_lines() -> u32 {
+    1
+}
+
+pub(crate) fn default_proxy_secret_stable_snapshots() -> u8 {
+    2
+}
+
+pub(crate) fn default_proxy_secret_rotate_runtime() -> bool {
+    true
+}
+
+pub(crate) fn default_me_secret_atomic_snapshot() -> bool {
+    true
+}
+
+pub(crate) fn default_proxy_secret_len_max() -> usize {
+    256
+}
+
+pub(crate) fn default_me_reinit_drain_timeout_secs() -> u64 {
+    120
+}
+
+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_pool_drain_soft_evict_enabled() -> bool {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_ENABLED
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_grace_secs() -> u64 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_GRACE_SECS
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_per_writer() -> u8 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_PER_WRITER
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_budget_per_core() -> u16 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_BUDGET_PER_CORE
+}
+
+pub(crate) fn default_me_pool_drain_soft_evict_cooldown_ms() -> u64 {
+    DEFAULT_ME_POOL_DRAIN_SOFT_EVICT_COOLDOWN_MS
+}
+
+pub(crate) fn default_me_bind_stale_ttl_secs() -> u64 {
+    default_me_pool_drain_ttl_secs()
+}
+
+pub(crate) fn default_me_pool_min_fresh_ratio() -> f32 {
+    0.8
+}
+
+pub(crate) fn default_me_deterministic_writer_sort() -> bool {
+    true
+}
+
+pub(crate) fn default_hardswap() -> bool {
+    true
+}
+
+pub(crate) fn default_ntp_check() -> bool {
+    true
+}
+
+pub(crate) fn default_ntp_servers() -> Vec<String> {
+    vec!["pool.ntp.org".to_string()]
+}
+
+pub(crate) fn default_fast_mode_min_tls_record() -> usize {
+    0
+}
+
+pub(crate) fn default_degradation_min_unavailable_dc_groups() -> u8 {
+    2
+}
+
+pub(crate) fn default_listen_addr_ipv6() -> String {
+    DEFAULT_LISTEN_ADDR_IPV6.to_string()
+}
+
+pub(crate) fn default_listen_addr_ipv6_opt() -> Option<String> {
+    Some(default_listen_addr_ipv6())
+}
+
+pub(crate) fn default_access_users() -> HashMap<String, String> {
+    HashMap::from([(
+        DEFAULT_ACCESS_USER.to_string(),
+        DEFAULT_ACCESS_SECRET.to_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)]
+#[serde(untagged)]
+pub(crate) enum OneOrMany {
+    One(String),
+    Many(Vec<String>),
+}
+
+pub(crate) fn deserialize_dc_overrides<'de, D>(
+    deserializer: D,
+) -> std::result::Result<HashMap<String, Vec<String>>, D::Error>
+where
+    D: serde::de::Deserializer<'de>,
+{
+    let raw: HashMap<String, OneOrMany> = HashMap::deserialize(deserializer)?;
+    let mut out = HashMap::new();
+    for (dc, val) in raw {
+        let mut addrs = match val {
+            OneOrMany::One(s) => vec![s],
+            OneOrMany::Many(v) => v,
+        };
+        addrs.retain(|s| !s.trim().is_empty());
+        if !addrs.is_empty() {
+            out.insert(dc, addrs);
+        }
+    }
+    Ok(out)
+}

src/config/mod.rs

@@ -1,287 +1,9 @@
-//! Configuration
+//! Configuration.
 
-use std::collections::HashMap;
-use std::net::IpAddr;
-use std::path::Path;
-use chrono::{DateTime, Utc};
-use serde::{Deserialize, Serialize};
-use crate::error::{ProxyError, Result};
+pub(crate) mod defaults;
+mod types;
+mod load;
+pub mod hot_reload;
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ProxyModes {
-    #[serde(default)]
-    pub classic: bool,
-    #[serde(default)]
-    pub secure: bool,
-    #[serde(default = "default_true")]
-    pub tls: bool,
-}
-
-fn default_true() -> bool { true }
-fn default_weight() -> u16 { 1 }
-
-impl Default for ProxyModes {
-    fn default() -> Self {
-        Self { classic: true, secure: true, tls: true }
-    }
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(tag = "type", rename_all = "lowercase")]
-pub enum UpstreamType {
-    Direct {
-        #[serde(default)]
-        interface: Option<String>, // Bind to specific IP/Interface
-    },
-    Socks4 {
-        address: String, // IP:Port of SOCKS server
-        #[serde(default)]
-        interface: Option<String>, // Bind to specific IP/Interface for connection to SOCKS
-        #[serde(default)]
-        user_id: Option<String>,
-    },
-    Socks5 {
-        address: String,
-        #[serde(default)]
-        interface: Option<String>,
-        #[serde(default)]
-        username: Option<String>,
-        #[serde(default)]
-        password: Option<String>,
-    },
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct UpstreamConfig {
-    #[serde(flatten)]
-    pub upstream_type: UpstreamType,
-    #[serde(default = "default_weight")]
-    pub weight: u16,
-    #[serde(default = "default_true")]
-    pub enabled: bool,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ListenerConfig {
-    pub ip: IpAddr,
-    #[serde(default)]
-    pub announce_ip: Option<IpAddr>, // IP to show in tg:// links
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ProxyConfig {
-    #[serde(default = "default_port")]
-    pub port: u16,
-    
-    #[serde(default)]
-    pub users: HashMap<String, String>,
-    
-    #[serde(default)]
-    pub ad_tag: Option<String>,
-    
-    #[serde(default)]
-    pub modes: ProxyModes,
-    
-    #[serde(default = "default_tls_domain")]
-    pub tls_domain: String,
-    
-    #[serde(default = "default_true")]
-    pub mask: bool,
-    
-    #[serde(default)]
-    pub mask_host: Option<String>,
-    
-    #[serde(default = "default_mask_port")]
-    pub mask_port: u16,
-    
-    #[serde(default)]
-    pub prefer_ipv6: bool,
-    
-    #[serde(default = "default_true")]
-    pub fast_mode: bool,
-    
-    #[serde(default)]
-    pub use_middle_proxy: bool,
-    
-    #[serde(default)]
-    pub user_max_tcp_conns: HashMap<String, usize>,
-    
-    #[serde(default)]
-    pub user_expirations: HashMap<String, DateTime<Utc>>,
-    
-    #[serde(default)]
-    pub user_data_quota: HashMap<String, u64>,
-    
-    #[serde(default = "default_replay_check_len")]
-    pub replay_check_len: usize,
-    
-    #[serde(default)]
-    pub ignore_time_skew: bool,
-    
-    #[serde(default = "default_handshake_timeout")]
-    pub client_handshake_timeout: u64,
-    
-    #[serde(default = "default_connect_timeout")]
-    pub tg_connect_timeout: u64,
-    
-    #[serde(default = "default_keepalive")]
-    pub client_keepalive: u64,
-    
-    #[serde(default = "default_ack_timeout")]
-    pub client_ack_timeout: u64,
-    
-    #[serde(default = "default_listen_addr")]
-    pub listen_addr_ipv4: String,
-    
-    #[serde(default)]
-    pub listen_addr_ipv6: Option<String>,
-    
-    #[serde(default)]
-    pub listen_unix_sock: Option<String>,
-    
-    #[serde(default)]
-    pub metrics_port: Option<u16>,
-    
-    #[serde(default = "default_metrics_whitelist")]
-    pub metrics_whitelist: Vec<IpAddr>,
-    
-    #[serde(default = "default_fake_cert_len")]
-    pub fake_cert_len: usize,
-
-    // New fields
-    #[serde(default)]
-    pub upstreams: Vec<UpstreamConfig>,
-
-    #[serde(default)]
-    pub listeners: Vec<ListenerConfig>,
-
-    #[serde(default)]
-    pub show_link: Vec<String>,
-}
-
-fn default_port() -> u16 { 443 }
-fn default_tls_domain() -> String { "www.google.com".to_string() }
-fn default_mask_port() -> u16 { 443 }
-fn default_replay_check_len() -> usize { 65536 }
-fn default_handshake_timeout() -> u64 { 10 }
-fn default_connect_timeout() -> u64 { 10 }
-fn default_keepalive() -> u64 { 600 }
-fn default_ack_timeout() -> u64 { 300 }
-fn default_listen_addr() -> String { "0.0.0.0".to_string() }
-fn default_fake_cert_len() -> usize { 2048 }
-
-fn default_metrics_whitelist() -> Vec<IpAddr> {
-    vec![
-        "127.0.0.1".parse().unwrap(),
-        "::1".parse().unwrap(),
-    ]
-}
-
-impl Default for ProxyConfig {
-    fn default() -> Self {
-        let mut users = HashMap::new();
-        users.insert("default".to_string(), "00000000000000000000000000000000".to_string());
-        
-        Self {
-            port: default_port(),
-            users,
-            ad_tag: None,
-            modes: ProxyModes::default(),
-            tls_domain: default_tls_domain(),
-            mask: true,
-            mask_host: None,
-            mask_port: default_mask_port(),
-            prefer_ipv6: false,
-            fast_mode: true,
-            use_middle_proxy: false,
-            user_max_tcp_conns: HashMap::new(),
-            user_expirations: HashMap::new(),
-            user_data_quota: HashMap::new(),
-            replay_check_len: default_replay_check_len(),
-            ignore_time_skew: false,
-            client_handshake_timeout: default_handshake_timeout(),
-            tg_connect_timeout: default_connect_timeout(),
-            client_keepalive: default_keepalive(),
-            client_ack_timeout: default_ack_timeout(),
-            listen_addr_ipv4: default_listen_addr(),
-            listen_addr_ipv6: Some("::".to_string()),
-            listen_unix_sock: None,
-            metrics_port: None,
-            metrics_whitelist: default_metrics_whitelist(),
-            fake_cert_len: default_fake_cert_len(),
-            upstreams: Vec::new(),
-            listeners: Vec::new(),
-            show_link: Vec::new(),
-        }
-    }
-}
-
-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 mut config: ProxyConfig = toml::from_str(&content)
-            .map_err(|e| ProxyError::Config(e.to_string()))?;
-        
-        // Validate secrets
-        for (user, secret) in &config.users {
-            if !secret.chars().all(|c| c.is_ascii_hexdigit()) || secret.len() != 32 {
-                return Err(ProxyError::InvalidSecret {
-                    user: user.clone(),
-                    reason: "Must be 32 hex characters".to_string(),
-                });
-            }
-        }
-        
-        // Default mask_host
-        if config.mask_host.is_none() {
-            config.mask_host = Some(config.tls_domain.clone());
-        }
-        
-        // Random fake_cert_len
-        use rand::Rng;
-        config.fake_cert_len = rand::thread_rng().gen_range(1024..4096);
-        
-        // Migration: Populate listeners if empty
-        if config.listeners.is_empty() {
-            if let Ok(ipv4) = config.listen_addr_ipv4.parse::<IpAddr>() {
-                config.listeners.push(ListenerConfig {
-                    ip: ipv4,
-                    announce_ip: None,
-                });
-            }
-            if let Some(ipv6_str) = &config.listen_addr_ipv6 {
-                 if let Ok(ipv6) = ipv6_str.parse::<IpAddr>() {
-                    config.listeners.push(ListenerConfig {
-                        ip: ipv6,
-                        announce_ip: None,
-                    });
-                }
-            }
-        }
-
-        // Migration: Populate upstreams if empty (Default Direct)
-        if config.upstreams.is_empty() {
-             config.upstreams.push(UpstreamConfig {
-                upstream_type: UpstreamType::Direct { interface: None },
-                weight: 1,
-                enabled: true,
-            });
-        }
-        
-        Ok(config)
-    }
-    
-    pub fn validate(&self) -> Result<()> {
-        if self.users.is_empty() {
-            return Err(ProxyError::Config("No users configured".to_string()));
-        }
-        
-        if !self.modes.classic && !self.modes.secure && !self.modes.tls {
-            return Err(ProxyError::Config("No modes enabled".to_string()));
-        }
-        
-        Ok(())
-    }
-}
+pub use load::ProxyConfig;
+pub use types::*;

src/crypto/aes.rs

@@ -1,9 +1,21 @@
 //! AES encryption implementations
 //!
 //! Provides AES-256-CTR and AES-256-CBC modes for MTProto encryption.
+//!
+//! ## Zeroize policy
+//!
+//! - `AesCbc` stores raw key/IV bytes and zeroizes them on drop.
+//! - `AesCtr` wraps an opaque `Aes256Ctr` cipher from the `ctr` crate.
+//!   The expanded key schedule lives inside that type and cannot be
+//!   zeroized from outside. Callers that hold raw key material (e.g.
+//!   `HandshakeSuccess`, `ObfuscationParams`) are responsible for
+//!   zeroizing their own copies.
+
+#![allow(dead_code)]
 
 use aes::Aes256;
 use ctr::{Ctr128BE, cipher::{KeyIvInit, StreamCipher}};
+use zeroize::Zeroize;
 use crate::error::{ProxyError, Result};
 
 type Aes256Ctr = Ctr128BE<Aes256>;
@@ -11,8 +23,13 @@ type Aes256Ctr = Ctr128BE<Aes256>;
 // ============= AES-256-CTR =============
 
 /// AES-256-CTR encryptor/decryptor
-/// 
-/// CTR mode is symmetric - encryption and decryption are the same operation.
+///
+/// CTR mode is symmetric — encryption and decryption are the same operation.
+///
+/// **Zeroize note:** The inner `Aes256Ctr` cipher state (expanded key schedule
+///     + counter) is opaque and cannot be zeroized. If you need to protect key
+///     material, zeroize the `[u8; 32]` key and `u128` IV at the call site
+///     before dropping them.
 pub struct AesCtr {
     cipher: Aes256Ctr,
 }
@@ -62,14 +79,23 @@ impl AesCtr {
 
 /// AES-256-CBC cipher with proper chaining
 ///
-/// Unlike CTR mode, CBC is NOT symmetric - encryption and decryption
+/// Unlike CTR mode, CBC is NOT symmetric — encryption and decryption
 /// are different operations. This implementation handles CBC chaining
 /// correctly across multiple blocks.
+///
+/// Key and IV are zeroized on drop.
 pub struct AesCbc {
     key: [u8; 32],
     iv: [u8; 16],
 }
 
+impl Drop for AesCbc {
+    fn drop(&mut self) {
+        self.key.zeroize();
+        self.iv.zeroize();
+    }
+}
+
 impl AesCbc {
     /// AES block size
     const BLOCK_SIZE: usize = 16;
@@ -123,7 +149,7 @@ impl AesCbc {
     ///
     /// CBC Encryption: C[i] = AES_Encrypt(P[i] XOR C[i-1]), where C[-1] = IV
     pub fn encrypt(&self, data: &[u8]) -> Result<Vec<u8>> {
-        if data.len() % Self::BLOCK_SIZE != 0 {
+        if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
             return Err(ProxyError::Crypto(
                 format!("CBC data must be aligned to 16 bytes, got {}", data.len())
             ));
@@ -141,17 +167,9 @@ impl AesCbc {
         
         for chunk in data.chunks(Self::BLOCK_SIZE) {
             let plaintext: [u8; 16] = chunk.try_into().unwrap();
-            
-            // XOR plaintext with previous ciphertext (or IV for first block)
             let xored = Self::xor_blocks(&plaintext, &prev_ciphertext);
-            
-            // Encrypt the XORed block
             let ciphertext = self.encrypt_block(&xored, &key_schedule);
-            
-            // Save for next iteration
             prev_ciphertext = ciphertext;
-            
-            // Append to result
             result.extend_from_slice(&ciphertext);
         }
         
@@ -162,7 +180,7 @@ impl AesCbc {
     ///
     /// CBC Decryption: P[i] = AES_Decrypt(C[i]) XOR C[i-1], where C[-1] = IV
     pub fn decrypt(&self, data: &[u8]) -> Result<Vec<u8>> {
-        if data.len() % Self::BLOCK_SIZE != 0 {
+        if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
             return Err(ProxyError::Crypto(
                 format!("CBC data must be aligned to 16 bytes, got {}", data.len())
             ));
@@ -180,17 +198,9 @@ impl AesCbc {
         
         for chunk in data.chunks(Self::BLOCK_SIZE) {
             let ciphertext: [u8; 16] = chunk.try_into().unwrap();
-            
-            // Decrypt the block
             let decrypted = self.decrypt_block(&ciphertext, &key_schedule);
-            
-            // XOR with previous ciphertext (or IV for first block)
             let plaintext = Self::xor_blocks(&decrypted, &prev_ciphertext);
-            
-            // Save current ciphertext for next iteration
             prev_ciphertext = ciphertext;
-            
-            // Append to result
             result.extend_from_slice(&plaintext);
         }
         
@@ -199,7 +209,7 @@ impl AesCbc {
     
     /// Encrypt data in-place
     pub fn encrypt_in_place(&self, data: &mut [u8]) -> Result<()> {
-        if data.len() % Self::BLOCK_SIZE != 0 {
+        if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
             return Err(ProxyError::Crypto(
                 format!("CBC data must be aligned to 16 bytes, got {}", data.len())
             ));
@@ -217,16 +227,13 @@ impl AesCbc {
         for i in (0..data.len()).step_by(Self::BLOCK_SIZE) {
             let block = &mut data[i..i + Self::BLOCK_SIZE];
             
-            // XOR with previous ciphertext
             for j in 0..Self::BLOCK_SIZE {
                 block[j] ^= prev_ciphertext[j];
             }
             
-            // Encrypt in-place
             let block_array: &mut [u8; 16] = block.try_into().unwrap();
             *block_array = self.encrypt_block(block_array, &key_schedule);
             
-            // Save for next iteration
             prev_ciphertext = *block_array;
         }
         
@@ -235,7 +242,7 @@ impl AesCbc {
     
     /// Decrypt data in-place
     pub fn decrypt_in_place(&self, data: &mut [u8]) -> Result<()> {
-        if data.len() % Self::BLOCK_SIZE != 0 {
+        if !data.len().is_multiple_of(Self::BLOCK_SIZE) {
             return Err(ProxyError::Crypto(
                 format!("CBC data must be aligned to 16 bytes, got {}", data.len())
             ));
@@ -248,26 +255,20 @@ impl AesCbc {
         use aes::cipher::KeyInit;
         let key_schedule = aes::Aes256::new((&self.key).into());
         
-        // For in-place decryption, we need to save ciphertext blocks
-        // before we overwrite them
         let mut prev_ciphertext = self.iv;
         
         for i in (0..data.len()).step_by(Self::BLOCK_SIZE) {
             let block = &mut data[i..i + Self::BLOCK_SIZE];
             
-            // Save current ciphertext before modifying
             let current_ciphertext: [u8; 16] = block.try_into().unwrap();
             
-            // Decrypt in-place
             let block_array: &mut [u8; 16] = block.try_into().unwrap();
             *block_array = self.decrypt_block(block_array, &key_schedule);
             
-            // XOR with previous ciphertext
             for j in 0..Self::BLOCK_SIZE {
                 block[j] ^= prev_ciphertext[j];
             }
             
-            // Save for next iteration
             prev_ciphertext = current_ciphertext;
         }
         
@@ -347,10 +348,8 @@ mod tests {
         let mut cipher = AesCtr::new(&key, iv);
         cipher.apply(&mut data);
         
-        // Encrypted should be different
         assert_ne!(&data[..], original);
         
-        // Decrypt with fresh cipher
         let mut cipher = AesCtr::new(&key, iv);
         cipher.apply(&mut data);
         
@@ -364,7 +363,7 @@ mod tests {
         let key = [0u8; 32];
         let iv = [0u8; 16];
         
-        let original = [0u8; 32]; // 2 blocks
+        let original = [0u8; 32];
         
         let cipher = AesCbc::new(key, iv);
         let encrypted = cipher.encrypt(&original).unwrap();
@@ -375,31 +374,25 @@ mod tests {
     
     #[test]
     fn test_aes_cbc_chaining_works() {
-        // This is the key test - verify CBC chaining is correct
         let key = [0x42u8; 32];
         let iv = [0x00u8; 16];
         
-        // Two IDENTICAL plaintext blocks
         let plaintext = [0xAAu8; 32];
         
         let cipher = AesCbc::new(key, iv);
         let ciphertext = cipher.encrypt(&plaintext).unwrap();
         
-        // With proper CBC, identical plaintext blocks produce DIFFERENT ciphertext
         let block1 = &ciphertext[0..16];
         let block2 = &ciphertext[16..32];
         
         assert_ne!(
             block1, block2,
-            "CBC chaining broken: identical plaintext blocks produced identical ciphertext. \
-             This indicates ECB mode, not CBC!"
+            "CBC chaining broken: identical plaintext blocks produced identical ciphertext"
         );
     }
     
     #[test]
     fn test_aes_cbc_known_vector() {
-        // Test with known NIST test vector
-        // AES-256-CBC with zero key and zero IV
         let key = [0u8; 32];
         let iv = [0u8; 16];
         let plaintext = [0u8; 16];
@@ -407,11 +400,9 @@ mod tests {
         let cipher = AesCbc::new(key, iv);
         let ciphertext = cipher.encrypt(&plaintext).unwrap();
         
-        // Decrypt and verify roundtrip
         let decrypted = cipher.decrypt(&ciphertext).unwrap();
         assert_eq!(plaintext.as_slice(), decrypted.as_slice());
         
-        // Ciphertext should not be all zeros
         assert_ne!(ciphertext.as_slice(), plaintext.as_slice());
     }
     
@@ -420,7 +411,6 @@ mod tests {
         let key = [0x12u8; 32];
         let iv = [0x34u8; 16];
         
-        // 5 blocks = 80 bytes
         let plaintext: Vec<u8> = (0..80).collect();
         
         let cipher = AesCbc::new(key, iv);
@@ -435,7 +425,7 @@ mod tests {
         let key = [0x12u8; 32];
         let iv = [0x34u8; 16];
         
-        let original = [0x56u8; 48]; // 3 blocks
+        let original = [0x56u8; 48];
         let mut buffer = original;
         
         let cipher = AesCbc::new(key, iv);
@@ -462,41 +452,33 @@ mod tests {
     fn test_aes_cbc_unaligned_error() {
         let cipher = AesCbc::new([0u8; 32], [0u8; 16]);
         
-        // 15 bytes - not aligned to block size
         let result = cipher.encrypt(&[0u8; 15]);
         assert!(result.is_err());
         
-        // 17 bytes - not aligned
         let result = cipher.encrypt(&[0u8; 17]);
         assert!(result.is_err());
     }
     
     #[test]
     fn test_aes_cbc_avalanche_effect() {
-        // Changing one bit in plaintext should change entire ciphertext block
-        // and all subsequent blocks (due to chaining)
         let key = [0xAB; 32];
         let iv = [0xCD; 16];
         
-        let mut plaintext1 = [0u8; 32];
+        let plaintext1 = [0u8; 32];
         let mut plaintext2 = [0u8; 32];
-        plaintext2[0] = 0x01; // Single bit difference in first block
+        plaintext2[0] = 0x01;
         
         let cipher = AesCbc::new(key, iv);
         
         let ciphertext1 = cipher.encrypt(&plaintext1).unwrap();
         let ciphertext2 = cipher.encrypt(&plaintext2).unwrap();
         
-        // First blocks should be different
         assert_ne!(&ciphertext1[0..16], &ciphertext2[0..16]);
-        
-        // Second blocks should ALSO be different (chaining effect)
         assert_ne!(&ciphertext1[16..32], &ciphertext2[16..32]);
     }
     
     #[test]
     fn test_aes_cbc_iv_matters() {
-        // Same plaintext with different IVs should produce different ciphertext
         let key = [0x55; 32];
         let plaintext = [0x77u8; 16];
         
@@ -511,7 +493,6 @@ mod tests {
     
     #[test]
     fn test_aes_cbc_deterministic() {
-        // Same key, IV, plaintext should always produce same ciphertext
         let key = [0x99; 32];
         let iv = [0x88; 16];
         let plaintext = [0x77u8; 32];
@@ -524,6 +505,23 @@ mod tests {
         assert_eq!(ciphertext1, ciphertext2);
     }
     
+    // ============= Zeroize Tests =============
+    
+    #[test]
+    fn test_aes_cbc_zeroize_on_drop() {
+        let key = [0xAA; 32];
+        let iv = [0xBB; 16];
+        
+        let cipher = AesCbc::new(key, iv);
+        // Verify key/iv are set
+        assert_eq!(cipher.key, [0xAA; 32]);
+        assert_eq!(cipher.iv, [0xBB; 16]);
+        
+        drop(cipher);
+        // After drop, key/iv are zeroized (can't observe directly,
+        // but the Drop impl runs without panic)
+    }
+    
     // ============= Error Handling Tests =============
     
     #[test]

src/crypto/hash.rs

@@ -1,3 +1,16 @@
+//! Cryptographic hash functions
+//!
+//! ## Protocol-required algorithms
+//!
+//! This module exposes MD5 and SHA-1 alongside SHA-256. These weaker
+//! hash functions are **required by the Telegram Middle Proxy protocol**
+//! (`derive_middleproxy_keys`) and cannot be replaced without breaking
+//! compatibility. They are NOT used for any security-sensitive purpose
+//! outside of that specific key derivation scheme mandated by Telegram.
+//!
+//! Static analysis tools (CodeQL, cargo-audit) may flag them — the
+//! usages are intentional and protocol-mandated.
+
 use hmac::{Hmac, Mac};
 use sha2::Sha256;
 use md5::Md5;
@@ -21,14 +34,16 @@ pub fn sha256_hmac(key: &[u8], data: &[u8]) -> [u8; 32] {
     mac.finalize().into_bytes().into()
 }
 
-/// SHA-1
+/// SHA-1 — **protocol-required** by Telegram Middle Proxy key derivation.
+/// Not used for general-purpose hashing.
 pub fn sha1(data: &[u8]) -> [u8; 20] {
     let mut hasher = Sha1::new();
     hasher.update(data);
     hasher.finalize().into()
 }
 
-/// MD5
+/// MD5 — **protocol-required** by Telegram Middle Proxy key derivation.
+/// Not used for general-purpose hashing.
 pub fn md5(data: &[u8]) -> [u8; 16] {
     let mut hasher = Md5::new();
     hasher.update(data);
@@ -40,7 +55,61 @@ pub fn crc32(data: &[u8]) -> u32 {
     crc32fast::hash(data)
 }
 
-/// Middle Proxy Keygen
+/// CRC32C (Castagnoli)
+pub fn crc32c(data: &[u8]) -> u32 {
+    crc32c::crc32c(data)
+}
+
+/// Build the exact prekey buffer used by Telegram Middle Proxy KDF.
+///
+/// Returned buffer layout (IPv4):
+/// nonce_srv | nonce_clt | clt_ts | srv_ip | clt_port | purpose | clt_ip | srv_port | secret | nonce_srv | [clt_v6 | srv_v6] | nonce_clt
+#[allow(clippy::too_many_arguments)]
+pub fn build_middleproxy_prekey(
+    nonce_srv: &[u8; 16],
+    nonce_clt: &[u8; 16],
+    clt_ts: &[u8; 4],
+    srv_ip: Option<&[u8]>,
+    clt_port: &[u8; 2],
+    purpose: &[u8],
+    clt_ip: Option<&[u8]>,
+    srv_port: &[u8; 2],
+    secret: &[u8],
+    clt_ipv6: Option<&[u8; 16]>,
+    srv_ipv6: Option<&[u8; 16]>,
+) -> Vec<u8> {
+    const EMPTY_IP: [u8; 4] = [0, 0, 0, 0];
+
+    let srv_ip = srv_ip.unwrap_or(&EMPTY_IP);
+    let clt_ip = clt_ip.unwrap_or(&EMPTY_IP);
+
+    let mut s = Vec::with_capacity(256);
+    s.extend_from_slice(nonce_srv);
+    s.extend_from_slice(nonce_clt);
+    s.extend_from_slice(clt_ts);
+    s.extend_from_slice(srv_ip);
+    s.extend_from_slice(clt_port);
+    s.extend_from_slice(purpose);
+    s.extend_from_slice(clt_ip);
+    s.extend_from_slice(srv_port);
+    s.extend_from_slice(secret);
+    s.extend_from_slice(nonce_srv);
+
+    if let (Some(clt_v6), Some(srv_v6)) = (clt_ipv6, srv_ipv6) {
+        s.extend_from_slice(clt_v6);
+        s.extend_from_slice(srv_v6);
+    }
+
+    s.extend_from_slice(nonce_clt);
+    s
+}
+
+/// Middle Proxy key derivation
+///
+/// Uses MD5 + SHA-1 as mandated by the Telegram Middle Proxy protocol.
+/// These algorithms are NOT replaceable here — changing them would break
+/// interoperability with Telegram's middle proxy infrastructure.
+#[allow(clippy::too_many_arguments)]
 pub fn derive_middleproxy_keys(
     nonce_srv: &[u8; 16],
     nonce_clt: &[u8; 16],
@@ -54,30 +123,20 @@ pub fn derive_middleproxy_keys(
     clt_ipv6: Option<&[u8; 16]>,
     srv_ipv6: Option<&[u8; 16]>,
 ) -> ([u8; 32], [u8; 16]) {
-    const EMPTY_IP: [u8; 4] = [0, 0, 0, 0];
-    
-    let srv_ip = srv_ip.unwrap_or(&EMPTY_IP);
-    let clt_ip = clt_ip.unwrap_or(&EMPTY_IP);
-    
-    let mut s = Vec::with_capacity(256);
-    s.extend_from_slice(nonce_srv);
-    s.extend_from_slice(nonce_clt);
-    s.extend_from_slice(clt_ts);
-    s.extend_from_slice(srv_ip);
-    s.extend_from_slice(clt_port);
-    s.extend_from_slice(purpose);
-    s.extend_from_slice(clt_ip);
-    s.extend_from_slice(srv_port);
-    s.extend_from_slice(secret);
-    s.extend_from_slice(nonce_srv);
-    
-    if let (Some(clt_v6), Some(srv_v6)) = (clt_ipv6, srv_ipv6) {
-        s.extend_from_slice(clt_v6);
-        s.extend_from_slice(srv_v6);
-    }
-    
-    s.extend_from_slice(nonce_clt);
-    
+    let s = build_middleproxy_prekey(
+        nonce_srv,
+        nonce_clt,
+        clt_ts,
+        srv_ip,
+        clt_port,
+        purpose,
+        clt_ip,
+        srv_port,
+        secret,
+        clt_ipv6,
+        srv_ipv6,
+    );
+
     let md5_1 = md5(&s[1..]);
     let sha1_sum = sha1(&s);
     let md5_2 = md5(&s[2..]);
@@ -87,4 +146,40 @@ pub fn derive_middleproxy_keys(
     key[12..].copy_from_slice(&sha1_sum);
     
     (key, md5_2)
-}
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn middleproxy_prekey_sha_is_stable() {
+        let nonce_srv = [0x11u8; 16];
+        let nonce_clt = [0x22u8; 16];
+        let clt_ts = 0x44332211u32.to_le_bytes();
+        let srv_ip = Some([149u8, 154, 175, 50].as_ref());
+        let clt_ip = Some([10u8, 0, 0, 1].as_ref());
+        let clt_port = 0x1f90u16.to_le_bytes(); // 8080
+        let srv_port = 0x22b8u16.to_le_bytes(); // 8888
+        let secret = vec![0x55u8; 128];
+
+        let prekey = build_middleproxy_prekey(
+            &nonce_srv,
+            &nonce_clt,
+            &clt_ts,
+            srv_ip,
+            &clt_port,
+            b"CLIENT",
+            clt_ip,
+            &srv_port,
+            &secret,
+            None,
+            None,
+        );
+        let digest = sha256(&prekey);
+        assert_eq!(
+            hex::encode(digest),
+            "934f5facdafd65a44d5c2df90d2f35ddc81faaaeb337949dfeef817c8a7c1e00"
+        );
+    }
+}

src/crypto/mod.rs

@@ -5,5 +5,7 @@ pub mod hash;
 pub mod random;
 
 pub use aes::{AesCtr, AesCbc};
-pub use hash::{sha256, sha256_hmac, sha1, md5, crc32};
-pub use random::{SecureRandom, SECURE_RANDOM};
+pub use hash::{
+    build_middleproxy_prekey, crc32, crc32c, derive_middleproxy_keys, sha256, sha256_hmac,
+};
+pub use random::SecureRandom;

src/crypto/random.rs

@@ -1,55 +1,98 @@
 //! Pseudorandom
 
+#![allow(deprecated)]
+#![allow(dead_code)]
+
 use rand::{Rng, RngCore, SeedableRng};
 use rand::rngs::StdRng;
 use parking_lot::Mutex;
+use zeroize::Zeroize;
 use crate::crypto::AesCtr;
-use once_cell::sync::Lazy;
-
-/// Global secure random instance
-pub static SECURE_RANDOM: Lazy<SecureRandom> = Lazy::new(SecureRandom::new);
 
 /// Cryptographically secure PRNG with AES-CTR
 pub struct SecureRandom {
     inner: Mutex<SecureRandomInner>,
 }
 
+unsafe impl Send for SecureRandom {}
+unsafe impl Sync for SecureRandom {}
+
 struct SecureRandomInner {
     rng: StdRng,
     cipher: AesCtr,
     buffer: Vec<u8>,
+    buffer_start: usize,
+}
+
+impl Drop for SecureRandomInner {
+    fn drop(&mut self) {
+        self.buffer.zeroize();
+    }
 }
 
 impl SecureRandom {
     pub fn new() -> Self {
-        let mut rng = StdRng::from_entropy();
+        let mut seed_source = rand::rng();
+        let mut rng = StdRng::from_rng(&mut seed_source);
         
         let mut key = [0u8; 32];
         rng.fill_bytes(&mut key);
-        let iv: u128 = rng.gen();
+        let iv: u128 = rng.random();
+        
+        let cipher = AesCtr::new(&key, iv);
+        
+        // Zeroize local key copy — cipher already consumed it
+        key.zeroize();
         
         Self {
             inner: Mutex::new(SecureRandomInner {
                 rng,
-                cipher: AesCtr::new(&key, iv),
+                cipher,
                 buffer: Vec::with_capacity(1024),
+                buffer_start: 0,
             }),
         }
     }
     
-    /// Generate random bytes
-    pub fn bytes(&self, len: usize) -> Vec<u8> {
+    /// Fill a caller-provided buffer with random bytes.
+    pub fn fill(&self, out: &mut [u8]) {
         let mut inner = self.inner.lock();
         const CHUNK_SIZE: usize = 512;
-        
-        while inner.buffer.len() < len {
-            let mut chunk = vec![0u8; CHUNK_SIZE];
-            inner.rng.fill_bytes(&mut chunk);
-            inner.cipher.apply(&mut chunk);
-            inner.buffer.extend_from_slice(&chunk);
+
+        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 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;
         }
-        
-        inner.buffer.drain(..len).collect()
+    }
+
+    /// Generate random bytes
+    pub fn bytes(&self, len: usize) -> Vec<u8> {
+        let mut out = vec![0u8; len];
+        self.fill(&mut out);
+        out
     }
     
     /// Generate random number in range [0, max)
@@ -67,7 +110,7 @@ impl SecureRandom {
             return 0;
         }
         
-        let bytes_needed = (k + 7) / 8;
+        let bytes_needed = k.div_ceil(8);
         let bytes = self.bytes(bytes_needed.min(8));
         
         let mut result = 0u64;
@@ -78,7 +121,6 @@ impl SecureRandom {
             result |= (b as u64) << (i * 8);
         }
         
-        // Mask extra bits
         if k < 64 {
             result &= (1u64 << k) - 1;
         }
@@ -107,13 +149,13 @@ impl SecureRandom {
     /// Generate random u32
     pub fn u32(&self) -> u32 {
         let mut inner = self.inner.lock();
-        inner.rng.gen()
+        inner.rng.random()
     }
     
     /// Generate random u64
     pub fn u64(&self) -> u64 {
         let mut inner = self.inner.lock();
-        inner.rng.gen()
+        inner.rng.random()
     }
 }
 
@@ -162,12 +204,10 @@ mod tests {
     fn test_bits() {
         let rng = SecureRandom::new();
         
-        // Single bit should be 0 or 1
         for _ in 0..100 {
             assert!(rng.bits(1) <= 1);
         }
         
-        // 8 bits should be 0-255
         for _ in 0..100 {
             assert!(rng.bits(8) <= 255);
         }
@@ -185,10 +225,8 @@ mod tests {
             }
         }
         
-        // Should have seen all items
         assert_eq!(seen.len(), 5);
         
-        // Empty slice should return None
         let empty: Vec<i32> = vec![];
         assert!(rng.choose(&empty).is_none());
     }
@@ -201,12 +239,10 @@ mod tests {
         let mut shuffled = original.clone();
         rng.shuffle(&mut shuffled);
         
-        // Should contain same elements
         let mut sorted = shuffled.clone();
         sorted.sort();
         assert_eq!(sorted, original);
         
-        // Should be different order (with very high probability)
         assert_ne!(shuffled, original);
     }
-}
+}

src/error.rs

@@ -1,5 +1,7 @@
 //! Error Types
 
+#![allow(dead_code)]
+
 use std::fmt;
 use std::net::SocketAddr;
 use thiserror::Error;
@@ -89,7 +91,7 @@ impl From<StreamError> for std::io::Error {
                 std::io::Error::new(std::io::ErrorKind::UnexpectedEof, err)
             }
             StreamError::Poisoned { .. } => {
-                std::io::Error::new(std::io::ErrorKind::Other, err)
+                std::io::Error::other(err)
             }
             StreamError::BufferOverflow { .. } => {
                 std::io::Error::new(std::io::ErrorKind::OutOfMemory, err)
@@ -98,7 +100,7 @@ impl From<StreamError> for std::io::Error {
                 std::io::Error::new(std::io::ErrorKind::InvalidData, err)
             }
             StreamError::PartialRead { .. } | StreamError::PartialWrite { .. } => {
-                std::io::Error::new(std::io::ErrorKind::Other, err)
+                std::io::Error::other(err)
             }
         }
     }
@@ -118,16 +120,13 @@ pub trait Recoverable {
 impl Recoverable for StreamError {
     fn is_recoverable(&self) -> bool {
         match self {
-            // Partial operations can be retried
             Self::PartialRead { .. } | Self::PartialWrite { .. } => true,
-            // I/O errors depend on kind
             Self::Io(e) => matches!(
                 e.kind(),
                 std::io::ErrorKind::WouldBlock 
                 | std::io::ErrorKind::Interrupted
                 | std::io::ErrorKind::TimedOut
             ),
-            // These are not recoverable
             Self::Poisoned { .. } 
             | Self::BufferOverflow { .. }
             | Self::InvalidFrame { .. }
@@ -136,16 +135,7 @@ impl Recoverable for StreamError {
     }
     
     fn can_continue(&self) -> bool {
-        match self {
-            // Poisoned stream cannot be used
-            Self::Poisoned { .. } => false,
-            // EOF means stream is done
-            Self::UnexpectedEof => false,
-            // Buffer overflow is fatal
-            Self::BufferOverflow { .. } => false,
-            // Others might allow continuation
-            _ => true,
-        }
+        !matches!(self, Self::Poisoned { .. } | Self::UnexpectedEof | Self::BufferOverflow { .. })
     }
 }
 
@@ -297,16 +287,16 @@ pub type StreamResult<T> = std::result::Result<T, StreamError>;
 
 /// Result with optional bad client handling
 #[derive(Debug)]
-pub enum HandshakeResult<T> {
+pub enum HandshakeResult<T, R, W> {
     /// Handshake succeeded
     Success(T),
-    /// Client failed validation, needs masking
-    BadClient,
+    /// Client failed validation, needs masking. Returns ownership of streams.
+    BadClient { reader: R, writer: W },
     /// Error occurred
     Error(ProxyError),
 }
 
-impl<T> HandshakeResult<T> {
+impl<T, R, W> HandshakeResult<T, R, W> {
     /// Check if successful
     pub fn is_success(&self) -> bool {
         matches!(self, HandshakeResult::Success(_))
@@ -314,49 +304,32 @@ impl<T> HandshakeResult<T> {
     
     /// Check if bad client
     pub fn is_bad_client(&self) -> bool {
-        matches!(self, HandshakeResult::BadClient)
-    }
-    
-    /// Convert to Result, treating BadClient as error
-    pub fn into_result(self) -> Result<T> {
-        match self {
-            HandshakeResult::Success(v) => Ok(v),
-            HandshakeResult::BadClient => Err(ProxyError::InvalidHandshake("Bad client".into())),
-            HandshakeResult::Error(e) => Err(e),
-        }
+        matches!(self, HandshakeResult::BadClient { .. })
     }
     
     /// Map the success value
-    pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> HandshakeResult<U> {
+    pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> HandshakeResult<U, R, W> {
         match self {
             HandshakeResult::Success(v) => HandshakeResult::Success(f(v)),
-            HandshakeResult::BadClient => HandshakeResult::BadClient,
+            HandshakeResult::BadClient { reader, writer } => HandshakeResult::BadClient { reader, writer },
             HandshakeResult::Error(e) => HandshakeResult::Error(e),
         }
     }
-    
-    /// Convert success to Option
-    pub fn ok(self) -> Option<T> {
-        match self {
-            HandshakeResult::Success(v) => Some(v),
-            _ => None,
-        }
-    }
 }
 
-impl<T> From<ProxyError> for HandshakeResult<T> {
+impl<T, R, W> From<ProxyError> for HandshakeResult<T, R, W> {
     fn from(err: ProxyError) -> Self {
         HandshakeResult::Error(err)
     }
 }
 
-impl<T> From<std::io::Error> for HandshakeResult<T> {
+impl<T, R, W> From<std::io::Error> for HandshakeResult<T, R, W> {
     fn from(err: std::io::Error) -> Self {
         HandshakeResult::Error(ProxyError::Io(err))
     }
 }
 
-impl<T> From<StreamError> for HandshakeResult<T> {
+impl<T, R, W> From<StreamError> for HandshakeResult<T, R, W> {
     fn from(err: StreamError) -> Self {
         HandshakeResult::Error(ProxyError::Stream(err))
     }
@@ -400,18 +373,18 @@ mod tests {
     
     #[test]
     fn test_handshake_result() {
-        let success: HandshakeResult<i32> = HandshakeResult::Success(42);
+        let success: HandshakeResult<i32, (), ()> = HandshakeResult::Success(42);
         assert!(success.is_success());
         assert!(!success.is_bad_client());
         
-        let bad: HandshakeResult<i32> = HandshakeResult::BadClient;
+        let bad: HandshakeResult<i32, (), ()> = HandshakeResult::BadClient { reader: (), writer: () };
         assert!(!bad.is_success());
         assert!(bad.is_bad_client());
     }
     
     #[test]
     fn test_handshake_result_map() {
-        let success: HandshakeResult<i32> = HandshakeResult::Success(42);
+        let success: HandshakeResult<i32, (), ()> = HandshakeResult::Success(42);
         let mapped = success.map(|x| x * 2);
         
         match mapped {

src/ip_tracker.rs

@@ -0,0 +1,676 @@
+// IP address tracking and per-user unique IP limiting.
+
+#![allow(dead_code)]
+
+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;
+
+use crate::config::UserMaxUniqueIpsMode;
+
+#[derive(Debug, Clone)]
+pub struct UserIpTracker {
+    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)),
+        }
+    }
+
+    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);
+    }
+
+    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);
+    }
+
+    pub async fn check_and_add(&self, username: &str, ip: IpAddr) -> Result<(), String> {
+        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))
+        };
+        let mode = *self.limit_mode.read().await;
+        let window = *self.limit_window.read().await;
+        let now = Instant::now();
+
+        let mut active_ips = self.active_ips.write().await;
+        let user_active = active_ips
+            .entry(username.to_string())
+            .or_insert_with(HashMap::new);
+
+        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 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
+                ));
+            }
+        }
+
+        user_active.insert(ip, 1);
+        user_recent.insert(ip, now);
+        Ok(())
+    }
+
+    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) {
+            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);
+            }
+        }
+    }
+
+    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)
+    }
+
+    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.keys().copied().collect())
+            .unwrap_or_else(Vec::new)
+    }
+
+    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()
+                .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
+    }
+
+    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();
+    }
+
+    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_key(&ip))
+            .unwrap_or(false)
+    }
+
+    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()
+            .filter(|limit| *limit > 0)
+            .or((default_max_ips > 0).then_some(default_max_ips))
+    }
+
+    pub async fn format_stats(&self) -> String {
+        let stats = self.get_stats().await;
+
+        if stats.is_empty() {
+            return String::from("No active users");
+        }
+
+        let mut output = String::from("User IP Statistics:\n");
+        output.push_str("==================\n");
+
+        for (username, active_count, limit) in stats {
+            output.push_str(&format!(
+                "User: {:<20} Active IPs: {}/{}\n",
+                username,
+                active_count,
+                if limit > 0 {
+                    limit.to_string()
+                } else {
+                    "unlimited".to_string()
+                }
+            ));
+
+            let ips = self.get_active_ips(&username).await;
+            for ip in ips {
+                output.push_str(&format!("  - {}\n", ip));
+            }
+        }
+
+        output
+    }
+}
+
+impl Default for UserIpTracker {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+    fn test_ipv4(oct1: u8, oct2: u8, oct3: u8, oct4: u8) -> IpAddr {
+        IpAddr::V4(Ipv4Addr::new(oct1, oct2, oct3, oct4))
+    }
+
+    fn test_ipv6() -> IpAddr {
+        IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1))
+    }
+
+    #[tokio::test]
+    async fn test_basic_ip_limit() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 2).await;
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+        let ip2 = test_ipv4(192, 168, 1, 2);
+        let ip3 = test_ipv4(192, 168, 1, 3);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+    }
+
+    #[tokio::test]
+    async fn test_active_window_rejects_new_ip_and_keeps_existing_session() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 1).await;
+        tracker
+            .set_limit_policy(UserMaxUniqueIpsMode::ActiveWindow, 30)
+            .await;
+
+        let ip1 = test_ipv4(10, 10, 10, 1);
+        let ip2 = test_ipv4(10, 10, 10, 2);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.is_ip_active("test_user", ip1).await);
+        assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+        // Existing session remains active; only new unique IP is denied.
+        assert!(tracker.is_ip_active("test_user", ip1).await);
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+    }
+
+    #[tokio::test]
+    async fn test_reconnection_from_same_ip() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 2).await;
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+    }
+
+    #[tokio::test]
+    async fn test_same_ip_disconnect_keeps_active_while_other_session_alive() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 2).await;
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+        tracker.remove_ip("test_user", ip1).await;
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+        tracker.remove_ip("test_user", ip1).await;
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 0);
+    }
+
+    #[tokio::test]
+    async fn test_ip_removal() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 2).await;
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+        let ip2 = test_ipv4(192, 168, 1, 2);
+        let ip3 = test_ipv4(192, 168, 1, 3);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+
+        tracker.remove_ip("test_user", ip1).await;
+
+        assert!(tracker.check_and_add("test_user", ip3).await.is_ok());
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+    }
+
+    #[tokio::test]
+    async fn test_no_limit() {
+        let tracker = UserIpTracker::new();
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+        let ip2 = test_ipv4(192, 168, 1, 2);
+        let ip3 = test_ipv4(192, 168, 1, 3);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip3).await.is_ok());
+
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 3);
+    }
+
+    #[tokio::test]
+    async fn test_multiple_users() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("user1", 2).await;
+        tracker.set_user_limit("user2", 1).await;
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+        let ip2 = test_ipv4(192, 168, 1, 2);
+
+        assert!(tracker.check_and_add("user1", ip1).await.is_ok());
+        assert!(tracker.check_and_add("user1", ip2).await.is_ok());
+
+        assert!(tracker.check_and_add("user2", ip1).await.is_ok());
+        assert!(tracker.check_and_add("user2", ip2).await.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_ipv6_support() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 2).await;
+
+        let ipv4 = test_ipv4(192, 168, 1, 1);
+        let ipv6 = test_ipv6();
+
+        assert!(tracker.check_and_add("test_user", ipv4).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ipv6).await.is_ok());
+
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 2);
+    }
+
+    #[tokio::test]
+    async fn test_get_active_ips() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 3).await;
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+        let ip2 = test_ipv4(192, 168, 1, 2);
+
+        tracker.check_and_add("test_user", ip1).await.unwrap();
+        tracker.check_and_add("test_user", ip2).await.unwrap();
+
+        let active_ips = tracker.get_active_ips("test_user").await;
+        assert_eq!(active_ips.len(), 2);
+        assert!(active_ips.contains(&ip1));
+        assert!(active_ips.contains(&ip2));
+    }
+
+    #[tokio::test]
+    async fn test_stats() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("user1", 3).await;
+        tracker.set_user_limit("user2", 2).await;
+
+        let ip1 = test_ipv4(192, 168, 1, 1);
+        let ip2 = test_ipv4(192, 168, 1, 2);
+
+        tracker.check_and_add("user1", ip1).await.unwrap();
+        tracker.check_and_add("user2", ip2).await.unwrap();
+
+        let stats = tracker.get_stats().await;
+        assert_eq!(stats.len(), 2);
+
+        assert!(stats.iter().any(|(name, _, _)| name == "user1"));
+        assert!(stats.iter().any(|(name, _, _)| name == "user2"));
+    }
+
+    #[tokio::test]
+    async fn test_clear_user_ips() {
+        let tracker = UserIpTracker::new();
+        let ip1 = test_ipv4(192, 168, 1, 1);
+
+        tracker.check_and_add("test_user", ip1).await.unwrap();
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 1);
+
+        tracker.clear_user_ips("test_user").await;
+        assert_eq!(tracker.get_active_ip_count("test_user").await, 0);
+    }
+
+    #[tokio::test]
+    async fn test_is_ip_active() {
+        let tracker = UserIpTracker::new();
+        let ip1 = test_ipv4(192, 168, 1, 1);
+        let ip2 = test_ipv4(192, 168, 1, 2);
+
+        tracker.check_and_add("test_user", ip1).await.unwrap();
+
+        assert!(tracker.is_ip_active("test_user", ip1).await);
+        assert!(!tracker.is_ip_active("test_user", ip2).await);
+    }
+
+    #[tokio::test]
+    async fn test_load_limits_from_config() {
+        let tracker = UserIpTracker::new();
+
+        let mut config_limits = HashMap::new();
+        config_limits.insert("user1".to_string(), 5);
+        config_limits.insert("user2".to_string(), 3);
+
+        tracker.load_limits(0, &config_limits).await;
+
+        assert_eq!(tracker.get_user_limit("user1").await, Some(5));
+        assert_eq!(tracker.get_user_limit("user2").await, Some(3));
+        assert_eq!(tracker.get_user_limit("user3").await, None);
+    }
+
+    #[tokio::test]
+    async fn test_load_limits_replaces_previous_map() {
+        let tracker = UserIpTracker::new();
+
+        let mut first = HashMap::new();
+        first.insert("user1".to_string(), 2);
+        first.insert("user2".to_string(), 3);
+        tracker.load_limits(0, &first).await;
+
+        let mut second = HashMap::new();
+        second.insert("user2".to_string(), 5);
+        tracker.load_limits(0, &second).await;
+
+        assert_eq!(tracker.get_user_limit("user1").await, None);
+        assert_eq!(tracker.get_user_limit("user2").await, Some(5));
+    }
+
+    #[tokio::test]
+    async fn test_global_each_limit_applies_without_user_override() {
+        let tracker = UserIpTracker::new();
+        tracker.load_limits(2, &HashMap::new()).await;
+
+        let ip1 = test_ipv4(172, 16, 0, 1);
+        let ip2 = test_ipv4(172, 16, 0, 2);
+        let ip3 = test_ipv4(172, 16, 0, 3);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip3).await.is_err());
+        assert_eq!(tracker.get_user_limit("test_user").await, Some(2));
+    }
+
+    #[tokio::test]
+    async fn test_user_override_wins_over_global_each_limit() {
+        let tracker = UserIpTracker::new();
+        let mut limits = HashMap::new();
+        limits.insert("test_user".to_string(), 1);
+        tracker.load_limits(3, &limits).await;
+
+        let ip1 = test_ipv4(172, 17, 0, 1);
+        let ip2 = test_ipv4(172, 17, 0, 2);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+        assert_eq!(tracker.get_user_limit("test_user").await, Some(1));
+    }
+
+    #[tokio::test]
+    async fn test_time_window_mode_blocks_recent_ip_churn() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 1).await;
+        tracker
+            .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 30)
+            .await;
+
+        let ip1 = test_ipv4(10, 0, 0, 1);
+        let ip2 = test_ipv4(10, 0, 0, 2);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        tracker.remove_ip("test_user", ip1).await;
+        assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_combined_mode_enforces_active_and_recent_limits() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 1).await;
+        tracker
+            .set_limit_policy(UserMaxUniqueIpsMode::Combined, 30)
+            .await;
+
+        let ip1 = test_ipv4(10, 0, 1, 1);
+        let ip2 = test_ipv4(10, 0, 1, 2);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+        tracker.remove_ip("test_user", ip1).await;
+        assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_time_window_expires() {
+        let tracker = UserIpTracker::new();
+        tracker.set_user_limit("test_user", 1).await;
+        tracker
+            .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+            .await;
+
+        let ip1 = test_ipv4(10, 1, 0, 1);
+        let ip2 = test_ipv4(10, 1, 0, 2);
+
+        assert!(tracker.check_and_add("test_user", ip1).await.is_ok());
+        tracker.remove_ip("test_user", ip1).await;
+        assert!(tracker.check_and_add("test_user", ip2).await.is_err());
+
+        tokio::time::sleep(Duration::from_millis(1100)).await;
+        assert!(tracker.check_and_add("test_user", ip2).await.is_ok());
+    }
+}

src/ip_tracker_regression_tests.rs

@@ -0,0 +1,450 @@
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr};
+use std::sync::Arc;
+use std::time::Duration;
+
+use crate::config::UserMaxUniqueIpsMode;
+use crate::ip_tracker::UserIpTracker;
+
+fn ip_from_idx(idx: u32) -> IpAddr {
+    let a = 10u8;
+    let b = ((idx / 65_536) % 256) as u8;
+    let c = ((idx / 256) % 256) as u8;
+    let d = (idx % 256) as u8;
+    IpAddr::V4(Ipv4Addr::new(a, b, c, d))
+}
+
+#[tokio::test]
+async fn active_window_enforces_large_unique_ip_burst() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("burst_user", 64).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::ActiveWindow, 30)
+        .await;
+
+    for idx in 0..64 {
+        assert!(tracker.check_and_add("burst_user", ip_from_idx(idx)).await.is_ok());
+    }
+    assert!(tracker.check_and_add("burst_user", ip_from_idx(9_999)).await.is_err());
+    assert_eq!(tracker.get_active_ip_count("burst_user").await, 64);
+}
+
+#[tokio::test]
+async fn global_limit_applies_across_many_users() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(3, &HashMap::new()).await;
+
+    for user_idx in 0..150u32 {
+        let user = format!("u{}", user_idx);
+        assert!(tracker.check_and_add(&user, ip_from_idx(user_idx * 10)).await.is_ok());
+        assert!(tracker
+            .check_and_add(&user, ip_from_idx(user_idx * 10 + 1))
+            .await
+            .is_ok());
+        assert!(tracker
+            .check_and_add(&user, ip_from_idx(user_idx * 10 + 2))
+            .await
+            .is_ok());
+        assert!(tracker
+            .check_and_add(&user, ip_from_idx(user_idx * 10 + 3))
+            .await
+            .is_err());
+    }
+
+    assert_eq!(tracker.get_stats().await.len(), 150);
+}
+
+#[tokio::test]
+async fn user_zero_override_falls_back_to_global_limit() {
+    let tracker = UserIpTracker::new();
+    let mut limits = HashMap::new();
+    limits.insert("target".to_string(), 0);
+    tracker.load_limits(2, &limits).await;
+
+    assert!(tracker.check_and_add("target", ip_from_idx(1)).await.is_ok());
+    assert!(tracker.check_and_add("target", ip_from_idx(2)).await.is_ok());
+    assert!(tracker.check_and_add("target", ip_from_idx(3)).await.is_err());
+    assert_eq!(tracker.get_user_limit("target").await, Some(2));
+}
+
+#[tokio::test]
+async fn remove_ip_is_idempotent_after_counter_reaches_zero() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("u", 2).await;
+    let ip = ip_from_idx(42);
+
+    tracker.check_and_add("u", ip).await.unwrap();
+    tracker.remove_ip("u", ip).await;
+    tracker.remove_ip("u", ip).await;
+    tracker.remove_ip("u", ip).await;
+
+    assert_eq!(tracker.get_active_ip_count("u").await, 0);
+    assert!(!tracker.is_ip_active("u", ip).await);
+}
+
+#[tokio::test]
+async fn clear_user_ips_resets_active_and_recent() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("u", 10).await;
+
+    for idx in 0..6 {
+        tracker.check_and_add("u", ip_from_idx(idx)).await.unwrap();
+    }
+
+    tracker.clear_user_ips("u").await;
+
+    assert_eq!(tracker.get_active_ip_count("u").await, 0);
+    let counts = tracker
+        .get_recent_counts_for_users(&["u".to_string()])
+        .await;
+    assert_eq!(counts.get("u").copied().unwrap_or(0), 0);
+}
+
+#[tokio::test]
+async fn clear_all_resets_multi_user_state() {
+    let tracker = UserIpTracker::new();
+
+    for user_idx in 0..80u32 {
+        let user = format!("u{}", user_idx);
+        for ip_idx in 0..3 {
+            tracker
+                .check_and_add(&user, ip_from_idx(user_idx * 100 + ip_idx))
+                .await
+                .unwrap();
+        }
+    }
+
+    tracker.clear_all().await;
+
+    assert!(tracker.get_stats().await.is_empty());
+    let users = (0..80u32)
+        .map(|idx| format!("u{}", idx))
+        .collect::<Vec<_>>();
+    let recent = tracker.get_recent_counts_for_users(&users).await;
+    assert!(recent.values().all(|count| *count == 0));
+}
+
+#[tokio::test]
+async fn get_active_ips_for_users_are_sorted() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user", 10).await;
+
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 0, 0, 9)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 0, 0, 5)))
+        .await
+        .unwrap();
+
+    let map = tracker
+        .get_active_ips_for_users(&["user".to_string()])
+        .await;
+    let ips = map.get("user").cloned().unwrap_or_default();
+
+    assert_eq!(
+        ips,
+        vec![
+            IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1)),
+            IpAddr::V4(Ipv4Addr::new(10, 0, 0, 5)),
+            IpAddr::V4(Ipv4Addr::new(10, 0, 0, 9)),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn get_recent_ips_for_users_are_sorted() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("user", 10).await;
+
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 1, 0, 9)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 1, 0, 1)))
+        .await
+        .unwrap();
+    tracker
+        .check_and_add("user", IpAddr::V4(Ipv4Addr::new(10, 1, 0, 5)))
+        .await
+        .unwrap();
+
+    let map = tracker
+        .get_recent_ips_for_users(&["user".to_string()])
+        .await;
+    let ips = map.get("user").cloned().unwrap_or_default();
+
+    assert_eq!(
+        ips,
+        vec![
+            IpAddr::V4(Ipv4Addr::new(10, 1, 0, 1)),
+            IpAddr::V4(Ipv4Addr::new(10, 1, 0, 5)),
+            IpAddr::V4(Ipv4Addr::new(10, 1, 0, 9)),
+        ]
+    );
+}
+
+#[tokio::test]
+async fn time_window_expires_for_large_rotation() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("tw", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::TimeWindow, 1)
+        .await;
+
+    tracker.check_and_add("tw", ip_from_idx(1)).await.unwrap();
+    tracker.remove_ip("tw", ip_from_idx(1)).await;
+    assert!(tracker.check_and_add("tw", ip_from_idx(2)).await.is_err());
+
+    tokio::time::sleep(Duration::from_millis(1_100)).await;
+    assert!(tracker.check_and_add("tw", ip_from_idx(2)).await.is_ok());
+}
+
+#[tokio::test]
+async fn combined_mode_blocks_recent_after_disconnect() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("cmb", 1).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::Combined, 2)
+        .await;
+
+    tracker.check_and_add("cmb", ip_from_idx(11)).await.unwrap();
+    tracker.remove_ip("cmb", ip_from_idx(11)).await;
+
+    assert!(tracker.check_and_add("cmb", ip_from_idx(12)).await.is_err());
+}
+
+#[tokio::test]
+async fn load_limits_replaces_large_limit_map() {
+    let tracker = UserIpTracker::new();
+    let mut first = HashMap::new();
+    let mut second = HashMap::new();
+
+    for idx in 0..300usize {
+        first.insert(format!("u{}", idx), 2usize);
+    }
+    for idx in 150..450usize {
+        second.insert(format!("u{}", idx), 4usize);
+    }
+
+    tracker.load_limits(0, &first).await;
+    tracker.load_limits(0, &second).await;
+
+    assert_eq!(tracker.get_user_limit("u20").await, None);
+    assert_eq!(tracker.get_user_limit("u200").await, Some(4));
+    assert_eq!(tracker.get_user_limit("u420").await, Some(4));
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_same_user_unique_ip_pressure_stays_bounded() {
+    let tracker = Arc::new(UserIpTracker::new());
+    tracker.set_user_limit("hot", 32).await;
+    tracker
+        .set_limit_policy(UserMaxUniqueIpsMode::ActiveWindow, 30)
+        .await;
+
+    let mut handles = Vec::new();
+    for worker in 0..16u32 {
+        let tracker_cloned = tracker.clone();
+        handles.push(tokio::spawn(async move {
+            let base = worker * 200;
+            for step in 0..200u32 {
+                let _ = tracker_cloned
+                    .check_and_add("hot", ip_from_idx(base + step))
+                    .await;
+            }
+        }));
+    }
+
+    for handle in handles {
+        handle.await.unwrap();
+    }
+
+    assert!(tracker.get_active_ip_count("hot").await <= 32);
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_many_users_isolate_limits() {
+    let tracker = Arc::new(UserIpTracker::new());
+    tracker.load_limits(4, &HashMap::new()).await;
+
+    let mut handles = Vec::new();
+    for user_idx in 0..120u32 {
+        let tracker_cloned = tracker.clone();
+        handles.push(tokio::spawn(async move {
+            let user = format!("u{}", user_idx);
+            for ip_idx in 0..10u32 {
+                let _ = tracker_cloned
+                    .check_and_add(&user, ip_from_idx(user_idx * 1_000 + ip_idx))
+                    .await;
+            }
+        }));
+    }
+
+    for handle in handles {
+        handle.await.unwrap();
+    }
+
+    let stats = tracker.get_stats().await;
+    assert_eq!(stats.len(), 120);
+    assert!(stats.iter().all(|(_, active, limit)| *active <= 4 && *limit == 4));
+}
+
+#[tokio::test]
+async fn same_ip_reconnect_high_frequency_keeps_single_unique() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("same", 2).await;
+    let ip = ip_from_idx(9);
+
+    for _ in 0..2_000 {
+        tracker.check_and_add("same", ip).await.unwrap();
+    }
+
+    assert_eq!(tracker.get_active_ip_count("same").await, 1);
+    assert!(tracker.is_ip_active("same", ip).await);
+}
+
+#[tokio::test]
+async fn format_stats_contains_expected_limited_and_unlimited_markers() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("limited", 2).await;
+    tracker.check_and_add("limited", ip_from_idx(1)).await.unwrap();
+    tracker.check_and_add("open", ip_from_idx(2)).await.unwrap();
+
+    let text = tracker.format_stats().await;
+
+    assert!(text.contains("limited"));
+    assert!(text.contains("open"));
+    assert!(text.contains("unlimited"));
+}
+
+#[tokio::test]
+async fn stats_report_global_default_for_users_without_override() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(5, &HashMap::new()).await;
+
+    tracker.check_and_add("a", ip_from_idx(1)).await.unwrap();
+    tracker.check_and_add("b", ip_from_idx(2)).await.unwrap();
+
+    let stats = tracker.get_stats().await;
+    assert!(stats.iter().any(|(user, _, limit)| user == "a" && *limit == 5));
+    assert!(stats.iter().any(|(user, _, limit)| user == "b" && *limit == 5));
+}
+
+#[tokio::test]
+async fn stress_cycle_add_remove_clear_preserves_empty_end_state() {
+    let tracker = UserIpTracker::new();
+
+    for cycle in 0..50u32 {
+        let user = format!("cycle{}", cycle);
+        tracker.set_user_limit(&user, 128).await;
+
+        for ip_idx in 0..128u32 {
+            tracker
+                .check_and_add(&user, ip_from_idx(cycle * 10_000 + ip_idx))
+                .await
+                .unwrap();
+        }
+
+        for ip_idx in 0..128u32 {
+            tracker
+                .remove_ip(&user, ip_from_idx(cycle * 10_000 + ip_idx))
+                .await;
+        }
+
+        tracker.clear_user_ips(&user).await;
+    }
+
+    assert!(tracker.get_stats().await.is_empty());
+}
+
+#[tokio::test]
+async fn remove_unknown_user_or_ip_does_not_corrupt_state() {
+    let tracker = UserIpTracker::new();
+
+    tracker.remove_ip("no_user", ip_from_idx(1)).await;
+    tracker.check_and_add("x", ip_from_idx(2)).await.unwrap();
+    tracker.remove_ip("x", ip_from_idx(3)).await;
+
+    assert_eq!(tracker.get_active_ip_count("x").await, 1);
+    assert!(tracker.is_ip_active("x", ip_from_idx(2)).await);
+}
+
+#[tokio::test]
+async fn active_and_recent_views_match_after_mixed_workload() {
+    let tracker = UserIpTracker::new();
+    tracker.set_user_limit("mix", 16).await;
+
+    for ip_idx in 0..12u32 {
+        tracker.check_and_add("mix", ip_from_idx(ip_idx)).await.unwrap();
+    }
+    for ip_idx in 0..6u32 {
+        tracker.remove_ip("mix", ip_from_idx(ip_idx)).await;
+    }
+
+    let active = tracker
+        .get_active_ips_for_users(&["mix".to_string()])
+        .await
+        .get("mix")
+        .cloned()
+        .unwrap_or_default();
+    let recent_count = tracker
+        .get_recent_counts_for_users(&["mix".to_string()])
+        .await
+        .get("mix")
+        .copied()
+        .unwrap_or(0);
+
+    assert_eq!(active.len(), 6);
+    assert!(recent_count >= active.len());
+    assert!(recent_count <= 12);
+}
+
+#[tokio::test]
+async fn global_limit_switch_updates_enforcement_immediately() {
+    let tracker = UserIpTracker::new();
+    tracker.load_limits(2, &HashMap::new()).await;
+
+    assert!(tracker.check_and_add("u", ip_from_idx(1)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(2)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(3)).await.is_err());
+
+    tracker.clear_user_ips("u").await;
+    tracker.load_limits(4, &HashMap::new()).await;
+
+    assert!(tracker.check_and_add("u", ip_from_idx(1)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(2)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(3)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(4)).await.is_ok());
+    assert!(tracker.check_and_add("u", ip_from_idx(5)).await.is_err());
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn concurrent_reconnect_and_disconnect_preserves_non_negative_counts() {
+    let tracker = Arc::new(UserIpTracker::new());
+    tracker.set_user_limit("cc", 8).await;
+
+    let mut handles = Vec::new();
+    for worker in 0..8u32 {
+        let tracker_cloned = tracker.clone();
+        handles.push(tokio::spawn(async move {
+            let ip = ip_from_idx(50 + worker);
+            for _ in 0..500u32 {
+                let _ = tracker_cloned.check_and_add("cc", ip).await;
+                tracker_cloned.remove_ip("cc", ip).await;
+            }
+        }));
+    }
+
+    for handle in handles {
+        handle.await.unwrap();
+    }
+
+    assert!(tracker.get_active_ip_count("cc").await <= 8);
+}

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,335 @@
+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 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)
+}
+
+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,521 @@
+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.me_pool_drain_soft_evict_enabled,
+                    config.general.me_pool_drain_soft_evict_grace_secs,
+                    config.general.me_pool_drain_soft_evict_per_writer,
+                    config.general.me_pool_drain_soft_evict_budget_per_core,
+                    config.general.me_pool_drain_soft_evict_cooldown_ms,
+                    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,598 @@
+//! 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;
+
+/// 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, data_path, cli_silent, cli_log_level) = parse_cli();
+
+    let mut config = match ProxyConfig::load(&config_path) {
+        Ok(c) => c,
+        Err(e) => {
+            if std::path::Path::new(&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);
+                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 = std::path::PathBuf::from(&config_path);
+            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(64 * 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,351 @@
+use std::net::IpAddr;
+use std::path::PathBuf;
+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: &str,
+    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(
+        PathBuf::from(config_path),
+        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>>,
+) {
+    // metrics_listen takes precedence; fall back to metrics_port for backward compat.
+    let metrics_target: Option<(u16, Option<String>)> =
+        if let Some(ref listen) = config.server.metrics_listen {
+            match listen.parse::<std::net::SocketAddr>() {
+                Ok(addr) => Some((addr.port(), Some(listen.clone()))),
+                Err(e) => {
+                    startup_tracker
+                        .skip_component(
+                            COMPONENT_METRICS_START,
+                            Some(format!("invalid metrics_listen \"{}\": {}", listen, e)),
+                        )
+                        .await;
+                    None
+                }
+            }
+        } else {
+            config.server.metrics_port.map(|p| (p, None))
+        };
+
+    if let Some((port, listen)) = metrics_target {
+        let fallback_label = format!("port {}", port);
+        let label = listen.as_deref().unwrap_or(&fallback_label);
+        startup_tracker
+            .start_component(
+                COMPONENT_METRICS_START,
+                Some(format!("spawn metrics endpoint on {}", label)),
+            )
+            .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,
+                listen,
+                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 if config.server.metrics_listen.is_none() {
+        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/main.rs

@@ -1,193 +1,26 @@
-//! Telemt - MTProxy on Rust
-
-use std::net::SocketAddr;
-use std::sync::Arc;
-use std::time::Duration;
-use tokio::net::TcpListener;
-use tokio::signal;
-use tracing::{info, error, warn};
-use tracing_subscriber::{fmt, EnvFilter};
+//! telemt — Telegram MTProto Proxy
 
+mod api;
+mod cli;
 mod config;
 mod crypto;
 mod error;
+mod ip_tracker;
+#[cfg(test)]
+mod ip_tracker_regression_tests;
+mod maestro;
+mod metrics;
+mod network;
 mod protocol;
 mod proxy;
+mod startup;
 mod stats;
 mod stream;
+mod tls_front;
 mod transport;
 mod util;
 
-use crate::config::ProxyConfig;
-use crate::proxy::ClientHandler;
-use crate::stats::Stats;
-use crate::transport::{create_listener, ListenOptions, UpstreamManager};
-use crate::util::ip::detect_ip;
-
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // Initialize logging
-    fmt()
-        .with_env_filter(EnvFilter::from_default_env().add_directive("info".parse().unwrap()))
-        .init();
-
-    // Load config
-    let config_path = std::env::args().nth(1).unwrap_or_else(|| "config.toml".to_string());
-    let config = match ProxyConfig::load(&config_path) {
-        Ok(c) => c,
-        Err(e) => {
-            // If config doesn't exist, try to create default
-            if std::path::Path::new(&config_path).exists() {
-                error!("Failed to load config: {}", e);
-                std::process::exit(1);
-            } else {
-                let default = ProxyConfig::default();
-                let toml = toml::to_string_pretty(&default).unwrap();
-                std::fs::write(&config_path, toml).unwrap();
-                info!("Created default config at {}", config_path);
-                default
-            }
-        }
-    };
-    
-    config.validate()?;
-    
-    let config = Arc::new(config);
-    let stats = Arc::new(Stats::new());
-    
-    // Initialize Upstream Manager
-    let upstream_manager = Arc::new(UpstreamManager::new(config.upstreams.clone()));
-    
-    // Start Health Checks
-    let um_clone = upstream_manager.clone();
-    tokio::spawn(async move {
-        um_clone.run_health_checks().await;
-    });
-
-    // Detect public IP if needed (once at startup)
-    let detected_ip = detect_ip().await;
-
-    // Start Listeners
-    let mut listeners = Vec::new();
-    
-    for listener_conf in &config.listeners {
-        let addr = SocketAddr::new(listener_conf.ip, config.port);
-        let options = ListenOptions {
-            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);
-                
-                // Determine public IP for tg:// links
-                // 1. Use explicit announce_ip if set
-                // 2. If listening on 0.0.0.0 or ::, use detected public IP
-                // 3. Otherwise use the bind IP
-                let public_ip = if let Some(ip) = listener_conf.announce_ip {
-                    ip
-                } else if listener_conf.ip.is_unspecified() {
-                    // Try to use detected IP of the same family
-                    if listener_conf.ip.is_ipv4() {
-                        detected_ip.ipv4.unwrap_or(listener_conf.ip)
-                    } else {
-                        detected_ip.ipv6.unwrap_or(listener_conf.ip)
-                    }
-                } else {
-                    listener_conf.ip
-                };
-
-                // Show links for configured users
-                if !config.show_link.is_empty() {
-                    info!("--- Proxy Links for {} ---", public_ip);
-                    for user_name in &config.show_link {
-                        if let Some(secret) = config.users.get(user_name) {
-                            info!("User: {}", user_name);
-
-                            // Classic
-                            if config.modes.classic {
-                                info!("  Classic: tg://proxy?server={}&port={}&secret={}", 
-                                    public_ip, config.port, secret);
-                            }
-
-                            // DD (Secure)
-                            if config.modes.secure {
-                                info!("  DD:      tg://proxy?server={}&port={}&secret=dd{}", 
-                                    public_ip, config.port, secret);
-                            }
-
-                            // EE-TLS (FakeTLS)
-                            if config.modes.tls {
-                                let domain_hex = hex::encode(&config.tls_domain);
-                                info!("  EE-TLS:  tg://proxy?server={}&port={}&secret=ee{}{}", 
-                                    public_ip, config.port, secret, domain_hex);
-                            }
-                        } else {
-                            warn!("User '{}' specified in show_link not found in users list", user_name);
-                        }
-                    }
-                    info!("-----------------------------------");
-                }
-                
-                listeners.push(listener);
-            },
-            Err(e) => {
-                error!("Failed to bind to {}: {}", addr, e);
-            }
-        }
-    }
-    
-    if listeners.is_empty() {
-        error!("No listeners could be started. Exiting.");
-        std::process::exit(1);
-    }
-
-    // Accept loop
-    // For simplicity in this slice, we just spawn a task for each listener
-    // In a real high-perf scenario, we might want a more complex accept loop
-    
-    for listener in listeners {
-        let config = config.clone();
-        let stats = stats.clone();
-        let upstream_manager = upstream_manager.clone();
-        
-        tokio::spawn(async move {
-            loop {
-                match listener.accept().await {
-                    Ok((stream, peer_addr)) => {
-                        let config = config.clone();
-                        let stats = stats.clone();
-                        let upstream_manager = upstream_manager.clone();
-                        
-                        tokio::spawn(async move {
-                            if let Err(e) = ClientHandler::new(
-                                stream, 
-                                peer_addr, 
-                                config, 
-                                stats,
-                                upstream_manager
-                            ).run().await {
-                                // Log only relevant errors
-                                // debug!("Connection error: {}", e);
-                            }
-                        });
-                    }
-                    Err(e) => {
-                        error!("Accept error: {}", e);
-                        tokio::time::sleep(Duration::from_millis(100)).await;
-                    }
-                }
-            }
-        });
-    }
-
-    // Wait for signal
-    match signal::ctrl_c().await {
-        Ok(()) => info!("Shutting down..."),
-        Err(e) => error!("Signal error: {}", e),
-    }
-
-    Ok(())
-}
+async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
+    maestro::run().await
+}

src/network/dns_overrides.rs

@@ -0,0 +1,197 @@
+//! Runtime DNS overrides for `host:port` targets.
+
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv6Addr, SocketAddr};
+use std::sync::{OnceLock, RwLock};
+
+use crate::error::{ProxyError, Result};
+
+type OverrideMap = HashMap<(String, u16), IpAddr>;
+
+static DNS_OVERRIDES: OnceLock<RwLock<OverrideMap>> = OnceLock::new();
+
+fn overrides_store() -> &'static RwLock<OverrideMap> {
+    DNS_OVERRIDES.get_or_init(|| RwLock::new(HashMap::new()))
+}
+
+fn parse_ip_spec(ip_spec: &str) -> Result<IpAddr> {
+    if ip_spec.starts_with('[') && ip_spec.ends_with(']') {
+        let inner = &ip_spec[1..ip_spec.len() - 1];
+        let ipv6 = inner.parse::<Ipv6Addr>().map_err(|_| {
+            ProxyError::Config(format!(
+                "network.dns_overrides IPv6 override is invalid: '{ip_spec}'"
+            ))
+        })?;
+        return Ok(IpAddr::V6(ipv6));
+    }
+
+    let ip = ip_spec.parse::<IpAddr>().map_err(|_| {
+        ProxyError::Config(format!(
+            "network.dns_overrides IP is invalid: '{ip_spec}'"
+        ))
+    })?;
+    if matches!(ip, IpAddr::V6(_)) {
+        return Err(ProxyError::Config(format!(
+            "network.dns_overrides IPv6 must be bracketed: '{ip_spec}'"
+        )));
+    }
+    Ok(ip)
+}
+
+fn parse_entry(entry: &str) -> Result<((String, u16), IpAddr)> {
+    let trimmed = entry.trim();
+    if trimmed.is_empty() {
+        return Err(ProxyError::Config(
+            "network.dns_overrides entry cannot be empty".to_string(),
+        ));
+    }
+
+    let first_sep = trimmed.find(':').ok_or_else(|| {
+        ProxyError::Config(format!(
+            "network.dns_overrides entry must use host:port:ip format: '{trimmed}'"
+        ))
+    })?;
+    let second_sep = trimmed[first_sep + 1..]
+        .find(':')
+        .map(|idx| first_sep + 1 + idx)
+        .ok_or_else(|| {
+            ProxyError::Config(format!(
+                "network.dns_overrides entry must use host:port:ip format: '{trimmed}'"
+            ))
+        })?;
+
+    let host = trimmed[..first_sep].trim();
+    let port_str = trimmed[first_sep + 1..second_sep].trim();
+    let ip_str = trimmed[second_sep + 1..].trim();
+
+    if host.is_empty() {
+        return Err(ProxyError::Config(format!(
+            "network.dns_overrides host cannot be empty: '{trimmed}'"
+        )));
+    }
+    if host.contains(':') {
+        return Err(ProxyError::Config(format!(
+            "network.dns_overrides host must be a domain name without ':' in this format: '{trimmed}'"
+        )));
+    }
+
+    let port = port_str.parse::<u16>().map_err(|_| {
+        ProxyError::Config(format!(
+            "network.dns_overrides port is invalid: '{trimmed}'"
+        ))
+    })?;
+    let ip = parse_ip_spec(ip_str)?;
+
+    Ok(((host.to_ascii_lowercase(), port), ip))
+}
+
+fn parse_entries(entries: &[String]) -> Result<OverrideMap> {
+    let mut parsed = HashMap::new();
+    for entry in entries {
+        let (key, ip) = parse_entry(entry)?;
+        parsed.insert(key, ip);
+    }
+    Ok(parsed)
+}
+
+/// Validate `network.dns_overrides` entries without updating runtime state.
+pub fn validate_entries(entries: &[String]) -> Result<()> {
+    let _ = parse_entries(entries)?;
+    Ok(())
+}
+
+/// Replace runtime DNS overrides with a new validated snapshot.
+pub fn install_entries(entries: &[String]) -> Result<()> {
+    let parsed = parse_entries(entries)?;
+    let mut guard = overrides_store()
+        .write()
+        .map_err(|_| ProxyError::Config("network.dns_overrides runtime lock is poisoned".to_string()))?;
+    *guard = parsed;
+    Ok(())
+}
+
+/// Resolve a hostname override for `(host, port)` if present.
+pub fn resolve(host: &str, port: u16) -> Option<IpAddr> {
+    let key = (host.to_ascii_lowercase(), port);
+    overrides_store()
+        .read()
+        .ok()
+        .and_then(|guard| guard.get(&key).copied())
+}
+
+/// Resolve a hostname override and construct a socket address when present.
+pub fn resolve_socket_addr(host: &str, port: u16) -> Option<SocketAddr> {
+    resolve(host, port).map(|ip| SocketAddr::new(ip, port))
+}
+
+/// Parse a runtime endpoint in `host:port` format.
+///
+/// Supports:
+/// - `example.com:443`
+/// - `[2001:db8::1]:443`
+pub fn split_host_port(endpoint: &str) -> Option<(String, u16)> {
+    if endpoint.starts_with('[') {
+        let bracket_end = endpoint.find(']')?;
+        if endpoint.as_bytes().get(bracket_end + 1) != Some(&b':') {
+            return None;
+        }
+        let host = endpoint[1..bracket_end].trim();
+        let port = endpoint[bracket_end + 2..].trim().parse::<u16>().ok()?;
+        if host.is_empty() {
+            return None;
+        }
+        return Some((host.to_ascii_lowercase(), port));
+    }
+
+    let split_idx = endpoint.rfind(':')?;
+    let host = endpoint[..split_idx].trim();
+    let port = endpoint[split_idx + 1..].trim().parse::<u16>().ok()?;
+    if host.is_empty() || host.contains(':') {
+        return None;
+    }
+
+    Some((host.to_ascii_lowercase(), port))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn validate_accepts_ipv4_and_bracketed_ipv6() {
+        let entries = vec![
+            "example.com:443:127.0.0.1".to_string(),
+            "example.net:8443:[2001:db8::10]".to_string(),
+        ];
+        assert!(validate_entries(&entries).is_ok());
+    }
+
+    #[test]
+    fn validate_rejects_unbracketed_ipv6() {
+        let entries = vec!["example.net:443:2001:db8::10".to_string()];
+        let err = validate_entries(&entries).unwrap_err().to_string();
+        assert!(err.contains("must be bracketed"));
+    }
+
+    #[test]
+    fn install_and_resolve_are_case_insensitive_for_host() {
+        let entries = vec!["MyPetrovich.ru:8443:127.0.0.1".to_string()];
+        install_entries(&entries).unwrap();
+
+        let resolved = resolve("mypetrovich.ru", 8443);
+        assert_eq!(resolved, Some("127.0.0.1".parse().unwrap()));
+    }
+
+    #[test]
+    fn split_host_port_parses_supported_shapes() {
+        assert_eq!(
+            split_host_port("example.com:443"),
+            Some(("example.com".to_string(), 443))
+        );
+        assert_eq!(
+            split_host_port("[2001:db8::1]:443"),
+            Some(("2001:db8::1".to_string(), 443))
+        );
+        assert_eq!(split_host_port("2001:db8::1:443"), None);
+    }
+}

src/network/mod.rs

@@ -0,0 +1,5 @@
+pub mod dns_overrides;
+pub mod probe;
+pub mod stun;
+
+pub use stun::IpFamily;

src/network/probe.rs

@@ -0,0 +1,551 @@
+#![allow(dead_code)]
+
+use std::collections::HashMap;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, UdpSocket};
+use std::time::Duration;
+
+use tokio::task::JoinSet;
+use tokio::time::timeout;
+use tracing::{debug, info, warn};
+
+use crate::config::{NetworkConfig, UpstreamConfig, UpstreamType};
+use crate::error::Result;
+use crate::network::stun::{stun_probe_family_with_bind, DualStunResult, IpFamily, StunProbeResult};
+use crate::transport::UpstreamManager;
+
+#[derive(Debug, Clone, Default)]
+pub struct NetworkProbe {
+    pub detected_ipv4: Option<Ipv4Addr>,
+    pub detected_ipv6: Option<Ipv6Addr>,
+    pub reflected_ipv4: Option<SocketAddr>,
+    pub reflected_ipv6: Option<SocketAddr>,
+    pub ipv4_is_bogon: bool,
+    pub ipv6_is_bogon: bool,
+    pub ipv4_nat_detected: bool,
+    pub ipv6_nat_detected: bool,
+    pub ipv4_usable: bool,
+    pub ipv6_usable: bool,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct NetworkDecision {
+    pub ipv4_dc: bool,
+    pub ipv6_dc: bool,
+    pub ipv4_me: bool,
+    pub ipv6_me: bool,
+    pub effective_prefer: u8,
+    pub effective_multipath: bool,
+}
+
+impl NetworkDecision {
+    pub fn prefer_ipv6(&self) -> bool {
+        self.effective_prefer == 6
+    }
+
+    pub fn me_families(&self) -> Vec<IpFamily> {
+        let mut res = Vec::new();
+        if self.ipv4_me {
+            res.push(IpFamily::V4);
+        }
+        if self.ipv6_me {
+            res.push(IpFamily::V6);
+        }
+        res
+    }
+}
+
+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;
+
+    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()
+        } else {
+            probe_stun_servers_parallel(
+                &servers,
+                stun_nat_probe_concurrency.max(1),
+                None,
+                None,
+            )
+            .await
+        }
+    } else if nat_probe {
+        info!("STUN probe is disabled by network.stun_use=false");
+        DualStunResult::default()
+    } else {
+        DualStunResult::default()
+    };
+    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
+        && probe.reflected_ipv4.is_none()
+        && probe.detected_ipv4.map(is_bogon_v4).unwrap_or(false)
+    {
+        if let Some(public_ip) = detect_public_ipv4_http(&config.http_ip_detect_urls).await {
+            probe.reflected_ipv4 = Some(SocketAddr::new(IpAddr::V4(public_ip), 0));
+            info!(public_ip = %public_ip, "STUN unavailable, using HTTP public IPv4 fallback");
+        }
+    }
+
+    probe.ipv4_nat_detected = match (probe.detected_ipv4, probe.reflected_ipv4) {
+        (Some(det), Some(reflected)) => det != reflected.ip(),
+        _ => false,
+    };
+    probe.ipv6_nat_detected = match (probe.detected_ipv6, probe.reflected_ipv6) {
+        (Some(det), Some(reflected)) => det != reflected.ip(),
+        _ => false,
+    };
+
+    probe.ipv4_usable = config.ipv4
+        && probe.detected_ipv4.is_some()
+        && (!probe.ipv4_is_bogon || probe.reflected_ipv4.map(|r| !is_bogon(r.ip())).unwrap_or(false));
+
+    let ipv6_enabled = config.ipv6.unwrap_or(probe.detected_ipv6.is_some());
+    probe.ipv6_usable = ipv6_enabled
+        && probe.detected_ipv6.is_some()
+        && (!probe.ipv6_is_bogon || probe.reflected_ipv6.map(|r| !is_bogon(r.ip())).unwrap_or(false));
+
+    Ok(probe)
+}
+
+async fn detect_public_ipv4_http(urls: &[String]) -> Option<Ipv4Addr> {
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(3))
+        .build()
+        .ok()?;
+
+    for url in urls {
+        let response = match client.get(url).send().await {
+            Ok(response) => response,
+            Err(_) => continue,
+        };
+
+        let body = match response.text().await {
+            Ok(body) => body,
+            Err(_) => continue,
+        };
+
+        let Ok(ip) = body.trim().parse::<Ipv4Addr>() else {
+            continue;
+        };
+        if !is_bogon_v4(ip) {
+            return Some(ip);
+        }
+    }
+
+    None
+}
+
+fn collect_stun_servers(config: &NetworkConfig) -> Vec<String> {
+    let mut out = Vec::new();
+    for s in &config.stun_servers {
+        if !s.is_empty() && !out.contains(s) {
+            out.push(s.clone());
+        }
+    }
+    out
+}
+
+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;
+    let mut best_v4_by_ip: HashMap<IpAddr, (usize, StunProbeResult)> = HashMap::new();
+    let mut best_v6_by_ip: HashMap<IpAddr, (usize, StunProbeResult)> = HashMap::new();
+
+    while next_idx < servers.len() || !join_set.is_empty() {
+        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, 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)
+            });
+        }
+
+        let Some(task) = join_set.join_next().await else {
+            break;
+        };
+
+        match task {
+            Ok((stun_addr, Ok(Ok(result)))) => {
+                if let Some(v4) = result.v4 {
+                    let entry = best_v4_by_ip.entry(v4.reflected_addr.ip()).or_insert((0, v4));
+                    entry.0 += 1;
+                }
+                if let Some(v6) = result.v6 {
+                    let entry = best_v6_by_ip.entry(v6.reflected_addr.ip()).or_insert((0, v6));
+                    entry.0 += 1;
+                }
+                if result.v4.is_some() || result.v6.is_some() {
+                    debug!(stun = %stun_addr, "STUN server responded within probe timeout");
+                }
+            }
+            Ok((stun_addr, Ok(Err(e)))) => {
+                debug!(error = %e, stun = %stun_addr, "STUN probe failed");
+            }
+            Ok((stun_addr, Err(_))) => {
+                debug!(stun = %stun_addr, "STUN probe timeout");
+            }
+            Err(e) => {
+                debug!(error = %e, "STUN probe task join failed");
+            }
+        }
+    }
+
+    let mut out = DualStunResult::default();
+    if let Some((_, best)) = best_v4_by_ip
+        .into_values()
+        .max_by_key(|(count, _)| *count)
+    {
+        info!("STUN-Quorum reached, IP: {}", best.reflected_addr.ip());
+        out.v4 = Some(best);
+    }
+    if let Some((_, best)) = best_v6_by_ip
+        .into_values()
+        .max_by_key(|(count, _)| *count)
+    {
+        info!("STUN-Quorum reached, IP: {}", best.reflected_addr.ip());
+        out.v6 = Some(best);
+    }
+    out
+}
+
+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() || 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() || nat_ip_v6);
+
+    let effective_prefer = match config.prefer {
+        6 if ipv6_me || ipv6_dc => 6,
+        4 if ipv4_me || ipv4_dc => 4,
+        6 => {
+            warn!("prefer=6 requested but IPv6 unavailable; falling back to IPv4");
+            4
+        }
+        _ => 4,
+    };
+
+    let me_families = ipv4_me as u8 + ipv6_me as u8;
+    let effective_multipath = config.multipath && me_families >= 2;
+
+    NetworkDecision {
+        ipv4_dc,
+        ipv6_dc,
+        ipv4_me,
+        ipv6_me,
+        effective_prefer,
+        effective_multipath,
+    }
+}
+
+#[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()?;
+    match socket.local_addr().ok()?.ip() {
+        IpAddr::V4(v4) => Some(v4),
+        _ => None,
+    }
+}
+
+fn detect_local_ip_v6() -> Option<Ipv6Addr> {
+    let socket = UdpSocket::bind("[::]:0").ok()?;
+    socket.connect("[2001:4860:4860::8888]:80").ok()?;
+    match socket.local_addr().ok()?.ip() {
+        IpAddr::V6(v6) => Some(v6),
+        _ => None,
+    }
+}
+
+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),
+        IpAddr::V6(v6) => is_bogon_v6(v6),
+    }
+}
+
+pub fn is_bogon_v4(ip: Ipv4Addr) -> bool {
+    let octets = ip.octets();
+    if ip.is_private() || ip.is_loopback() || ip.is_link_local() {
+        return true;
+    }
+    if octets[0] == 0 {
+        return true;
+    }
+    if octets[0] == 100 && (octets[1] & 0xC0) == 64 {
+        return true;
+    }
+    if octets[0] == 192 && octets[1] == 0 && octets[2] == 0 {
+        return true;
+    }
+    if octets[0] == 192 && octets[1] == 0 && octets[2] == 2 {
+        return true;
+    }
+    if octets[0] == 198 && (octets[1] & 0xFE) == 18 {
+        return true;
+    }
+    if octets[0] == 198 && octets[1] == 51 && octets[2] == 100 {
+        return true;
+    }
+    if octets[0] == 203 && octets[1] == 0 && octets[2] == 113 {
+        return true;
+    }
+    if ip.is_multicast() {
+        return true;
+    }
+    if octets[0] >= 240 {
+        return true;
+    }
+    if ip.is_broadcast() {
+        return true;
+    }
+    false
+}
+
+pub fn is_bogon_v6(ip: Ipv6Addr) -> bool {
+    if ip.is_unspecified() || ip.is_loopback() || ip.is_unique_local() {
+        return true;
+    }
+    let segs = ip.segments();
+    if (segs[0] & 0xFFC0) == 0xFE80 {
+        return true;
+    }
+    if segs[0..5] == [0, 0, 0, 0, 0] && segs[5] == 0xFFFF {
+        return true;
+    }
+    if segs[0] == 0x0100 && segs[1..4] == [0, 0, 0] {
+        return true;
+    }
+    if segs[0] == 0x2001 && segs[1] == 0x0db8 {
+        return true;
+    }
+    if segs[0] == 0x2002 {
+        return true;
+    }
+    if ip.is_multicast() {
+        return true;
+    }
+    false
+}
+
+pub fn log_probe_result(probe: &NetworkProbe, decision: &NetworkDecision) {
+    info!(
+        ipv4 = probe.detected_ipv4.as_ref().map(|v| v.to_string()).unwrap_or_else(|| "-".into()),
+        ipv6 = probe.detected_ipv6.as_ref().map(|v| v.to_string()).unwrap_or_else(|| "-".into()),
+        reflected_v4 = probe.reflected_ipv4.as_ref().map(|v| v.ip().to_string()).unwrap_or_else(|| "-".into()),
+        reflected_v6 = probe.reflected_ipv6.as_ref().map(|v| v.ip().to_string()).unwrap_or_else(|| "-".into()),
+        ipv4_bogon = probe.ipv4_is_bogon,
+        ipv6_bogon = probe.ipv6_is_bogon,
+        ipv4_me = decision.ipv4_me,
+        ipv6_me = decision.ipv6_me,
+        ipv4_dc = decision.ipv4_dc,
+        ipv6_dc = decision.ipv6_dc,
+        prefer = decision.effective_prefer,
+        multipath = decision.effective_multipath,
+        "Network capabilities resolved"
+    );
+}

src/network/stun.rs

@@ -0,0 +1,234 @@
+#![allow(unreachable_code)]
+#![allow(dead_code)]
+
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
+
+use tokio::net::{lookup_host, UdpSocket};
+use tokio::time::{timeout, Duration, sleep};
+
+use crate::error::{ProxyError, Result};
+use crate::network::dns_overrides::{resolve, split_host_port};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum IpFamily {
+    V4,
+    V6,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct StunProbeResult {
+    pub local_addr: SocketAddr,
+    pub reflected_addr: SocketAddr,
+    pub family: IpFamily,
+}
+
+#[derive(Debug, Default, Clone)]
+pub struct DualStunResult {
+    pub v4: Option<StunProbeResult>,
+    pub v6: Option<StunProbeResult>,
+}
+
+pub async fn stun_probe_dual(stun_addr: &str) -> Result<DualStunResult> {
+    let (v4, v6) = tokio::join!(
+        stun_probe_family(stun_addr, IpFamily::V4),
+        stun_probe_family(stun_addr, IpFamily::V6),
+    );
+
+    Ok(DualStunResult {
+        v4: v4?,
+        v6: v6?,
+    })
+}
+
+pub async fn stun_probe_family(stun_addr: &str, family: IpFamily) -> Result<Option<StunProbeResult>> {
+    stun_probe_family_with_bind(stun_addr, family, None).await
+}
+
+pub async fn stun_probe_family_with_bind(
+    stun_addr: &str,
+    family: IpFamily,
+    bind_ip: Option<IpAddr>,
+) -> Result<Option<StunProbeResult>> {
+    use rand::RngCore;
+
+    let bind_addr = match (family, bind_ip) {
+        (IpFamily::V4, Some(IpAddr::V4(ip))) => SocketAddr::new(IpAddr::V4(ip), 0),
+        (IpFamily::V6, Some(IpAddr::V6(ip))) => SocketAddr::new(IpAddr::V6(ip), 0),
+        (IpFamily::V4, Some(IpAddr::V6(_))) | (IpFamily::V6, Some(IpAddr::V4(_))) => {
+            return Ok(None);
+        }
+        (IpFamily::V4, None) => SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 0),
+        (IpFamily::V6, None) => SocketAddr::new(IpAddr::V6(Ipv6Addr::UNSPECIFIED), 0),
+    };
+
+    let socket = match UdpSocket::bind(bind_addr).await {
+        Ok(socket) => socket,
+        Err(_) if bind_ip.is_some() => return Ok(None),
+        Err(e) => return Err(ProxyError::Proxy(format!("STUN bind failed: {e}"))),
+    };
+
+    let target_addr = resolve_stun_addr(stun_addr, family).await?;
+    if let Some(addr) = target_addr {
+        match socket.connect(addr).await {
+            Ok(()) => {}
+            Err(e) if family == IpFamily::V6 && matches!(
+                e.kind(),
+                std::io::ErrorKind::NetworkUnreachable
+                | std::io::ErrorKind::HostUnreachable
+                | std::io::ErrorKind::Unsupported
+                | std::io::ErrorKind::NetworkDown
+            ) => return Ok(None),
+            Err(e) => return Err(ProxyError::Proxy(format!("STUN connect failed: {e}"))),
+        }
+    } else {
+        return Ok(None);
+    }
+
+    let mut req = [0u8; 20];
+    req[0..2].copy_from_slice(&0x0001u16.to_be_bytes()); // Binding Request
+    req[2..4].copy_from_slice(&0u16.to_be_bytes()); // length
+    req[4..8].copy_from_slice(&0x2112A442u32.to_be_bytes()); // magic cookie
+    rand::rng().fill_bytes(&mut req[8..20]); // transaction ID
+
+    let mut buf = [0u8; 256];
+    let mut attempt = 0;
+    let mut backoff = Duration::from_secs(1);
+    loop {
+        socket
+            .send(&req)
+            .await
+            .map_err(|e| ProxyError::Proxy(format!("STUN send failed: {e}")))?;
+
+        let recv_res = timeout(Duration::from_secs(3), socket.recv(&mut buf)).await;
+        let n = match recv_res {
+            Ok(Ok(n)) => n,
+            Ok(Err(e)) => return Err(ProxyError::Proxy(format!("STUN recv failed: {e}"))),
+            Err(_) => {
+                attempt += 1;
+                if attempt >= 3 {
+                    return Ok(None);
+                }
+                sleep(backoff).await;
+                backoff *= 2;
+                continue;
+            }
+        };
+
+        if n < 20 {
+            return Ok(None);
+        }
+
+        let magic = 0x2112A442u32.to_be_bytes();
+        let txid = &req[8..20];
+    let mut idx = 20;
+    while idx + 4 <= n {
+        let atype = u16::from_be_bytes(buf[idx..idx + 2].try_into().unwrap());
+        let alen = u16::from_be_bytes(buf[idx + 2..idx + 4].try_into().unwrap()) as usize;
+        idx += 4;
+        if idx + alen > n {
+            break;
+        }
+
+        match atype {
+            0x0020 /* XOR-MAPPED-ADDRESS */ | 0x0001 /* MAPPED-ADDRESS */ => {
+                if alen < 8 {
+                    break;
+                }
+                let family_byte = buf[idx + 1];
+                let port_bytes = [buf[idx + 2], buf[idx + 3]];
+                let len_check = match family_byte {
+                    0x01 => 4,
+                    0x02 => 16,
+                    _ => 0,
+                };
+                if len_check == 0 || alen < 4 + len_check {
+                    break;
+                }
+
+                let raw_ip = &buf[idx + 4..idx + 4 + len_check];
+                let mut port = u16::from_be_bytes(port_bytes);
+
+                let reflected_ip = if atype == 0x0020 {
+                    port ^= ((magic[0] as u16) << 8) | magic[1] as u16;
+                    match family_byte {
+                        0x01 => {
+                            let ip = [
+                                raw_ip[0] ^ magic[0],
+                                raw_ip[1] ^ magic[1],
+                                raw_ip[2] ^ magic[2],
+                                raw_ip[3] ^ magic[3],
+                            ];
+                            IpAddr::V4(Ipv4Addr::new(ip[0], ip[1], ip[2], ip[3]))
+                        }
+                        0x02 => {
+                            let mut ip = [0u8; 16];
+                            let xor_key = [magic.as_slice(), txid].concat();
+                            for (i, b) in raw_ip.iter().enumerate().take(16) {
+                                ip[i] = *b ^ xor_key[i];
+                            }
+                            IpAddr::V6(Ipv6Addr::from(ip))
+                        }
+                        _ => {
+                            idx += (alen + 3) & !3;
+                            continue;
+                        }
+                    }
+                } else {
+                    match family_byte {
+                        0x01 => IpAddr::V4(Ipv4Addr::new(raw_ip[0], raw_ip[1], raw_ip[2], raw_ip[3])),
+                        0x02 => IpAddr::V6(Ipv6Addr::from(<[u8; 16]>::try_from(raw_ip).unwrap())),
+                        _ => {
+                            idx += (alen + 3) & !3;
+                            continue;
+                        }
+                    }
+                };
+
+                let reflected_addr = SocketAddr::new(reflected_ip, port);
+                let local_addr = socket
+                    .local_addr()
+                    .map_err(|e| ProxyError::Proxy(format!("STUN local_addr failed: {e}")))?;
+
+                return Ok(Some(StunProbeResult {
+                    local_addr,
+                    reflected_addr,
+                    family,
+                }));
+            }
+            _ => {}
+        }
+
+        idx += (alen + 3) & !3;
+    }
+
+    }
+
+    Ok(None)
+}
+
+async fn resolve_stun_addr(stun_addr: &str, family: IpFamily) -> Result<Option<SocketAddr>> {
+    if let Ok(addr) = stun_addr.parse::<SocketAddr>() {
+        return Ok(match (addr.is_ipv4(), family) {
+            (true, IpFamily::V4) | (false, IpFamily::V6) => Some(addr),
+            _ => None,
+        });
+    }
+
+    if let Some((host, port)) = split_host_port(stun_addr)
+        && let Some(ip) = resolve(&host, port)
+    {
+        let addr = SocketAddr::new(ip, port);
+        return Ok(match (addr.is_ipv4(), family) {
+            (true, IpFamily::V4) | (false, IpFamily::V6) => Some(addr),
+            _ => None,
+        });
+    }
+
+    let mut addrs = lookup_host(stun_addr)
+        .await
+        .map_err(|e| ProxyError::Proxy(format!("STUN resolve failed: {e}")))?;
+
+    let target = addrs
+        .find(|a| matches!((a.is_ipv4(), family), (true, IpFamily::V4) | (false, IpFamily::V6)));
+    Ok(target)
+}

src/protocol/constants.rs

@@ -1,13 +1,17 @@
 //! Protocol constants and datacenter addresses
 
-use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
-use once_cell::sync::Lazy;
+#![allow(dead_code)]
+
+use std::net::{IpAddr, Ipv4Addr};
+
+use crate::crypto::SecureRandom;
+use std::sync::LazyLock;
 
 // ============= Telegram Datacenters =============
 
 pub const TG_DATACENTER_PORT: u16 = 443;
 
-pub static TG_DATACENTERS_V4: Lazy<Vec<IpAddr>> = Lazy::new(|| {
+pub static TG_DATACENTERS_V4: LazyLock<Vec<IpAddr>> = LazyLock::new(|| {
     vec![
         IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)),
         IpAddr::V4(Ipv4Addr::new(149, 154, 167, 51)),
@@ -17,7 +21,7 @@ pub static TG_DATACENTERS_V4: Lazy<Vec<IpAddr>> = Lazy::new(|| {
     ]
 });
 
-pub static TG_DATACENTERS_V6: Lazy<Vec<IpAddr>> = Lazy::new(|| {
+pub static TG_DATACENTERS_V6: LazyLock<Vec<IpAddr>> = LazyLock::new(|| {
     vec![
         IpAddr::V6("2001:b28:f23d:f001::a".parse().unwrap()),
         IpAddr::V6("2001:67c:04e8:f002::a".parse().unwrap()),
@@ -29,8 +33,8 @@ pub static TG_DATACENTERS_V6: Lazy<Vec<IpAddr>> = Lazy::new(|| {
 
 // ============= Middle Proxies (for advertising) =============
 
-pub static TG_MIDDLE_PROXIES_V4: Lazy<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> = 
-    Lazy::new(|| {
+pub static TG_MIDDLE_PROXIES_V4: LazyLock<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> = 
+    LazyLock::new(|| {
         let mut m = std::collections::HashMap::new();
         m.insert(1, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888)]);
         m.insert(-1, vec![(IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888)]);
@@ -45,8 +49,8 @@ pub static TG_MIDDLE_PROXIES_V4: Lazy<std::collections::HashMap<i32, Vec<(IpAddr
         m
     });
 
-pub static TG_MIDDLE_PROXIES_V6: Lazy<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> = 
-    Lazy::new(|| {
+pub static TG_MIDDLE_PROXIES_V6: LazyLock<std::collections::HashMap<i32, Vec<(IpAddr, u16)>>> = 
+    LazyLock::new(|| {
         let mut m = std::collections::HashMap::new();
         m.insert(1, vec![(IpAddr::V6("2001:b28:f23d:f001::d".parse().unwrap()), 8888)]);
         m.insert(-1, vec![(IpAddr::V6("2001:b28:f23d:f001::d".parse().unwrap()), 8888)]);
@@ -151,7 +155,32 @@ pub const TLS_RECORD_ALERT: u8 = 0x15;
 /// Maximum TLS record size
 pub const MAX_TLS_RECORD_SIZE: usize = 16384;
 /// Maximum TLS chunk size (with overhead)
-pub const MAX_TLS_CHUNK_SIZE: usize = 16384 + 24;
+/// RFC 8446 §5.2 allows up to 16384 + 256 bytes of ciphertext
+pub const MAX_TLS_CHUNK_SIZE: usize = 16384 + 256;
+
+/// Secure Intermediate payload is expected to be 4-byte aligned.
+pub fn is_valid_secure_payload_len(data_len: usize) -> bool {
+    data_len.is_multiple_of(4)
+}
+
+/// Compute Secure Intermediate payload length from wire length.
+/// Secure mode strips up to 3 random tail bytes by truncating to 4-byte boundary.
+pub fn secure_payload_len_from_wire_len(wire_len: usize) -> Option<usize> {
+    if wire_len < 4 {
+        return None;
+    }
+    Some(wire_len - (wire_len % 4))
+}
+
+/// Generate padding length for Secure Intermediate protocol.
+/// Data must be 4-byte aligned; padding is 1..=3 so total is never divisible by 4.
+pub fn secure_padding_len(data_len: usize, rng: &SecureRandom) -> usize {
+    debug_assert!(
+        is_valid_secure_payload_len(data_len),
+        "Secure payload must be 4-byte aligned, got {data_len}"
+    );
+    rng.range(3) + 1
+}
 
 // ============= Timeouts =============
 
@@ -167,7 +196,8 @@ pub const DEFAULT_ACK_TIMEOUT_SECS: u64 = 300;
 // ============= Buffer Sizes =============
 
 /// Default buffer size
-pub const DEFAULT_BUFFER_SIZE: usize = 65536;
+pub const DEFAULT_BUFFER_SIZE: usize = 16384;
+
 /// Small buffer size for bad client handling
 pub const SMALL_BUFFER_SIZE: usize = 8192;
 
@@ -201,6 +231,16 @@ pub static RESERVED_NONCE_CONTINUES: &[[u8; 4]] = &[
 // ============= RPC Constants (for Middle Proxy) =============
 
 /// RPC Proxy Request
+/// RPC Flags (from Erlang mtp_rpc.erl)
+pub const RPC_FLAG_NOT_ENCRYPTED: u32 = 0x2;
+pub const RPC_FLAG_HAS_AD_TAG: u32    = 0x8;
+pub const RPC_FLAG_MAGIC: u32          = 0x1000;
+pub const RPC_FLAG_EXTMODE2: u32       = 0x20000;
+pub const RPC_FLAG_PAD: u32            = 0x8000000;
+pub const RPC_FLAG_INTERMEDIATE: u32   = 0x20000000;
+pub const RPC_FLAG_ABRIDGED: u32       = 0x40000000;
+pub const RPC_FLAG_QUICKACK: u32       = 0x80000000;
+
 pub const RPC_PROXY_REQ: [u8; 4] = [0xee, 0xf1, 0xce, 0x36];
 /// RPC Proxy Answer
 pub const RPC_PROXY_ANS: [u8; 4] = [0x0d, 0xda, 0x03, 0x44];
@@ -227,7 +267,60 @@ pub mod rpc_flags {
     pub const FLAG_QUICKACK: u32 = 0x80000000;
 }
 
-#[cfg(test)]
+
+    // ============= Middle-End Proxy Servers =============
+    pub const ME_PROXY_PORT: u16 = 8888;
+    
+    pub static TG_MIDDLE_PROXIES_FLAT_V4: LazyLock<Vec<(IpAddr, u16)>> = LazyLock::new(|| {
+        vec![
+            (IpAddr::V4(Ipv4Addr::new(149, 154, 175, 50)), 8888),
+            (IpAddr::V4(Ipv4Addr::new(149, 154, 161, 144)), 8888),
+            (IpAddr::V4(Ipv4Addr::new(149, 154, 175, 100)), 8888),
+            (IpAddr::V4(Ipv4Addr::new(91, 108, 4, 136)), 8888),
+            (IpAddr::V4(Ipv4Addr::new(91, 108, 56, 183)), 8888),
+        ]
+    });
+    
+    // ============= RPC Constants (u32 native endian) =============
+    // From mtproto-common.h + net-tcp-rpc-common.h + mtproto-proxy.c
+    
+    pub const RPC_NONCE_U32: u32           = 0x7acb87aa;
+    pub const RPC_HANDSHAKE_U32: u32       = 0x7682eef5;
+    pub const RPC_HANDSHAKE_ERROR_U32: u32 = 0x6a27beda;
+    pub const TL_PROXY_TAG_U32: u32        = 0xdb1e26ae;  // mtproto-proxy.c:121
+    
+    // mtproto-common.h
+    pub const RPC_PROXY_REQ_U32: u32       = 0x36cef1ee;
+    pub const RPC_PROXY_ANS_U32: u32       = 0x4403da0d;
+    pub const RPC_CLOSE_CONN_U32: u32      = 0x1fcf425d;
+    pub const RPC_CLOSE_EXT_U32: u32       = 0x5eb634a2;
+    pub const RPC_SIMPLE_ACK_U32: u32      = 0x3bac409b;
+    pub const RPC_PING_U32: u32            = 0x5730a2df;
+    pub const RPC_PONG_U32: u32            = 0x8430eaa7;
+    
+    pub const RPC_CRYPTO_NONE_U32: u32 = 0;
+    pub const RPC_CRYPTO_AES_U32: u32  = 1;
+    
+    pub mod proxy_flags {
+        pub const FLAG_HAS_AD_TAG: u32    = 1;
+        pub const FLAG_NOT_ENCRYPTED: u32 = 0x2;
+        pub const FLAG_HAS_AD_TAG2: u32   = 0x8;
+        pub const FLAG_MAGIC: u32         = 0x1000;
+        pub const FLAG_EXTMODE2: u32      = 0x20000;
+        pub const FLAG_PAD: u32           = 0x8000000;
+        pub const FLAG_INTERMEDIATE: u32  = 0x20000000;
+        pub const FLAG_ABRIDGED: u32      = 0x40000000;
+        pub const FLAG_QUICKACK: u32      = 0x80000000;
+    }
+
+    pub mod rpc_crypto_flags {
+        pub const USE_CRC32C: u32 = 0x800;
+    }
+    
+    pub const ME_CONNECT_TIMEOUT_SECS: u64 = 5;
+    pub const ME_HANDSHAKE_TIMEOUT_SECS: u64 = 10;
+    
+    #[cfg(test)]
 mod tests {
     use super::*;
     
@@ -258,4 +351,43 @@ mod tests {
         assert_eq!(TG_DATACENTERS_V4.len(), 5);
         assert_eq!(TG_DATACENTERS_V6.len(), 5);
     }
-}
+
+    #[test]
+    fn secure_padding_never_produces_aligned_total() {
+        let rng = SecureRandom::new();
+        for data_len in (0..1000).step_by(4) {
+            for _ in 0..100 {
+                let padding = secure_padding_len(data_len, &rng);
+                assert!(
+                    padding <= 3,
+                    "padding out of range: data_len={data_len}, padding={padding}"
+                );
+                assert_ne!(
+                    (data_len + padding) % 4,
+                    0,
+                    "invariant violated: data_len={data_len}, padding={padding}, total={}",
+                    data_len + padding
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn secure_wire_len_roundtrip_for_aligned_payload() {
+        for payload_len in (4..4096).step_by(4) {
+            for padding in 0..=3usize {
+                let wire_len = payload_len + padding;
+                let recovered = secure_payload_len_from_wire_len(wire_len);
+                assert_eq!(recovered, Some(payload_len));
+            }
+        }
+    }
+
+    #[test]
+    fn secure_wire_len_rejects_too_short_frames() {
+        assert_eq!(secure_payload_len_from_wire_len(0), None);
+        assert_eq!(secure_payload_len_from_wire_len(1), None);
+        assert_eq!(secure_payload_len_from_wire_len(2), None);
+        assert_eq!(secure_payload_len_from_wire_len(3), None);
+    }
+}

src/protocol/frame.rs

@@ -1,5 +1,7 @@
 //! MTProto frame types and metadata
 
+#![allow(dead_code)]
+
 use std::collections::HashMap;
 
 /// Extra metadata associated with a frame
@@ -83,7 +85,7 @@ impl FrameMode {
 pub fn validate_message_length(len: usize) -> bool {
     use super::constants::{MIN_MSG_LEN, MAX_MSG_LEN, PADDING_FILLER};
     
-    len >= MIN_MSG_LEN && len <= MAX_MSG_LEN && len % PADDING_FILLER.len() == 0
+    (MIN_MSG_LEN..=MAX_MSG_LEN).contains(&len) && len.is_multiple_of(PADDING_FILLER.len())
 }
 
 #[cfg(test)]

src/protocol/mod.rs

@@ -5,7 +5,11 @@ pub mod frame;
 pub mod obfuscation;
 pub mod tls;
 
+#[allow(unused_imports)]
 pub use constants::*;
+#[allow(unused_imports)]
 pub use frame::*;
+#[allow(unused_imports)]
 pub use obfuscation::*;
+#[allow(unused_imports)]
 pub use tls::*;

src/protocol/obfuscation.rs

@@ -1,10 +1,14 @@
 //! MTProto Obfuscation
 
+#![allow(dead_code)]
+
+use zeroize::Zeroize;
 use crate::crypto::{sha256, AesCtr};
-use crate::error::Result;
 use super::constants::*;
 
 /// Obfuscation parameters from handshake
+///
+/// Key material is zeroized on drop.
 #[derive(Debug, Clone)]
 pub struct ObfuscationParams {
     /// Key for decrypting client -> proxy traffic
@@ -21,25 +25,31 @@ pub struct ObfuscationParams {
     pub dc_idx: i16,
 }
 
+impl Drop for ObfuscationParams {
+    fn drop(&mut self) {
+        self.decrypt_key.zeroize();
+        self.decrypt_iv.zeroize();
+        self.encrypt_key.zeroize();
+        self.encrypt_iv.zeroize();
+    }
+}
+
 impl ObfuscationParams {
     /// Parse obfuscation parameters from handshake bytes
     /// Returns None if handshake doesn't match any user secret
     pub fn from_handshake(
         handshake: &[u8; HANDSHAKE_LEN],
-        secrets: &[(String, Vec<u8>)], // (username, secret_bytes)
+        secrets: &[(String, Vec<u8>)],
     ) -> Option<(Self, String)> {
-        // Extract prekey and IV for decryption
         let dec_prekey_iv = &handshake[SKIP_LEN..SKIP_LEN + PREKEY_LEN + IV_LEN];
         let dec_prekey = &dec_prekey_iv[..PREKEY_LEN];
         let dec_iv_bytes = &dec_prekey_iv[PREKEY_LEN..];
         
-        // Reversed for encryption direction
         let enc_prekey_iv: Vec<u8> = dec_prekey_iv.iter().rev().copied().collect();
         let enc_prekey = &enc_prekey_iv[..PREKEY_LEN];
         let enc_iv_bytes = &enc_prekey_iv[PREKEY_LEN..];
         
         for (username, secret) in secrets {
-            // Derive decryption key
             let mut dec_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
             dec_key_input.extend_from_slice(dec_prekey);
             dec_key_input.extend_from_slice(secret);
@@ -47,26 +57,22 @@ impl ObfuscationParams {
             
             let decrypt_iv = u128::from_be_bytes(dec_iv_bytes.try_into().unwrap());
             
-            // Create decryptor and decrypt handshake
             let mut decryptor = AesCtr::new(&decrypt_key, decrypt_iv);
             let decrypted = decryptor.decrypt(handshake);
             
-            // Check protocol tag
             let tag_bytes: [u8; 4] = decrypted[PROTO_TAG_POS..PROTO_TAG_POS + 4]
                 .try_into()
                 .unwrap();
             
             let proto_tag = match ProtoTag::from_bytes(tag_bytes) {
                 Some(tag) => tag,
-                None => continue, // Try next secret
+                None => continue,
             };
             
-            // Extract DC index
             let dc_idx = i16::from_le_bytes(
                 decrypted[DC_IDX_POS..DC_IDX_POS + 2].try_into().unwrap()
             );
             
-            // Derive encryption key
             let mut enc_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
             enc_key_input.extend_from_slice(enc_prekey);
             enc_key_input.extend_from_slice(secret);
@@ -123,18 +129,15 @@ pub fn generate_nonce<R: FnMut(usize) -> Vec<u8>>(mut random_bytes: R) -> [u8; H
 
 /// Check if nonce is valid (not matching reserved patterns)
 pub fn is_valid_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> bool {
-    // Check first byte
     if RESERVED_NONCE_FIRST_BYTES.contains(&nonce[0]) {
         return false;
     }
     
-    // Check first 4 bytes
     let first_four: [u8; 4] = nonce[..4].try_into().unwrap();
     if RESERVED_NONCE_BEGINNINGS.contains(&first_four) {
         return false;
     }
     
-    // Check bytes 4-7
     let continue_four: [u8; 4] = nonce[4..8].try_into().unwrap();
     if RESERVED_NONCE_CONTINUES.contains(&continue_four) {
         return false;
@@ -147,12 +150,10 @@ pub fn is_valid_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> bool {
 pub fn prepare_tg_nonce(
     nonce: &mut [u8; HANDSHAKE_LEN],
     proto_tag: ProtoTag,
-    enc_key_iv: Option<&[u8]>, // For fast mode
+    enc_key_iv: Option<&[u8]>,
 ) {
-    // Set protocol tag
     nonce[PROTO_TAG_POS..PROTO_TAG_POS + 4].copy_from_slice(&proto_tag.to_bytes());
     
-    // For fast mode, copy the reversed enc_key_iv
     if let Some(key_iv) = enc_key_iv {
         let reversed: Vec<u8> = key_iv.iter().rev().copied().collect();
         nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN].copy_from_slice(&reversed);
@@ -160,15 +161,19 @@ pub fn prepare_tg_nonce(
 }
 
 /// Encrypt the outgoing nonce for Telegram
+/// Legacy helper — **do not use**.
+/// WARNING: logic diverges from Python/C reference (SHA256 of 48 bytes, IV from head).
+/// Kept only to avoid breaking external callers; prefer `encrypt_tg_nonce_with_ciphers`.
+#[deprecated(
+    note = "Incorrect MTProto obfuscation KDF; use proxy::handshake::encrypt_tg_nonce_with_ciphers"
+)]
 pub fn encrypt_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> Vec<u8> {
-    // Derive encryption key from the nonce itself
     let key_iv = &nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN];
     let enc_key = sha256(key_iv);
     let enc_iv = u128::from_be_bytes(key_iv[..IV_LEN].try_into().unwrap());
     
     let mut encryptor = AesCtr::new(&enc_key, enc_iv);
     
-    // Only encrypt from PROTO_TAG_POS onwards
     let mut result = nonce.to_vec();
     let encrypted_part = encryptor.encrypt(&nonce[PROTO_TAG_POS..]);
     result[PROTO_TAG_POS..].copy_from_slice(&encrypted_part);
@@ -182,22 +187,18 @@ mod tests {
     
     #[test]
     fn test_is_valid_nonce() {
-        // Valid nonce
         let mut valid = [0x42u8; HANDSHAKE_LEN];
         valid[4..8].copy_from_slice(&[1, 2, 3, 4]);
         assert!(is_valid_nonce(&valid));
         
-        // Invalid: starts with 0xef
         let mut invalid = [0x00u8; HANDSHAKE_LEN];
         invalid[0] = 0xef;
         assert!(!is_valid_nonce(&invalid));
         
-        // Invalid: starts with HEAD
         let mut invalid = [0x00u8; HANDSHAKE_LEN];
         invalid[..4].copy_from_slice(b"HEAD");
         assert!(!is_valid_nonce(&invalid));
         
-        // Invalid: bytes 4-7 are zeros
         let mut invalid = [0x42u8; HANDSHAKE_LEN];
         invalid[4..8].copy_from_slice(&[0, 0, 0, 0]);
         assert!(!is_valid_nonce(&invalid));
@@ -214,4 +215,4 @@ mod tests {
         assert!(is_valid_nonce(&nonce));
         assert_eq!(nonce.len(), HANDSHAKE_LEN);
     }
-}
+}

src/protocol/tls.rs

@@ -4,10 +4,15 @@
 //! for domain fronting. The handshake looks like valid TLS 1.3 but
 //! actually carries MTProto authentication data.
 
-use crate::crypto::{sha256_hmac, random::SECURE_RANDOM};
-use crate::error::{ProxyError, Result};
+#![allow(dead_code)]
+
+use crate::crypto::{sha256_hmac, SecureRandom};
+#[cfg(test)]
+use crate::error::ProxyError;
 use super::constants::*;
 use std::time::{SystemTime, UNIX_EPOCH};
+use num_bigint::BigUint;
+use num_traits::One;
 
 // ============= Public Constants =============
 
@@ -30,6 +35,7 @@ pub const TIME_SKEW_MAX: i64 = 10 * 60;  // 10 minutes after
 mod extension_type {
     pub const KEY_SHARE: u16 = 0x0033;
     pub const SUPPORTED_VERSIONS: u16 = 0x002b;
+    pub const ALPN: u16 = 0x0010;
 }
 
 /// TLS Cipher Suites
@@ -60,6 +66,7 @@ pub struct TlsValidation {
 // ============= TLS Extension Builder =============
 
 /// Builder for TLS extensions with correct length calculation
+#[derive(Clone)]
 struct TlsExtensionBuilder {
     extensions: Vec<u8>,
 }
@@ -106,6 +113,27 @@ impl TlsExtensionBuilder {
         
         self
     }
+
+    /// Add ALPN extension with a single selected protocol.
+    fn add_alpn(&mut self, proto: &[u8]) -> &mut Self {
+        // Extension type: ALPN (0x0010)
+        self.extensions.extend_from_slice(&extension_type::ALPN.to_be_bytes());
+
+        // ALPN extension format:
+        // extension_data length (2 bytes)
+        //   protocols length (2 bytes)
+        //     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 ext_len: u16 = 2 + list_len;
+
+        self.extensions.extend_from_slice(&ext_len.to_be_bytes());
+        self.extensions.extend_from_slice(&list_len.to_be_bytes());
+        self.extensions.push(proto_len);
+        self.extensions.extend_from_slice(proto);
+        self
+    }
     
     /// Build final extensions with length prefix
     fn build(self) -> Vec<u8> {
@@ -142,6 +170,8 @@ struct ServerHelloBuilder {
     compression: u8,
     /// Extensions
     extensions: TlsExtensionBuilder,
+    /// Selected ALPN protocol (if any)
+    alpn: Option<Vec<u8>>,
 }
 
 impl ServerHelloBuilder {
@@ -152,6 +182,7 @@ impl ServerHelloBuilder {
             cipher_suite: cipher_suite::TLS_AES_128_GCM_SHA256,
             compression: 0x00,
             extensions: TlsExtensionBuilder::new(),
+            alpn: None,
         }
     }
     
@@ -165,10 +196,19 @@ impl ServerHelloBuilder {
         self.extensions.add_supported_versions(0x0304);
         self
     }
+
+    fn with_alpn(mut self, proto: Option<Vec<u8>>) -> Self {
+        self.alpn = proto;
+        self
+    }
     
     /// Build ServerHello message (without record header)
     fn build_message(&self) -> Vec<u8> {
-        let extensions = self.extensions.extensions.clone();
+        let mut ext_builder = self.extensions.clone();
+        if let Some(ref alpn) = self.alpn {
+            ext_builder.add_alpn(alpn);
+        }
+        let extensions = ext_builder.extensions.clone();
         let extensions_len = extensions.len() as u16;
         
         // Calculate total length
@@ -295,7 +335,7 @@ pub fn validate_tls_handshake(
             // 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_diff < TIME_SKEW_MIN || time_diff > TIME_SKEW_MAX) {
+            if !is_boot_time && !(TIME_SKEW_MIN..=TIME_SKEW_MAX).contains(&time_diff) {
                 continue;
             }
         }
@@ -311,13 +351,27 @@ pub fn validate_tls_handshake(
     None
 }
 
+fn curve25519_prime() -> BigUint {
+    (BigUint::one() << 255) - BigUint::from(19u32)
+}
+
 /// Generate a fake X25519 public key for TLS
 ///
-/// This generates random bytes that look like a valid X25519 public key.
-/// Since we're not doing real TLS, the actual cryptographic properties don't matter.
-pub fn gen_fake_x25519_key() -> [u8; 32] {
-    let bytes = SECURE_RANDOM.bytes(32);
-    bytes.try_into().unwrap()
+/// Produces a quadratic residue mod p = 2^255 - 19 by computing n² mod p,
+/// which matches Python/C behavior and avoids DPI fingerprinting.
+pub fn gen_fake_x25519_key(rng: &SecureRandom) -> [u8; 32] {
+    let mut n_bytes = [0u8; 32];
+    n_bytes.copy_from_slice(&rng.bytes(32));
+
+    let n = BigUint::from_bytes_le(&n_bytes);
+    let p = curve25519_prime();
+    let pk = (&n * &n) % &p;
+
+    let mut out = pk.to_bytes_le();
+    out.resize(32, 0);
+    let mut result = [0u8; 32];
+    result.copy_from_slice(&out[..32]);
+    result
 }
 
 /// Build TLS ServerHello response
@@ -333,13 +387,20 @@ pub fn build_server_hello(
     client_digest: &[u8; TLS_DIGEST_LEN],
     session_id: &[u8],
     fake_cert_len: usize,
+    rng: &SecureRandom,
+    alpn: Option<Vec<u8>>,
+    new_session_tickets: u8,
 ) -> Vec<u8> {
-    let x25519_key = gen_fake_x25519_key();
+    const MIN_APP_DATA: usize = 64;
+    const MAX_APP_DATA: usize = 16640; // RFC 8446 §5.2 upper bound
+    let fake_cert_len = fake_cert_len.clamp(MIN_APP_DATA, MAX_APP_DATA);
+    let x25519_key = gen_fake_x25519_key(rng);
     
     // Build ServerHello
     let server_hello = ServerHelloBuilder::new(session_id.to_vec())
         .with_x25519_key(&x25519_key)
         .with_tls13_version()
+        .with_alpn(alpn)
         .build_record();
     
     // Build Change Cipher Spec record
@@ -351,20 +412,40 @@ pub fn build_server_hello(
     ];
     
     // Build fake certificate (Application Data record)
-    let fake_cert = SECURE_RANDOM.bytes(fake_cert_len);
+    let fake_cert = rng.bytes(fake_cert_len);
     let mut app_data_record = Vec::with_capacity(5 + fake_cert_len);
     app_data_record.push(TLS_RECORD_APPLICATION);
     app_data_record.extend_from_slice(&TLS_VERSION);
     app_data_record.extend_from_slice(&(fake_cert_len as u16).to_be_bytes());
+    // Fill ApplicationData with fully random bytes of desired length to avoid
+    // deterministic DPI fingerprints (fixed inner content type markers).
     app_data_record.extend_from_slice(&fake_cert);
     
+    // Build optional NewSessionTicket records (TLS 1.3 handshake messages are encrypted;
+    // here we mimic with opaque ApplicationData records of plausible size).
+    let mut tickets = Vec::new();
+    if new_session_tickets > 0 {
+        for _ in 0..new_session_tickets {
+            let ticket_len: usize = rng.range(48) + 48; // 48-95 bytes
+            let mut record = Vec::with_capacity(5 + ticket_len);
+            record.push(TLS_RECORD_APPLICATION);
+            record.extend_from_slice(&TLS_VERSION);
+            record.extend_from_slice(&(ticket_len as u16).to_be_bytes());
+            record.extend_from_slice(&rng.bytes(ticket_len));
+            tickets.push(record);
+        }
+    }
+
     // Combine all records
     let mut response = Vec::with_capacity(
-        server_hello.len() + change_cipher_spec.len() + app_data_record.len()
+        server_hello.len() + change_cipher_spec.len() + app_data_record.len() + tickets.iter().map(|r| r.len()).sum::<usize>()
     );
     response.extend_from_slice(&server_hello);
     response.extend_from_slice(&change_cipher_spec);
     response.extend_from_slice(&app_data_record);
+    for t in &tickets {
+        response.extend_from_slice(t);
+    }
     
     // Compute HMAC for the response
     let mut hmac_input = Vec::with_capacity(TLS_DIGEST_LEN + response.len());
@@ -380,6 +461,131 @@ pub fn build_server_hello(
     response
 }
 
+/// Extract SNI (server_name) from a TLS ClientHello.
+pub fn extract_sni_from_client_hello(handshake: &[u8]) -> Option<String> {
+    if handshake.len() < 43 || handshake[0] != TLS_RECORD_HANDSHAKE {
+        return None;
+    }
+
+    let mut pos = 5; // after record header
+    if handshake.get(pos).copied()? != 0x01 {
+        return None; // not ClientHello
+    }
+
+    // Handshake length bytes
+    pos += 4; // type + len (3)
+
+    // version (2) + random (32)
+    pos += 2 + 32;
+    if pos + 1 > handshake.len() {
+        return None;
+    }
+
+    let session_id_len = *handshake.get(pos)? as usize;
+    pos += 1 + session_id_len;
+    if pos + 2 > handshake.len() {
+        return None;
+    }
+
+    let cipher_suites_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    pos += 2 + cipher_suites_len;
+    if pos + 1 > handshake.len() {
+        return None;
+    }
+
+    let comp_len = *handshake.get(pos)? as usize;
+    pos += 1 + comp_len;
+    if pos + 2 > handshake.len() {
+        return None;
+    }
+
+    let ext_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+    pos += 2;
+    let ext_end = pos + ext_len;
+    if ext_end > handshake.len() {
+        return None;
+    }
+
+    while pos + 4 <= ext_end {
+        let etype = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]);
+        let elen = u16::from_be_bytes([handshake[pos + 2], handshake[pos + 3]]) as usize;
+        pos += 4;
+        if pos + elen > ext_end {
+            break;
+        }
+        if etype == 0x0000 && elen >= 5 {
+            // server_name extension
+            let list_len = u16::from_be_bytes([handshake[pos], handshake[pos + 1]]) as usize;
+            let mut sn_pos = pos + 2;
+            let sn_end = std::cmp::min(sn_pos + list_len, pos + elen);
+            while sn_pos + 3 <= sn_end {
+                let name_type = handshake[sn_pos];
+                let name_len = u16::from_be_bytes([handshake[sn_pos + 1], handshake[sn_pos + 2]]) as usize;
+                sn_pos += 3;
+                if sn_pos + name_len > sn_end {
+                    break;
+                }
+                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());
+                }
+                sn_pos += name_len;
+            }
+        }
+        pos += elen;
+    }
+
+    None
+}
+
+/// 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
+    if handshake.get(pos) != Some(&0x01) {
+        return Vec::new();
+    }
+    pos += 4; // type + len
+    pos += 2 + 32; // version + random
+    if pos >= handshake.len() { return Vec::new(); }
+    let session_id_len = *handshake.get(pos).unwrap_or(&0) as usize;
+    pos += 1 + session_id_len;
+    if pos + 2 > handshake.len() { return Vec::new(); }
+    let cipher_len = u16::from_be_bytes([handshake[pos], handshake[pos+1]]) as usize;
+    pos += 2 + cipher_len;
+    if pos >= handshake.len() { return Vec::new(); }
+    let comp_len = *handshake.get(pos).unwrap_or(&0) as usize;
+    pos += 1 + comp_len;
+    if pos + 2 > handshake.len() { return Vec::new(); }
+    let ext_len = u16::from_be_bytes([handshake[pos], handshake[pos+1]]) as usize;
+    pos += 2;
+    let ext_end = pos + ext_len;
+    if ext_end > handshake.len() { return Vec::new(); }
+    let mut out = Vec::new();
+    while pos + 4 <= ext_end {
+        let etype = u16::from_be_bytes([handshake[pos], handshake[pos+1]]);
+        let elen = u16::from_be_bytes([handshake[pos+2], handshake[pos+3]]) as usize;
+        pos += 4;
+        if pos + elen > ext_end { break; }
+        if etype == extension_type::ALPN && elen >= 3 {
+            let list_len = u16::from_be_bytes([handshake[pos], handshake[pos+1]]) as usize;
+            let mut lp = pos + 2;
+            let list_end = (pos + 2).saturating_add(list_len).min(pos + elen);
+            while lp < list_end {
+                let plen = handshake[lp] as usize;
+                lp += 1;
+                if lp + plen > list_end { break; }
+                out.push(handshake[lp..lp+plen].to_vec());
+                lp += plen;
+            }
+            break;
+        }
+        pos += elen;
+    }
+    out
+}
+
+
 /// Check if bytes look like a TLS ClientHello
 pub fn is_tls_handshake(first_bytes: &[u8]) -> bool {
     if first_bytes.len() < 3 {
@@ -410,7 +616,7 @@ pub fn parse_tls_record_header(header: &[u8; 5]) -> Option<(u8, u16)> {
 ///
 /// This is useful for testing that our ServerHello is well-formed.
 #[cfg(test)]
-fn validate_server_hello_structure(data: &[u8]) -> Result<()> {
+fn validate_server_hello_structure(data: &[u8]) -> Result<(), ProxyError> {
     if data.len() < 5 {
         return Err(ProxyError::InvalidTlsRecord {
             record_type: 0,
@@ -489,13 +695,25 @@ mod tests {
     
     #[test]
     fn test_gen_fake_x25519_key() {
-        let key1 = gen_fake_x25519_key();
-        let key2 = 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
     }
+
+    #[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() {
@@ -545,7 +763,8 @@ mod tests {
         let client_digest = [0x42u8; 32];
         let session_id = vec![0xAA; 32];
         
-        let response = build_server_hello(secret, &client_digest, &session_id, 2048);
+        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);
@@ -577,8 +796,9 @@ mod tests {
         let client_digest = [0x42u8; 32];
         let session_id = vec![0xAA; 32];
         
-        let response1 = build_server_hello(secret, &client_digest, &session_id, 1024);
-        let response2 = build_server_hello(secret, &client_digest, &session_id, 1024);
+        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];
@@ -637,4 +857,101 @@ mod tests {
         // Should return None (no match) but not panic
         assert!(result.is_none());
     }
-}
+
+    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
+
+        // 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);
+
+        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"]);
+    }
+}

src/proxy/adaptive_buffers.rs

@@ -0,0 +1,383 @@
+use dashmap::DashMap;
+use std::cmp::max;
+use std::sync::OnceLock;
+use std::time::{Duration, Instant};
+
+const EMA_ALPHA: f64 = 0.2;
+const PROFILE_TTL: Duration = Duration::from_secs(300);
+const THROUGHPUT_UP_BPS: f64 = 8_000_000.0;
+const THROUGHPUT_DOWN_BPS: f64 = 2_000_000.0;
+const RATIO_CONFIRM_THRESHOLD: f64 = 1.12;
+const TIER1_HOLD_TICKS: u32 = 8;
+const TIER2_HOLD_TICKS: u32 = 4;
+const QUIET_DEMOTE_TICKS: u32 = 480;
+const HARD_COOLDOWN_TICKS: u32 = 20;
+const HARD_PENDING_THRESHOLD: u32 = 3;
+const HARD_PARTIAL_RATIO_THRESHOLD: f64 = 0.25;
+const DIRECT_C2S_CAP_BYTES: usize = 128 * 1024;
+const DIRECT_S2C_CAP_BYTES: usize = 512 * 1024;
+const ME_FRAMES_CAP: usize = 96;
+const ME_BYTES_CAP: usize = 384 * 1024;
+const ME_DELAY_MIN_US: u64 = 150;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum AdaptiveTier {
+    Base = 0,
+    Tier1 = 1,
+    Tier2 = 2,
+    Tier3 = 3,
+}
+
+impl AdaptiveTier {
+    pub fn promote(self) -> Self {
+        match self {
+            Self::Base => Self::Tier1,
+            Self::Tier1 => Self::Tier2,
+            Self::Tier2 => Self::Tier3,
+            Self::Tier3 => Self::Tier3,
+        }
+    }
+
+    pub fn demote(self) -> Self {
+        match self {
+            Self::Base => Self::Base,
+            Self::Tier1 => Self::Base,
+            Self::Tier2 => Self::Tier1,
+            Self::Tier3 => Self::Tier2,
+        }
+    }
+
+    fn ratio(self) -> (usize, usize) {
+        match self {
+            Self::Base => (1, 1),
+            Self::Tier1 => (5, 4),
+            Self::Tier2 => (3, 2),
+            Self::Tier3 => (2, 1),
+        }
+    }
+
+    pub fn as_u8(self) -> u8 {
+        self as u8
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TierTransitionReason {
+    SoftConfirmed,
+    HardPressure,
+    QuietDemotion,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TierTransition {
+    pub from: AdaptiveTier,
+    pub to: AdaptiveTier,
+    pub reason: TierTransitionReason,
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+pub struct RelaySignalSample {
+    pub c2s_bytes: u64,
+    pub s2c_requested_bytes: u64,
+    pub s2c_written_bytes: u64,
+    pub s2c_write_ops: u64,
+    pub s2c_partial_writes: u64,
+    pub s2c_consecutive_pending_writes: u32,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct SessionAdaptiveController {
+    tier: AdaptiveTier,
+    max_tier_seen: AdaptiveTier,
+    throughput_ema_bps: f64,
+    incoming_ema_bps: f64,
+    outgoing_ema_bps: f64,
+    tier1_hold_ticks: u32,
+    tier2_hold_ticks: u32,
+    quiet_ticks: u32,
+    hard_cooldown_ticks: u32,
+}
+
+impl SessionAdaptiveController {
+    pub fn new(initial_tier: AdaptiveTier) -> Self {
+        Self {
+            tier: initial_tier,
+            max_tier_seen: initial_tier,
+            throughput_ema_bps: 0.0,
+            incoming_ema_bps: 0.0,
+            outgoing_ema_bps: 0.0,
+            tier1_hold_ticks: 0,
+            tier2_hold_ticks: 0,
+            quiet_ticks: 0,
+            hard_cooldown_ticks: 0,
+        }
+    }
+
+    pub fn max_tier_seen(&self) -> AdaptiveTier {
+        self.max_tier_seen
+    }
+
+    pub fn observe(&mut self, sample: RelaySignalSample, tick_secs: f64) -> Option<TierTransition> {
+        if tick_secs <= f64::EPSILON {
+            return None;
+        }
+
+        if self.hard_cooldown_ticks > 0 {
+            self.hard_cooldown_ticks -= 1;
+        }
+
+        let c2s_bps = (sample.c2s_bytes as f64 * 8.0) / tick_secs;
+        let incoming_bps = (sample.s2c_requested_bytes as f64 * 8.0) / tick_secs;
+        let outgoing_bps = (sample.s2c_written_bytes as f64 * 8.0) / tick_secs;
+        let throughput = c2s_bps.max(outgoing_bps);
+
+        self.throughput_ema_bps = ema(self.throughput_ema_bps, throughput);
+        self.incoming_ema_bps = ema(self.incoming_ema_bps, incoming_bps);
+        self.outgoing_ema_bps = ema(self.outgoing_ema_bps, outgoing_bps);
+
+        let tier1_now = self.throughput_ema_bps >= THROUGHPUT_UP_BPS;
+        if tier1_now {
+            self.tier1_hold_ticks = self.tier1_hold_ticks.saturating_add(1);
+        } else {
+            self.tier1_hold_ticks = 0;
+        }
+
+        let ratio = if self.outgoing_ema_bps <= f64::EPSILON {
+            0.0
+        } else {
+            self.incoming_ema_bps / self.outgoing_ema_bps
+        };
+        let tier2_now = ratio >= RATIO_CONFIRM_THRESHOLD;
+        if tier2_now {
+            self.tier2_hold_ticks = self.tier2_hold_ticks.saturating_add(1);
+        } else {
+            self.tier2_hold_ticks = 0;
+        }
+
+        let partial_ratio = if sample.s2c_write_ops == 0 {
+            0.0
+        } else {
+            sample.s2c_partial_writes as f64 / sample.s2c_write_ops as f64
+        };
+        let hard_now = sample.s2c_consecutive_pending_writes >= HARD_PENDING_THRESHOLD
+            || partial_ratio >= HARD_PARTIAL_RATIO_THRESHOLD;
+
+        if hard_now && self.hard_cooldown_ticks == 0 {
+            return self.promote(TierTransitionReason::HardPressure, HARD_COOLDOWN_TICKS);
+        }
+
+        if self.tier1_hold_ticks >= TIER1_HOLD_TICKS && self.tier2_hold_ticks >= TIER2_HOLD_TICKS {
+            return self.promote(TierTransitionReason::SoftConfirmed, 0);
+        }
+
+        let demote_candidate = self.throughput_ema_bps < THROUGHPUT_DOWN_BPS && !tier2_now && !hard_now;
+        if demote_candidate {
+            self.quiet_ticks = self.quiet_ticks.saturating_add(1);
+            if self.quiet_ticks >= QUIET_DEMOTE_TICKS {
+                self.quiet_ticks = 0;
+                return self.demote(TierTransitionReason::QuietDemotion);
+            }
+        } else {
+            self.quiet_ticks = 0;
+        }
+
+        None
+    }
+
+    fn promote(
+        &mut self,
+        reason: TierTransitionReason,
+        hard_cooldown_ticks: u32,
+    ) -> Option<TierTransition> {
+        let from = self.tier;
+        let to = from.promote();
+        if from == to {
+            return None;
+        }
+        self.tier = to;
+        self.max_tier_seen = max(self.max_tier_seen, to);
+        self.hard_cooldown_ticks = hard_cooldown_ticks;
+        self.tier1_hold_ticks = 0;
+        self.tier2_hold_ticks = 0;
+        self.quiet_ticks = 0;
+        Some(TierTransition { from, to, reason })
+    }
+
+    fn demote(&mut self, reason: TierTransitionReason) -> Option<TierTransition> {
+        let from = self.tier;
+        let to = from.demote();
+        if from == to {
+            return None;
+        }
+        self.tier = to;
+        self.tier1_hold_ticks = 0;
+        self.tier2_hold_ticks = 0;
+        Some(TierTransition { from, to, reason })
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+struct UserAdaptiveProfile {
+    tier: AdaptiveTier,
+    seen_at: Instant,
+}
+
+fn profiles() -> &'static DashMap<String, UserAdaptiveProfile> {
+    static USER_PROFILES: OnceLock<DashMap<String, UserAdaptiveProfile>> = OnceLock::new();
+    USER_PROFILES.get_or_init(DashMap::new)
+}
+
+pub fn seed_tier_for_user(user: &str) -> AdaptiveTier {
+    let now = Instant::now();
+    if let Some(entry) = profiles().get(user) {
+        let value = entry.value();
+        if now.duration_since(value.seen_at) <= PROFILE_TTL {
+            return value.tier;
+        }
+    }
+    AdaptiveTier::Base
+}
+
+pub fn record_user_tier(user: &str, tier: AdaptiveTier) {
+    let now = Instant::now();
+    if let Some(mut entry) = profiles().get_mut(user) {
+        let existing = *entry;
+        let effective = if now.duration_since(existing.seen_at) > PROFILE_TTL {
+            tier
+        } else {
+            max(existing.tier, tier)
+        };
+        *entry = UserAdaptiveProfile {
+            tier: effective,
+            seen_at: now,
+        };
+        return;
+    }
+    profiles().insert(
+        user.to_string(),
+        UserAdaptiveProfile { tier, seen_at: now },
+    );
+}
+
+pub fn direct_copy_buffers_for_tier(
+    tier: AdaptiveTier,
+    base_c2s: usize,
+    base_s2c: usize,
+) -> (usize, usize) {
+    let (num, den) = tier.ratio();
+    (
+        scale(base_c2s, num, den, DIRECT_C2S_CAP_BYTES),
+        scale(base_s2c, num, den, DIRECT_S2C_CAP_BYTES),
+    )
+}
+
+pub fn me_flush_policy_for_tier(
+    tier: AdaptiveTier,
+    base_frames: usize,
+    base_bytes: usize,
+    base_delay: Duration,
+) -> (usize, usize, Duration) {
+    let (num, den) = tier.ratio();
+    let frames = scale(base_frames, num, den, ME_FRAMES_CAP).max(1);
+    let bytes = scale(base_bytes, num, den, ME_BYTES_CAP).max(4096);
+    let delay_us = base_delay.as_micros() as u64;
+    let adjusted_delay_us = match tier {
+        AdaptiveTier::Base => delay_us,
+        AdaptiveTier::Tier1 => (delay_us.saturating_mul(7)).saturating_div(10),
+        AdaptiveTier::Tier2 => delay_us.saturating_div(2),
+        AdaptiveTier::Tier3 => (delay_us.saturating_mul(3)).saturating_div(10),
+    }
+    .max(ME_DELAY_MIN_US)
+    .min(delay_us.max(ME_DELAY_MIN_US));
+    (frames, bytes, Duration::from_micros(adjusted_delay_us))
+}
+
+fn ema(prev: f64, value: f64) -> f64 {
+    if prev <= f64::EPSILON {
+        value
+    } else {
+        (prev * (1.0 - EMA_ALPHA)) + (value * EMA_ALPHA)
+    }
+}
+
+fn scale(base: usize, numerator: usize, denominator: usize, cap: usize) -> usize {
+    let scaled = base
+        .saturating_mul(numerator)
+        .saturating_div(denominator.max(1));
+    scaled.min(cap).max(1)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample(
+        c2s_bytes: u64,
+        s2c_requested_bytes: u64,
+        s2c_written_bytes: u64,
+        s2c_write_ops: u64,
+        s2c_partial_writes: u64,
+        s2c_consecutive_pending_writes: u32,
+    ) -> RelaySignalSample {
+        RelaySignalSample {
+            c2s_bytes,
+            s2c_requested_bytes,
+            s2c_written_bytes,
+            s2c_write_ops,
+            s2c_partial_writes,
+            s2c_consecutive_pending_writes,
+        }
+    }
+
+    #[test]
+    fn test_soft_promotion_requires_tier1_and_tier2() {
+        let mut ctrl = SessionAdaptiveController::new(AdaptiveTier::Base);
+        let tick_secs = 0.25;
+        let mut promoted = None;
+        for _ in 0..8 {
+            promoted = ctrl.observe(
+                sample(
+                    300_000, // ~9.6 Mbps
+                    320_000, // incoming > outgoing to confirm tier2
+                    250_000,
+                    10,
+                    0,
+                    0,
+                ),
+                tick_secs,
+            );
+        }
+
+        let transition = promoted.expect("expected soft promotion");
+        assert_eq!(transition.from, AdaptiveTier::Base);
+        assert_eq!(transition.to, AdaptiveTier::Tier1);
+        assert_eq!(transition.reason, TierTransitionReason::SoftConfirmed);
+    }
+
+    #[test]
+    fn test_hard_promotion_on_pending_pressure() {
+        let mut ctrl = SessionAdaptiveController::new(AdaptiveTier::Base);
+        let transition = ctrl
+            .observe(
+                sample(10_000, 20_000, 10_000, 4, 1, 3),
+                0.25,
+            )
+            .expect("expected hard promotion");
+        assert_eq!(transition.reason, TierTransitionReason::HardPressure);
+        assert_eq!(transition.to, AdaptiveTier::Tier1);
+    }
+
+    #[test]
+    fn test_quiet_demotion_is_slow_and_stepwise() {
+        let mut ctrl = SessionAdaptiveController::new(AdaptiveTier::Tier2);
+        let mut demotion = None;
+        for _ in 0..QUIET_DEMOTE_TICKS {
+            demotion = ctrl.observe(sample(1, 1, 1, 1, 0, 0), 0.25);
+        }
+
+        let transition = demotion.expect("expected quiet demotion");
+        assert_eq!(transition.from, AdaptiveTier::Tier2);
+        assert_eq!(transition.to, AdaptiveTier::Tier1);
+        assert_eq!(transition.reason, TierTransitionReason::QuietDemotion);
+    }
+}

src/proxy/direct_relay.rs

@@ -0,0 +1,245 @@
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+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::{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::proxy::adaptive_buffers;
+use crate::proxy::session_eviction::SessionLease;
+use crate::stats::Stats;
+use crate::stream::{BufferPool, CryptoReader, CryptoWriter};
+use crate::transport::UpstreamManager;
+
+pub(crate) async fn handle_via_direct<R, W>(
+    client_reader: CryptoReader<R>,
+    client_writer: CryptoWriter<W>,
+    success: HandshakeSuccess,
+    upstream_manager: Arc<UpstreamManager>,
+    stats: Arc<Stats>,
+    config: Arc<ProxyConfig>,
+    buffer_pool: Arc<BufferPool>,
+    rng: Arc<SecureRandom>,
+    mut route_rx: watch::Receiver<RouteCutoverState>,
+    route_snapshot: RouteCutoverState,
+    session_id: u64,
+    session_lease: SessionLease,
+) -> Result<()>
+where
+    R: AsyncRead + Unpin + Send + 'static,
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let user = &success.user;
+    let dc_addr = get_dc_addr_static(success.dc_idx, &config)?;
+
+    debug!(
+        user = %user,
+        peer = %success.peer,
+        dc = success.dc_idx,
+        dc_addr = %dc_addr,
+        proto = ?success.proto_tag,
+        mode = "direct",
+        "Connecting to Telegram DC"
+    );
+
+    let tg_stream = upstream_manager
+        .connect(dc_addr, Some(success.dc_idx), user.strip_prefix("scope_").filter(|s| !s.is_empty()))
+        .await?;
+
+    debug!(peer = %success.peer, dc_addr = %dc_addr, "Connected, performing TG handshake");
+
+    let (tg_reader, tg_writer) =
+        do_tg_handshake_static(tg_stream, &success, &config, rng.as_ref()).await?;
+
+    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 seed_tier = adaptive_buffers::seed_tier_for_user(user);
+    let (c2s_copy_buf, s2c_copy_buf) = adaptive_buffers::direct_copy_buffers_for_tier(
+        seed_tier,
+        config.general.direct_relay_copy_buf_c2s_bytes,
+        config.general.direct_relay_copy_buf_s2c_bytes,
+    );
+
+    let relay_result = relay_bidirectional(
+        client_reader,
+        client_writer,
+        tg_reader,
+        tg_writer,
+        c2s_copy_buf,
+        s2c_copy_buf,
+        user,
+        success.dc_idx,
+        Arc::clone(&stats),
+        buffer_pool,
+        session_lease,
+        seed_tier,
+    );
+    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_current_connections_direct();
+    stats.decrement_user_curr_connects(user);
+
+    match &relay_result {
+        Ok(()) => debug!(user = %user, "Direct relay completed"),
+        Err(e) => debug!(user = %user, error = %e, "Direct relay ended with error"),
+    }
+
+    relay_result
+}
+
+fn get_dc_addr_static(dc_idx: i16, config: &ProxyConfig) -> Result<SocketAddr> {
+    let prefer_v6 = config.network.prefer == 6 && config.network.ipv6.unwrap_or(true);
+    let datacenters = if prefer_v6 {
+        &*TG_DATACENTERS_V6
+    } else {
+        &*TG_DATACENTERS_V4
+    };
+
+    let num_dcs = datacenters.len();
+
+    let dc_key = dc_idx.to_string();
+    if let Some(addrs) = config.dc_overrides.get(&dc_key) {
+        let mut parsed = Vec::new();
+        for addr_str in addrs {
+            match addr_str.parse::<SocketAddr>() {
+                Ok(addr) => parsed.push(addr),
+                Err(_) => warn!(dc_idx = dc_idx, addr_str = %addr_str, "Invalid DC override address in config, ignoring"),
+            }
+        }
+
+        if let Some(addr) = parsed
+            .iter()
+            .find(|a| a.is_ipv6() == prefer_v6)
+            .or_else(|| parsed.first())
+            .copied()
+        {
+            debug!(dc_idx = dc_idx, addr = %addr, count = parsed.len(), "Using DC override from config");
+            return Ok(addr);
+        }
+    }
+
+    let abs_dc = dc_idx.unsigned_abs() as usize;
+    if abs_dc >= 1 && abs_dc <= num_dcs {
+        return Ok(SocketAddr::new(datacenters[abs_dc - 1], TG_DATACENTER_PORT));
+    }
+
+    // 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 config.general.unknown_dc_file_log_enabled
+            && let Some(path) = &config.general.unknown_dc_log_path
+            && let Ok(handle) = tokio::runtime::Handle::try_current()
+        {
+            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}");
+                }
+            });
+        }
+    }
+
+    let default_dc = config.default_dc.unwrap_or(2) as usize;
+    let fallback_idx = if default_dc >= 1 && default_dc <= num_dcs {
+        default_dc - 1
+    } else {
+        1
+    };
+
+    info!(
+        original_dc = dc_idx,
+        fallback_dc = (fallback_idx + 1) as u16,
+        fallback_addr = %datacenters[fallback_idx],
+        "Special DC ---> default_cluster"
+    );
+
+    Ok(SocketAddr::new(
+        datacenters[fallback_idx],
+        TG_DATACENTER_PORT,
+    ))
+}
+
+async fn do_tg_handshake_static(
+    mut stream: TcpStream,
+    success: &HandshakeSuccess,
+    config: &ProxyConfig,
+    rng: &SecureRandom,
+) -> Result<(
+    CryptoReader<tokio::net::tcp::OwnedReadHalf>,
+    CryptoWriter<tokio::net::tcp::OwnedWriteHalf>,
+)> {
+    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,
+        config.general.fast_mode,
+    );
+
+    let (encrypted_nonce, tg_encryptor, tg_decryptor) = encrypt_tg_nonce_with_ciphers(&nonce);
+
+    debug!(
+        peer = %success.peer,
+        nonce_head = %hex::encode(&nonce[..16]),
+        "Sending nonce to Telegram"
+    );
+
+    stream.write_all(&encrypted_nonce).await?;
+    stream.flush().await?;
+
+    let (read_half, write_half) = stream.into_split();
+
+    let max_pending = config.general.crypto_pending_buffer;
+    Ok((
+        CryptoReader::new(read_half, tg_decryptor),
+        CryptoWriter::new(write_half, tg_encryptor, max_pending),
+    ))
+}

src/proxy/handshake.rs

@@ -1,19 +1,53 @@
-//! MTProto Handshake Magics
+//! MTProto Handshake
+
+#![allow(dead_code)]
 
 use std::net::SocketAddr;
+use std::sync::Arc;
+use std::time::Duration;
 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};
-use crate::crypto::random::SECURE_RANDOM;
+use crate::crypto::{sha256, AesCtr, SecureRandom};
+use rand::Rng;
 use crate::protocol::constants::*;
 use crate::protocol::tls;
 use crate::stream::{FakeTlsReader, FakeTlsWriter, CryptoReader, CryptoWriter};
 use crate::error::{ProxyError, HandshakeResult};
 use crate::stats::ReplayChecker;
 use crate::config::ProxyConfig;
+use crate::tls_front::{TlsFrontCache, emulator};
+
+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 Ok(bytes) = hex::decode(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 Ok(bytes) = hex::decode(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)]
 pub struct HandshakeSuccess {
     /// Authenticated user name
@@ -34,6 +68,15 @@ pub struct HandshakeSuccess {
     pub is_tls: bool,
 }
 
+impl Drop for HandshakeSuccess {
+    fn drop(&mut self) {
+        self.dec_key.zeroize();
+        self.dec_iv.zeroize();
+        self.enc_key.zeroize();
+        self.enc_iv.zeroize();
+    }
+}
+
 /// Handle fake TLS handshake
 pub async fn handle_tls_handshake<R, W>(
     handshake: &[u8],
@@ -42,84 +85,149 @@ pub async fn handle_tls_handshake<R, W>(
     peer: SocketAddr,
     config: &ProxyConfig,
     replay_checker: &ReplayChecker,
-) -> HandshakeResult<(FakeTlsReader<R>, FakeTlsWriter<W>, String)>
+    rng: &SecureRandom,
+    tls_cache: Option<Arc<TlsFrontCache>>,
+) -> HandshakeResult<(FakeTlsReader<R>, FakeTlsWriter<W>, String), R, W>
 where
     R: AsyncRead + Unpin,
     W: AsyncWrite + Unpin,
 {
     debug!(peer = %peer, handshake_len = handshake.len(), "Processing TLS handshake");
-    
-    // Check minimum length
+
     if handshake.len() < tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN + 1 {
         debug!(peer = %peer, "TLS handshake too short");
-        return HandshakeResult::BadClient;
+        return HandshakeResult::BadClient { reader, writer };
     }
-    
-    // Extract digest for replay check
+
     let digest = &handshake[tls::TLS_DIGEST_POS..tls::TLS_DIGEST_POS + tls::TLS_DIGEST_LEN];
     let digest_half = &digest[..tls::TLS_DIGEST_HALF_LEN];
-    
-    // Check for replay
-    if replay_checker.check_tls_digest(digest_half) {
-        warn!(peer = %peer, "TLS replay attack detected");
-        return HandshakeResult::BadClient;
+
+    if replay_checker.check_and_add_tls_digest(digest_half) {
+        warn!(peer = %peer, "TLS replay attack detected (duplicate digest)");
+        return HandshakeResult::BadClient { reader, writer };
     }
-    
-    // Build secrets list
-    let secrets: Vec<(String, Vec<u8>)> = config.users.iter()
-        .filter_map(|(name, hex)| {
-            hex::decode(hex).ok().map(|bytes| (name.clone(), bytes))
-        })
-        .collect();
-    
-    debug!(peer = %peer, num_users = secrets.len(), "Validating TLS handshake against users");
-    
-    // Validate handshake
+
+    let secrets = decode_user_secrets(config, None);
+
     let validation = match tls::validate_tls_handshake(
         handshake,
         &secrets,
-        config.ignore_time_skew,
+        config.access.ignore_time_skew,
     ) {
         Some(v) => v,
         None => {
-            debug!(peer = %peer, "TLS handshake validation failed - no matching user");
-            return HandshakeResult::BadClient;
+            debug!(
+                peer = %peer, 
+                ignore_time_skew = config.access.ignore_time_skew,
+                "TLS handshake validation failed - no matching user or time skew"
+            );
+            return HandshakeResult::BadClient { reader, writer };
         }
     };
-    
-    // Get secret for response
+
     let secret = match secrets.iter().find(|(name, _)| *name == validation.user) {
         Some((_, s)) => s,
-        None => return HandshakeResult::BadClient,
+        None => return HandshakeResult::BadClient { reader, writer },
     };
-    
-    // Build and send response
-    let response = tls::build_server_hello(
-        secret,
-        &validation.digest,
-        &validation.session_id,
-        config.fake_cert_len,
-    );
-    
+
+    let cached = if config.censorship.tls_emulation {
+        if let Some(cache) = tls_cache.as_ref() {
+            let selected_domain = if let Some(sni) = tls::extract_sni_from_client_hello(handshake) {
+                if cache.contains_domain(&sni).await {
+                    sni
+                } else {
+                    config.censorship.tls_domain.clone()
+                }
+            } else {
+                config.censorship.tls_domain.clone()
+            };
+            let cached_entry = cache.get(&selected_domain).await;
+            let use_full_cert_payload = cache
+                .take_full_cert_budget_for_ip(
+                    peer.ip(),
+                    Duration::from_secs(config.censorship.tls_full_cert_ttl_secs),
+                )
+                .await;
+            Some((cached_entry, use_full_cert_payload))
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    let alpn_list = if config.censorship.alpn_enforce {
+        tls::extract_alpn_from_client_hello(handshake)
+    } else {
+        Vec::new()
+    };
+    let selected_alpn = if config.censorship.alpn_enforce {
+        if alpn_list.iter().any(|p| p == b"h2") {
+            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 {
+            None
+        }
+    } else {
+        None
+    };
+
+    let response = if let Some((cached_entry, use_full_cert_payload)) = cached {
+        emulator::build_emulated_server_hello(
+            secret,
+            &validation.digest,
+            &validation.session_id,
+            &cached_entry,
+            use_full_cert_payload,
+            rng,
+            selected_alpn.clone(),
+            config.censorship.tls_new_session_tickets,
+        )
+    } else {
+        tls::build_server_hello(
+            secret,
+            &validation.digest,
+            &validation.session_id,
+            config.censorship.fake_cert_len,
+            rng,
+            selected_alpn.clone(),
+            config.censorship.tls_new_session_tickets,
+        )
+    };
+
+    // Optional anti-fingerprint delay before sending ServerHello.
+    if config.censorship.server_hello_delay_max_ms > 0 {
+        let min = config.censorship.server_hello_delay_min_ms;
+        let max = config.censorship.server_hello_delay_max_ms.max(min);
+        let delay_ms = if max == min {
+            max
+        } else {
+            rand::rng().random_range(min..=max)
+        };
+        if delay_ms > 0 {
+            tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
+        }
+    }
+
     debug!(peer = %peer, response_len = response.len(), "Sending TLS ServerHello");
-    
+
     if let Err(e) = writer.write_all(&response).await {
+        warn!(peer = %peer, error = %e, "Failed to write TLS ServerHello");
         return HandshakeResult::Error(ProxyError::Io(e));
     }
-    
+
     if let Err(e) = writer.flush().await {
+        warn!(peer = %peer, error = %e, "Failed to flush TLS ServerHello");
         return HandshakeResult::Error(ProxyError::Io(e));
     }
-    
-    // Record for replay protection
-    replay_checker.add_tls_digest(digest_half);
-    
-    info!(
+
+    debug!(
         peer = %peer,
         user = %validation.user,
         "TLS handshake successful"
     );
-    
+
     HandshakeResult::Success((
         FakeTlsReader::new(reader),
         FakeTlsWriter::new(writer),
@@ -136,111 +244,81 @@ pub async fn handle_mtproto_handshake<R, W>(
     config: &ProxyConfig,
     replay_checker: &ReplayChecker,
     is_tls: bool,
-) -> HandshakeResult<(CryptoReader<R>, CryptoWriter<W>, HandshakeSuccess)>
+    preferred_user: Option<&str>,
+) -> HandshakeResult<(CryptoReader<R>, CryptoWriter<W>, HandshakeSuccess), R, W>
 where
     R: AsyncRead + Unpin + Send,
     W: AsyncWrite + Unpin + Send,
 {
     trace!(peer = %peer, handshake = ?hex::encode(handshake), "MTProto handshake bytes");
-    
-    // Extract prekey and IV
+
     let dec_prekey_iv = &handshake[SKIP_LEN..SKIP_LEN + PREKEY_LEN + IV_LEN];
-    
-    debug!(
-        peer = %peer,
-        dec_prekey_iv = %hex::encode(dec_prekey_iv),
-        "Extracted prekey+IV from handshake"
-    );
-    
-    // Check for replay
-    if replay_checker.check_handshake(dec_prekey_iv) {
+
+    if replay_checker.check_and_add_handshake(dec_prekey_iv) {
         warn!(peer = %peer, "MTProto replay attack detected");
-        return HandshakeResult::BadClient;
+        return HandshakeResult::BadClient { reader, writer };
     }
-    
-    // Reversed for encryption direction
+
     let enc_prekey_iv: Vec<u8> = dec_prekey_iv.iter().rev().copied().collect();
-    
-    // Try each user's secret
-    for (user, secret_hex) in &config.users {
-        let secret = match hex::decode(secret_hex) {
-            Ok(s) => s,
-            Err(_) => continue,
-        };
-        
-        // Derive decryption key
+
+    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..];
-        
+
         let mut dec_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
         dec_key_input.extend_from_slice(dec_prekey);
         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());
-        
-        // Decrypt handshake to check protocol tag
+
         let mut decryptor = AesCtr::new(&dec_key, dec_iv);
         let decrypted = decryptor.decrypt(handshake);
-        
-        trace!(
-            peer = %peer,
-            user = %user,
-            decrypted_tail = %hex::encode(&decrypted[PROTO_TAG_POS..]),
-            "Decrypted handshake tail"
-        );
-        
-        // Check protocol tag
+
         let tag_bytes: [u8; 4] = decrypted[PROTO_TAG_POS..PROTO_TAG_POS + 4]
             .try_into()
             .unwrap();
-        
+
         let proto_tag = match ProtoTag::from_bytes(tag_bytes) {
             Some(tag) => tag,
-            None => {
-                trace!(peer = %peer, user = %user, tag = %hex::encode(tag_bytes), "Invalid proto tag");
-                continue;
-            }
+            None => continue,
         };
-        
-        debug!(peer = %peer, user = %user, proto = ?proto_tag, "Found valid proto tag");
-        
-        // Check if mode is enabled
+
         let mode_ok = match proto_tag {
             ProtoTag::Secure => {
-                if is_tls { config.modes.tls } else { config.modes.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.modes.classic,
+            ProtoTag::Intermediate | ProtoTag::Abridged => config.general.modes.classic,
         };
-        
+
         if !mode_ok {
             debug!(peer = %peer, user = %user, proto = ?proto_tag, "Mode not enabled");
             continue;
         }
-        
-        // Extract DC index
+
         let dc_idx = i16::from_le_bytes(
             decrypted[DC_IDX_POS..DC_IDX_POS + 2].try_into().unwrap()
         );
-        
-        // Derive encryption key
+
         let enc_prekey = &enc_prekey_iv[..PREKEY_LEN];
         let enc_iv_bytes = &enc_prekey_iv[PREKEY_LEN..];
-        
+
         let mut enc_key_input = Vec::with_capacity(PREKEY_LEN + secret.len());
         enc_key_input.extend_from_slice(enc_prekey);
         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());
-        
-        // Record for replay protection
-        replay_checker.add_handshake(dec_prekey_iv);
-        
-        // Create new cipher instances
-        let decryptor = AesCtr::new(&dec_key, dec_iv);
+
         let encryptor = AesCtr::new(&enc_key, enc_iv);
-        
+
         let success = HandshakeSuccess {
             user: user.clone(),
             dc_idx,
@@ -252,8 +330,8 @@ where
             peer,
             is_tls,
         };
-        
-        info!(
+
+        debug!(
             peer = %peer,
             user = %user,
             dc = dc_idx,
@@ -261,151 +339,170 @@ where
             tls = is_tls,
             "MTProto handshake successful"
         );
-        
+
+        let max_pending = config.general.crypto_pending_buffer;
         return HandshakeResult::Success((
             CryptoReader::new(reader, decryptor),
-            CryptoWriter::new(writer, encryptor),
+            CryptoWriter::new(writer, encryptor, max_pending),
             success,
         ));
     }
-    
+
     debug!(peer = %peer, "MTProto handshake: no matching user found");
-    HandshakeResult::BadClient
+    HandshakeResult::BadClient { reader, writer }
 }
 
 /// Generate nonce for Telegram connection
-/// 
-/// In FAST MODE: we use the same keys for TG as for client, but reversed.
-/// This means: client's enc_key becomes TG's dec_key and vice versa.
 pub fn generate_tg_nonce(
     proto_tag: ProtoTag, 
-    client_dec_key: &[u8; 32],
-    client_dec_iv: u128,
+    dc_idx: i16,
+    _client_dec_key: &[u8; 32],
+    _client_dec_iv: u128,
+    client_enc_key: &[u8; 32],
+    client_enc_iv: u128,
+    rng: &SecureRandom,
     fast_mode: bool,
 ) -> ([u8; HANDSHAKE_LEN], [u8; 32], u128, [u8; 32], u128) {
     loop {
-        let bytes = SECURE_RANDOM.bytes(HANDSHAKE_LEN);
+        let bytes = rng.bytes(HANDSHAKE_LEN);
         let mut nonce: [u8; HANDSHAKE_LEN] = bytes.try_into().unwrap();
-        
-        // Check reserved patterns
-        if RESERVED_NONCE_FIRST_BYTES.contains(&nonce[0]) {
-            continue;
-        }
-        
+
+        if RESERVED_NONCE_FIRST_BYTES.contains(&nonce[0]) { continue; }
+
         let first_four: [u8; 4] = nonce[..4].try_into().unwrap();
-        if RESERVED_NONCE_BEGINNINGS.contains(&first_four) {
-            continue;
-        }
-        
+        if RESERVED_NONCE_BEGINNINGS.contains(&first_four) { continue; }
+
         let continue_four: [u8; 4] = nonce[4..8].try_into().unwrap();
-        if RESERVED_NONCE_CONTINUES.contains(&continue_four) {
-            continue;
-        }
-        
-        // Set protocol tag
+        if RESERVED_NONCE_CONTINUES.contains(&continue_four) { continue; }
+
         nonce[PROTO_TAG_POS..PROTO_TAG_POS + 4].copy_from_slice(&proto_tag.to_bytes());
-        
-        // Fast mode: copy client's dec_key+iv (this becomes TG's enc direction)
-        // In fast mode, we make TG use the same keys as client but swapped:
-        // - What we decrypt FROM TG = what we encrypt TO client (so no re-encryption needed)
-        // - What we encrypt TO TG = what we decrypt FROM client
+        // CRITICAL: write dc_idx so upstream DC knows where to route
+        nonce[DC_IDX_POS..DC_IDX_POS + 2].copy_from_slice(&dc_idx.to_le_bytes());
+
         if fast_mode {
-            // Put client's dec_key + dec_iv into nonce[8:56]
-            // This will be used by TG for encryption TO us
-            nonce[SKIP_LEN..SKIP_LEN + KEY_LEN].copy_from_slice(client_dec_key);
-            nonce[SKIP_LEN + KEY_LEN..SKIP_LEN + KEY_LEN + IV_LEN]
-                .copy_from_slice(&client_dec_iv.to_be_bytes());
+            let mut key_iv = Vec::with_capacity(KEY_LEN + IV_LEN);
+            key_iv.extend_from_slice(client_enc_key);
+            key_iv.extend_from_slice(&client_enc_iv.to_be_bytes());
+            key_iv.reverse(); // Python/C behavior: reversed enc_key+enc_iv in nonce
+            nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN].copy_from_slice(&key_iv);
         }
-        
-        // Now compute what keys WE will use for TG connection
-        // enc_key_iv = nonce[8:56] (for encrypting TO TG)
-        // dec_key_iv = nonce[8:56] reversed (for decrypting FROM TG)
+
         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 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());
-        
-        debug!(
-            fast_mode = fast_mode,
-            tg_enc_key = %hex::encode(&tg_enc_key[..8]),
-            tg_dec_key = %hex::encode(&tg_dec_key[..8]),
-            "Generated TG nonce"
-        );
-        
+
         return (nonce, tg_enc_key, tg_enc_iv, tg_dec_key, tg_dec_iv);
     }
 }
 
-/// Encrypt nonce for sending to Telegram
-/// 
-/// Only the part from PROTO_TAG_POS onwards is encrypted.
-/// The encryption key is derived from enc_key_iv in the nonce itself.
-pub fn encrypt_tg_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> Vec<u8> {
-    // enc_key_iv is at nonce[8:56]
+/// Encrypt nonce for sending to Telegram and return cipher objects with correct counter state
+pub fn encrypt_tg_nonce_with_ciphers(nonce: &[u8; HANDSHAKE_LEN]) -> (Vec<u8>, AesCtr, AesCtr) {
     let enc_key_iv = &nonce[SKIP_LEN..SKIP_LEN + KEY_LEN + IV_LEN];
-    
-    // Key for encrypting is just the first 32 bytes of enc_key_iv
-    let key: [u8; 32] = enc_key_iv[..KEY_LEN].try_into().unwrap();
-    let iv = u128::from_be_bytes(enc_key_iv[KEY_LEN..].try_into().unwrap());
-    
-    let mut encryptor = AesCtr::new(&key, iv);
-    
-    // Encrypt the entire nonce first, then take only the encrypted tail
-    let encrypted_full = encryptor.encrypt(nonce);
-    
-    // Result: unencrypted head + encrypted tail
+    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 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 encryptor = AesCtr::new(&enc_key, enc_iv);
+    let encrypted_full = encryptor.encrypt(nonce);  // counter: 0 → 4
+
     let mut result = nonce[..PROTO_TAG_POS].to_vec();
     result.extend_from_slice(&encrypted_full[PROTO_TAG_POS..]);
-    
-    trace!(
-        original = %hex::encode(&nonce[PROTO_TAG_POS..]),
-        encrypted = %hex::encode(&result[PROTO_TAG_POS..]),
-        "Encrypted nonce tail"
-    );
-    
-    result
+
+    let decryptor = AesCtr::new(&dec_key, dec_iv);
+
+    (result, encryptor, decryptor)
+}
+
+/// Encrypt nonce for sending to Telegram (legacy function for compatibility)
+pub fn encrypt_tg_nonce(nonce: &[u8; HANDSHAKE_LEN]) -> Vec<u8> {
+    let (encrypted, _, _) = encrypt_tg_nonce_with_ciphers(nonce);
+    encrypted
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    
+
     #[test]
     fn test_generate_tg_nonce() {
         let client_dec_key = [0x42u8; 32];
         let client_dec_iv = 12345u128;
-        
-        let (nonce, tg_enc_key, tg_enc_iv, tg_dec_key, tg_dec_iv) = 
-            generate_tg_nonce(ProtoTag::Secure, &client_dec_key, client_dec_iv, false);
-        
-        // Check length
+        let client_enc_key = [0x24u8; 32];
+        let client_enc_iv = 54321u128;
+
+        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);
-        
-        // Check proto tag is set
+
         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, &client_dec_key, client_dec_iv, false);
-        
+            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);
-        
-        // First PROTO_TAG_POS bytes should be unchanged
         assert_eq!(&encrypted[..PROTO_TAG_POS], &nonce[..PROTO_TAG_POS]);
-        
-        // Rest should be different (encrypted)
         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
+    }
+}

src/proxy/masking.rs

@@ -1,72 +1,214 @@
 //! Masking - forward unrecognized traffic to mask host
 
+use std::str;
+use std::net::SocketAddr;
 use std::time::Duration;
 use tokio::net::TcpStream;
-use tokio::io::{AsyncReadExt, AsyncWriteExt};
+#[cfg(unix)]
+use tokio::net::UnixStream;
+use tokio::io::{AsyncRead, AsyncWrite, AsyncReadExt, AsyncWriteExt};
 use tokio::time::timeout;
 use tracing::debug;
 use crate::config::ProxyConfig;
-use crate::transport::set_linger_zero;
+use crate::network::dns_overrides::resolve_socket_addr;
+use crate::stats::beobachten::BeobachtenStore;
+use crate::transport::proxy_protocol::{ProxyProtocolV1Builder, ProxyProtocolV2Builder};
 
 const MASK_TIMEOUT: Duration = Duration::from_secs(5);
+/// Maximum duration for the entire masking relay.
+/// Limits resource consumption from slow-loris attacks and port scanners.
+const MASK_RELAY_TIMEOUT: Duration = Duration::from_secs(60);
 const MASK_BUFFER_SIZE: usize = 8192;
 
+/// Detect client type based on initial data
+fn detect_client_type(data: &[u8]) -> &'static str {
+    // Check for HTTP request
+    if data.len() > 4
+        && (data.starts_with(b"GET ") || data.starts_with(b"POST") ||
+           data.starts_with(b"HEAD") || data.starts_with(b"PUT ") ||
+           data.starts_with(b"DELETE") || data.starts_with(b"OPTIONS"))
+    {
+        return "HTTP";
+    }
+
+    // Check for TLS ClientHello (0x16 = handshake, 0x03 0x01-0x03 = TLS version)
+    if data.len() > 3 && data[0] == 0x16 && data[1] == 0x03 {
+        return "TLS-scanner";
+    }
+
+    // Check for SSH
+    if data.starts_with(b"SSH-") {
+        return "SSH";
+    }
+
+    // Port scanner (very short data)
+    if data.len() < 10 {
+        return "port-scanner";
+    }
+
+    "unknown"
+}
+
 /// Handle a bad client by forwarding to mask host
-pub async fn handle_bad_client(
-    client: TcpStream,
+pub async fn handle_bad_client<R, W>(
+    reader: R,
+    writer: W,
     initial_data: &[u8],
+    peer: SocketAddr,
+    local_addr: SocketAddr,
     config: &ProxyConfig,
-) {
-    if !config.mask {
+    beobachten: &BeobachtenStore,
+)
+where
+    R: AsyncRead + Unpin + Send + 'static,
+    W: AsyncWrite + Unpin + Send + 'static,
+{
+    let client_type = detect_client_type(initial_data);
+    if config.general.beobachten {
+        let ttl = Duration::from_secs(config.general.beobachten_minutes.saturating_mul(60));
+        beobachten.record(client_type, peer.ip(), ttl);
+    }
+
+    if !config.censorship.mask {
         // Masking disabled, just consume data
-        consume_client_data(client).await;
+        consume_client_data(reader).await;
         return;
     }
-    
-    let mask_host = config.mask_host.as_deref()
-        .unwrap_or(&config.tls_domain);
-    let mask_port = config.mask_port;
-    
+
+    // Connect via Unix socket or TCP
+    #[cfg(unix)]
+    if let Some(ref sock_path) = config.censorship.mask_unix_sock {
+        debug!(
+            client_type = client_type,
+            sock = %sock_path,
+            data_len = initial_data.len(),
+            "Forwarding bad client to mask unix socket"
+        );
+
+        let connect_result = timeout(MASK_TIMEOUT, UnixStream::connect(sock_path)).await;
+        match connect_result {
+            Ok(Ok(stream)) => {
+                let (mask_read, mut mask_write) = stream.into_split();
+                let proxy_header: Option<Vec<u8>> = match config.censorship.mask_proxy_protocol {
+                    0 => None,
+                    version => {
+                        let header = match version {
+                            2 => ProxyProtocolV2Builder::new().with_addrs(peer, local_addr).build(),
+                            _ => match (peer, local_addr) {
+                                (SocketAddr::V4(src), SocketAddr::V4(dst)) =>
+                                    ProxyProtocolV1Builder::new().tcp4(src.into(), dst.into()).build(),
+                                (SocketAddr::V6(src), SocketAddr::V6(dst)) =>
+                                    ProxyProtocolV1Builder::new().tcp6(src.into(), dst.into()).build(),
+                                _ =>
+                                    ProxyProtocolV1Builder::new().build(),
+                            },
+                        };
+                        Some(header)
+                    }
+                };
+                if let Some(header) = proxy_header {
+                    if mask_write.write_all(&header).await.is_err() {
+                        return;
+                    }
+                }
+                if timeout(MASK_RELAY_TIMEOUT, relay_to_mask(reader, writer, mask_read, mask_write, initial_data)).await.is_err() {
+                    debug!("Mask relay timed out (unix socket)");
+                }
+            }
+            Ok(Err(e)) => {
+                debug!(error = %e, "Failed to connect to mask unix socket");
+                consume_client_data(reader).await;
+            }
+            Err(_) => {
+                debug!("Timeout connecting to mask unix socket");
+                consume_client_data(reader).await;
+            }
+        }
+        return;
+    }
+
+    let mask_host = config.censorship.mask_host.as_deref()
+        .unwrap_or(&config.censorship.tls_domain);
+    let mask_port = config.censorship.mask_port;
+
     debug!(
+        client_type = client_type,
         host = %mask_host,
         port = mask_port,
+        data_len = initial_data.len(),
         "Forwarding bad client to mask host"
     );
-    
-    // Connect to mask host
-    let mask_addr = format!("{}:{}", mask_host, mask_port);
-    let connect_result = timeout(
-        MASK_TIMEOUT,
-        TcpStream::connect(&mask_addr)
-    ).await;
-    
-    let mut mask_stream = match connect_result {
-        Ok(Ok(s)) => s,
+
+    // Apply runtime DNS override for mask target when configured.
+    let mask_addr = resolve_socket_addr(mask_host, mask_port)
+        .map(|addr| addr.to_string())
+        .unwrap_or_else(|| format!("{}:{}", mask_host, mask_port));
+    let connect_result = timeout(MASK_TIMEOUT, TcpStream::connect(&mask_addr)).await;
+    match connect_result {
+        Ok(Ok(stream)) => {
+            let proxy_header: Option<Vec<u8>> = match config.censorship.mask_proxy_protocol {
+                0 => None,
+                version => {
+                    let header = match version {
+                        2 => ProxyProtocolV2Builder::new().with_addrs(peer, local_addr).build(),
+                        _ => match (peer, local_addr) {
+                            (SocketAddr::V4(src), SocketAddr::V4(dst)) =>
+                                ProxyProtocolV1Builder::new().tcp4(src.into(), dst.into()).build(),
+                            (SocketAddr::V6(src), SocketAddr::V6(dst)) =>
+                                ProxyProtocolV1Builder::new().tcp6(src.into(), dst.into()).build(),
+                            _ =>
+                                ProxyProtocolV1Builder::new().build(),
+                        },
+                    };
+                    Some(header)
+                }
+            };
+
+            let (mask_read, mut mask_write) = stream.into_split();
+            if let Some(header) = proxy_header {
+                if mask_write.write_all(&header).await.is_err() {
+                    return;
+                }
+            }
+            if timeout(MASK_RELAY_TIMEOUT, relay_to_mask(reader, writer, mask_read, mask_write, initial_data)).await.is_err() {
+                debug!("Mask relay timed out");
+            }
+        }
         Ok(Err(e)) => {
             debug!(error = %e, "Failed to connect to mask host");
-            consume_client_data(client).await;
-            return;
+            consume_client_data(reader).await;
         }
         Err(_) => {
             debug!("Timeout connecting to mask host");
-            consume_client_data(client).await;
-            return;
+            consume_client_data(reader).await;
         }
-    };
-    
+    }
+}
+
+/// Relay traffic between client and mask backend
+async fn relay_to_mask<R, W, MR, MW>(
+    mut reader: R,
+    mut writer: W,
+    mut mask_read: MR,
+    mut mask_write: MW,
+    initial_data: &[u8],
+)
+where
+    R: AsyncRead + Unpin + Send + 'static,
+    W: AsyncWrite + Unpin + Send + 'static,
+    MR: AsyncRead + Unpin + Send + 'static,
+    MW: AsyncWrite + Unpin + Send + 'static,
+{
     // Send initial data to mask host
-    if mask_stream.write_all(initial_data).await.is_err() {
+    if mask_write.write_all(initial_data).await.is_err() {
         return;
     }
-    
+
     // Relay traffic
-    let (mut client_read, mut client_write) = client.into_split();
-    let (mut mask_read, mut mask_write) = mask_stream.into_split();
-    
     let c2m = tokio::spawn(async move {
         let mut buf = vec![0u8; MASK_BUFFER_SIZE];
         loop {
-            match client_read.read(&mut buf).await {
+            match reader.read(&mut buf).await {
                 Ok(0) | Err(_) => {
                     let _ = mask_write.shutdown().await;
                     break;
@@ -79,24 +221,24 @@ pub async fn handle_bad_client(
             }
         }
     });
-    
+
     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 _ = client_write.shutdown().await;
+                    let _ = writer.shutdown().await;
                     break;
                 }
                 Ok(n) => {
-                    if client_write.write_all(&buf[..n]).await.is_err() {
+                    if writer.write_all(&buf[..n]).await.is_err() {
                         break;
                     }
                 }
             }
         }
     });
-    
+
     // Wait for either to complete
     tokio::select! {
         _ = c2m => {}
@@ -105,11 +247,11 @@ pub async fn handle_bad_client(
 }
 
 /// Just consume all data from client without responding
-async fn consume_client_data(mut client: TcpStream) {
+async fn consume_client_data<R: AsyncRead + Unpin>(mut reader: R) {
     let mut buf = vec![0u8; MASK_BUFFER_SIZE];
-    while let Ok(n) = client.read(&mut buf).await {
+    while let Ok(n) = reader.read(&mut buf).await {
         if n == 0 {
             break;
         }
     }
-}
+}