API Defaults: merge pull request #388 from telemt/api-defaults

API Defaults

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "telemt"
-version = "3.3.14"
+version = "3.3.15"
 edition = "2024"
 
 [dependencies]

docs/API.md

@@ -85,6 +85,7 @@ Notes:
 | `GET` | `/v1/health` | none | `200` | `HealthData` |
 | `GET` | `/v1/system/info` | none | `200` | `SystemInfoData` |
 | `GET` | `/v1/runtime/gates` | none | `200` | `RuntimeGatesData` |
+| `GET` | `/v1/runtime/initialization` | none | `200` | `RuntimeInitializationData` |
 | `GET` | `/v1/limits/effective` | none | `200` | `EffectiveLimitsData` |
 | `GET` | `/v1/security/posture` | none | `200` | `SecurityPostureData` |
 | `GET` | `/v1/security/whitelist` | none | `200` | `SecurityWhitelistData` |
@@ -98,6 +99,7 @@ Notes:
 | `GET` | `/v1/runtime/me_quality` | none | `200` | `RuntimeMeQualityData` |
 | `GET` | `/v1/runtime/upstream_quality` | none | `200` | `RuntimeUpstreamQualityData` |
 | `GET` | `/v1/runtime/nat_stun` | none | `200` | `RuntimeNatStunData` |
+| `GET` | `/v1/runtime/me-selftest` | none | `200` | `RuntimeMeSelftestData` |
 | `GET` | `/v1/runtime/connections/summary` | none | `200` | `RuntimeEdgeConnectionsSummaryData` |
 | `GET` | `/v1/runtime/events/recent` | none | `200` | `RuntimeEdgeEventsData` |
 | `GET` | `/v1/stats/users` | none | `200` | `UserInfo[]` |
@@ -147,6 +149,12 @@ Notes:
 - `PATCH` updates only provided fields and does not support explicit clearing of optional fields.
 - `If-Match` supports both quoted and unquoted values; surrounding whitespace is trimmed.
 
+## Query Parameters
+
+| Endpoint | Query | Behavior |
+| --- | --- | --- |
+| `GET /v1/runtime/events/recent` | `limit=<usize>` | Optional. Invalid/missing value falls back to default `50`. Effective value is clamped to `[1, 1000]` and additionally bounded by ring-buffer capacity. |
+
 ## Request Contracts
 
 ### `CreateUserRequest`
@@ -219,6 +227,45 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `me_runtime_ready` | `bool` | Current ME runtime readiness status used for conditional gate decisions. |
 | `me2dc_fallback_enabled` | `bool` | Whether ME -> direct fallback is enabled. |
 | `use_middle_proxy` | `bool` | Current transport mode preference. |
+| `startup_status` | `string` | Startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
+| `startup_stage` | `string` | Current startup stage identifier. |
+| `startup_progress_pct` | `f64` | Startup progress percentage (`0..100`). |
+
+### `RuntimeInitializationData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `status` | `string` | Startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
+| `degraded` | `bool` | Whether runtime is currently in degraded mode. |
+| `current_stage` | `string` | Current startup stage identifier. |
+| `progress_pct` | `f64` | Overall startup progress percentage (`0..100`). |
+| `started_at_epoch_secs` | `u64` | Process start timestamp (Unix seconds). |
+| `ready_at_epoch_secs` | `u64?` | Timestamp when startup reached ready state; absent until ready. |
+| `total_elapsed_ms` | `u64` | Elapsed startup duration in milliseconds. |
+| `transport_mode` | `string` | Startup transport mode (`middle_proxy` or `direct`). |
+| `me` | `RuntimeInitializationMeData` | ME startup substate snapshot. |
+| `components` | `RuntimeInitializationComponentData[]` | Per-component startup timeline and status. |
+
+#### `RuntimeInitializationMeData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `status` | `string` | ME startup status (`pending`, `initializing`, `ready`, `failed`, `skipped`). |
+| `current_stage` | `string` | Current ME startup stage identifier. |
+| `progress_pct` | `f64` | ME startup progress percentage (`0..100`). |
+| `init_attempt` | `u32` | Current ME init attempt counter. |
+| `retry_limit` | `string` | Retry limit (`"unlimited"` or numeric string). |
+| `last_error` | `string?` | Last ME initialization error text when present. |
+
+#### `RuntimeInitializationComponentData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Startup component identifier. |
+| `title` | `string` | Human-readable component title. |
+| `status` | `string` | Component status (`pending`, `running`, `ready`, `failed`, `skipped`). |
+| `started_at_epoch_ms` | `u64?` | Component start timestamp in Unix milliseconds. |
+| `finished_at_epoch_ms` | `u64?` | Component finish timestamp in Unix milliseconds. |
+| `duration_ms` | `u64?` | Component duration in milliseconds. |
+| `attempts` | `u32` | Attempt counter for this component. |
+| `details` | `string?` | Optional short status details text. |
 
 ### `EffectiveLimitsData`
 | Field | Type | Description |
@@ -256,11 +303,22 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `floor_mode` | `string` | Effective floor mode (`static` or `adaptive`). |
 | `adaptive_floor_idle_secs` | `u64` | Adaptive floor idle threshold. |
 | `adaptive_floor_min_writers_single_endpoint` | `u8` | Adaptive floor minimum for single-endpoint DCs. |
+| `adaptive_floor_min_writers_multi_endpoint` | `u8` | Adaptive floor minimum for multi-endpoint DCs. |
 | `adaptive_floor_recover_grace_secs` | `u64` | Adaptive floor recovery grace period. |
+| `adaptive_floor_writers_per_core_total` | `u16` | Target total writers-per-core budget in adaptive mode. |
+| `adaptive_floor_cpu_cores_override` | `u16` | Manual CPU core override (`0` means auto-detect). |
+| `adaptive_floor_max_extra_writers_single_per_core` | `u16` | Extra per-core adaptive headroom for single-endpoint DCs. |
+| `adaptive_floor_max_extra_writers_multi_per_core` | `u16` | Extra per-core adaptive headroom for multi-endpoint DCs. |
+| `adaptive_floor_max_active_writers_per_core` | `u16` | Active writer cap per CPU core. |
+| `adaptive_floor_max_warm_writers_per_core` | `u16` | Warm writer cap per CPU core. |
+| `adaptive_floor_max_active_writers_global` | `u32` | Global active writer cap. |
+| `adaptive_floor_max_warm_writers_global` | `u32` | Global warm writer cap. |
 | `reconnect_max_concurrent_per_dc` | `u32` | Max concurrent reconnects per DC. |
 | `reconnect_backoff_base_ms` | `u64` | Reconnect base backoff. |
 | `reconnect_backoff_cap_ms` | `u64` | Reconnect backoff cap. |
 | `reconnect_fast_retry_count` | `u32` | Number of fast retries before standard backoff strategy. |
+| `writer_pick_mode` | `string` | Writer picker mode (`sorted_rr`, `p2c`). |
+| `writer_pick_sample_size` | `u8` | Candidate sample size for `p2c` picker mode. |
 | `me2dc_fallback` | `bool` | Effective ME -> direct fallback flag. |
 
 #### `EffectiveUserIpPolicyLimits`
@@ -290,16 +348,353 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `entries_total` | `usize` | Number of whitelist CIDR entries. |
 | `entries` | `string[]` | Whitelist CIDR entries as strings. |
 
-### Runtime Min Endpoints
-- `/v1/runtime/me_pool_state`: generations, hardswap state, writer contour/health counts, refill inflight snapshot.
-- `/v1/runtime/me_quality`: ME error/drift/reconnect counters and per-DC RTT coverage snapshot.
-- `/v1/runtime/upstream_quality`: upstream runtime policy, connect counters, health summary and per-upstream DC latency/IP preference.
-- `/v1/runtime/nat_stun`: NAT/STUN runtime flags, server lists, reflection cache state and backoff remaining.
+### `RuntimeMePoolStateData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when ME pool snapshot is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeMePoolStatePayload?` | Null when unavailable. |
 
-### Runtime Edge Endpoints
-- `/v1/runtime/connections/summary`: cached connection totals (`total/me/direct`), active users and top-N users by connections/traffic.
-- `/v1/runtime/events/recent?limit=N`: bounded control-plane ring-buffer events (`limit` clamped to `[1, 1000]`).
-- If `server.api.runtime_edge_enabled=false`, runtime edge endpoints return `enabled=false` with `reason=feature_disabled`.
+#### `RuntimeMePoolStatePayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `generations` | `RuntimeMePoolStateGenerationData` | Active/warm/pending/draining generation snapshot. |
+| `hardswap` | `RuntimeMePoolStateHardswapData` | Hardswap state flags. |
+| `writers` | `RuntimeMePoolStateWriterData` | Writer total/contour/health counters. |
+| `refill` | `RuntimeMePoolStateRefillData` | In-flight refill counters by DC/family. |
+
+#### `RuntimeMePoolStateGenerationData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `active_generation` | `u64` | Active pool generation id. |
+| `warm_generation` | `u64` | Warm pool generation id. |
+| `pending_hardswap_generation` | `u64` | Pending hardswap generation id (`0` when none). |
+| `pending_hardswap_age_secs` | `u64?` | Age of pending hardswap generation in seconds. |
+| `draining_generations` | `u64[]` | Distinct generation ids currently draining. |
+
+#### `RuntimeMePoolStateHardswapData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Hardswap feature toggle. |
+| `pending` | `bool` | `true` when pending generation is non-zero. |
+
+#### `RuntimeMePoolStateWriterData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `total` | `usize` | Total writer rows in snapshot. |
+| `alive_non_draining` | `usize` | Alive writers excluding draining ones. |
+| `draining` | `usize` | Writers marked draining. |
+| `degraded` | `usize` | Non-draining degraded writers. |
+| `contour` | `RuntimeMePoolStateWriterContourData` | Counts by contour state. |
+| `health` | `RuntimeMePoolStateWriterHealthData` | Counts by health bucket. |
+
+#### `RuntimeMePoolStateWriterContourData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `warm` | `usize` | Writers in warm contour. |
+| `active` | `usize` | Writers in active contour. |
+| `draining` | `usize` | Writers in draining contour. |
+
+#### `RuntimeMePoolStateWriterHealthData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `healthy` | `usize` | Non-draining non-degraded writers. |
+| `degraded` | `usize` | Non-draining degraded writers. |
+| `draining` | `usize` | Draining writers. |
+
+#### `RuntimeMePoolStateRefillData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `inflight_endpoints_total` | `usize` | Total in-flight endpoint refill operations. |
+| `inflight_dc_total` | `usize` | Number of distinct DC+family keys with refill in flight. |
+| `by_dc` | `RuntimeMePoolStateRefillDcData[]` | Per-DC refill rows. |
+
+#### `RuntimeMePoolStateRefillDcData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `dc` | `i16` | Telegram DC id. |
+| `family` | `string` | Address family label (`V4`, `V6`). |
+| `inflight` | `usize` | In-flight refill operations for this row. |
+
+### `RuntimeMeQualityData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when ME pool snapshot is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeMeQualityPayload?` | Null when unavailable. |
+
+#### `RuntimeMeQualityPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `counters` | `RuntimeMeQualityCountersData` | Key ME lifecycle/error counters. |
+| `route_drops` | `RuntimeMeQualityRouteDropData` | Route drop counters by reason. |
+| `dc_rtt` | `RuntimeMeQualityDcRttData[]` | Per-DC RTT and writer coverage rows. |
+
+#### `RuntimeMeQualityCountersData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `idle_close_by_peer_total` | `u64` | Peer-initiated idle closes. |
+| `reader_eof_total` | `u64` | Reader EOF events. |
+| `kdf_drift_total` | `u64` | KDF drift detections. |
+| `kdf_port_only_drift_total` | `u64` | KDF port-only drift detections. |
+| `reconnect_attempt_total` | `u64` | Reconnect attempts. |
+| `reconnect_success_total` | `u64` | Successful reconnects. |
+
+#### `RuntimeMeQualityRouteDropData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `no_conn_total` | `u64` | Route drops with no connection mapping. |
+| `channel_closed_total` | `u64` | Route drops because destination channel is closed. |
+| `queue_full_total` | `u64` | Route drops due queue backpressure (aggregate). |
+| `queue_full_base_total` | `u64` | Route drops in base-queue path. |
+| `queue_full_high_total` | `u64` | Route drops in high-priority queue path. |
+
+#### `RuntimeMeQualityDcRttData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `dc` | `i16` | Telegram DC id. |
+| `rtt_ema_ms` | `f64?` | RTT EMA for this DC. |
+| `alive_writers` | `usize` | Alive writers currently mapped to this DC. |
+| `required_writers` | `usize` | Target writer floor for this DC. |
+| `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
+
+### `RuntimeUpstreamQualityData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when upstream runtime snapshot is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `policy` | `RuntimeUpstreamQualityPolicyData` | Effective upstream policy values. |
+| `counters` | `RuntimeUpstreamQualityCountersData` | Upstream connect counters. |
+| `summary` | `RuntimeUpstreamQualitySummaryData?` | Aggregate runtime health summary. |
+| `upstreams` | `RuntimeUpstreamQualityUpstreamData[]?` | Per-upstream runtime rows. |
+
+#### `RuntimeUpstreamQualityPolicyData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `connect_retry_attempts` | `u32` | Upstream connect retry attempts. |
+| `connect_retry_backoff_ms` | `u64` | Upstream retry backoff delay. |
+| `connect_budget_ms` | `u64` | Total connect wall-clock budget. |
+| `unhealthy_fail_threshold` | `u32` | Consecutive fail threshold for unhealthy marking. |
+| `connect_failfast_hard_errors` | `bool` | Whether hard errors skip retries. |
+
+#### `RuntimeUpstreamQualityCountersData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `connect_attempt_total` | `u64` | Total connect attempts. |
+| `connect_success_total` | `u64` | Successful connects. |
+| `connect_fail_total` | `u64` | Failed connects. |
+| `connect_failfast_hard_error_total` | `u64` | Fail-fast hard errors. |
+
+#### `RuntimeUpstreamQualitySummaryData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `configured_total` | `usize` | Total configured upstream entries. |
+| `healthy_total` | `usize` | Upstreams currently healthy. |
+| `unhealthy_total` | `usize` | Upstreams currently unhealthy. |
+| `direct_total` | `usize` | Direct-route upstream entries. |
+| `socks4_total` | `usize` | SOCKS4 upstream entries. |
+| `socks5_total` | `usize` | SOCKS5 upstream entries. |
+
+#### `RuntimeUpstreamQualityUpstreamData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `upstream_id` | `usize` | Runtime upstream index. |
+| `route_kind` | `string` | `direct`, `socks4`, `socks5`. |
+| `address` | `string` | Upstream address (`direct` literal for direct route kind). |
+| `weight` | `u16` | Selection weight. |
+| `scopes` | `string` | Configured scope selector. |
+| `healthy` | `bool` | Current health flag. |
+| `fails` | `u32` | Consecutive fail counter. |
+| `last_check_age_secs` | `u64` | Seconds since last health update. |
+| `effective_latency_ms` | `f64?` | Effective latency score used by selector. |
+| `dc` | `RuntimeUpstreamQualityDcData[]` | Per-DC runtime rows. |
+
+#### `RuntimeUpstreamQualityDcData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `dc` | `i16` | Telegram DC id. |
+| `latency_ema_ms` | `f64?` | Per-DC latency EMA. |
+| `ip_preference` | `string` | `unknown`, `prefer_v4`, `prefer_v6`, `both_work`, `unavailable`. |
+
+### `RuntimeNatStunData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when shared STUN state is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeNatStunPayload?` | Null when unavailable. |
+
+#### `RuntimeNatStunPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `flags` | `RuntimeNatStunFlagsData` | NAT probe runtime flags. |
+| `servers` | `RuntimeNatStunServersData` | Configured/live STUN server lists. |
+| `reflection` | `RuntimeNatStunReflectionBlockData` | Reflection cache data for v4/v6. |
+| `stun_backoff_remaining_ms` | `u64?` | Remaining retry backoff (milliseconds). |
+
+#### `RuntimeNatStunFlagsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `nat_probe_enabled` | `bool` | Current NAT probe enable state. |
+| `nat_probe_disabled_runtime` | `bool` | Runtime disable flag due failures/conditions. |
+| `nat_probe_attempts` | `u8` | Configured NAT probe attempt count. |
+
+#### `RuntimeNatStunServersData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `configured` | `string[]` | Configured STUN server entries. |
+| `live` | `string[]` | Runtime live STUN server entries. |
+| `live_total` | `usize` | Number of live STUN entries. |
+
+#### `RuntimeNatStunReflectionBlockData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `v4` | `RuntimeNatStunReflectionData?` | IPv4 reflection data. |
+| `v6` | `RuntimeNatStunReflectionData?` | IPv6 reflection data. |
+
+#### `RuntimeNatStunReflectionData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `addr` | `string` | Reflected public endpoint (`ip:port`). |
+| `age_secs` | `u64` | Reflection value age in seconds. |
+
+### `RuntimeMeSelftestData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Runtime payload availability. |
+| `reason` | `string?` | `source_unavailable` when ME pool is unavailable. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeMeSelftestPayload?` | Null when unavailable. |
+
+#### `RuntimeMeSelftestPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `kdf` | `RuntimeMeSelftestKdfData` | KDF EWMA health state. |
+| `timeskew` | `RuntimeMeSelftestTimeskewData` | Date-header skew health state. |
+| `ip` | `RuntimeMeSelftestIpData` | Interface IP family classification. |
+| `pid` | `RuntimeMeSelftestPidData` | Process PID marker (`one|non-one`). |
+| `bnd` | `RuntimeMeSelftestBndData` | SOCKS BND.ADDR/BND.PORT health state. |
+
+#### `RuntimeMeSelftestKdfData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `state` | `string` | `ok` or `error` based on EWMA threshold. |
+| `ewma_errors_per_min` | `f64` | EWMA KDF error rate per minute. |
+| `threshold_errors_per_min` | `f64` | Threshold used for `error` decision. |
+| `errors_total` | `u64` | Total source errors (`kdf_drift + socks_kdf_strict_reject`). |
+
+#### `RuntimeMeSelftestTimeskewData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `state` | `string` | `ok` or `error` (`max_skew_secs_15m > 60` => `error`). |
+| `max_skew_secs_15m` | `u64?` | Maximum observed skew in the last 15 minutes. |
+| `samples_15m` | `usize` | Number of skew samples in the last 15 minutes. |
+| `last_skew_secs` | `u64?` | Latest observed skew value. |
+| `last_source` | `string?` | Latest skew source marker. |
+| `last_seen_age_secs` | `u64?` | Age of the latest skew sample. |
+
+#### `RuntimeMeSelftestIpData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `v4` | `RuntimeMeSelftestIpFamilyData?` | IPv4 interface probe result; absent when unknown. |
+| `v6` | `RuntimeMeSelftestIpFamilyData?` | IPv6 interface probe result; absent when unknown. |
+
+#### `RuntimeMeSelftestIpFamilyData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `addr` | `string` | Detected interface IP. |
+| `state` | `string` | `good`, `bogon`, or `loopback`. |
+
+#### `RuntimeMeSelftestPidData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `pid` | `u32` | Current process PID. |
+| `state` | `string` | `one` when PID=1, otherwise `non-one`. |
+
+#### `RuntimeMeSelftestBndData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `addr_state` | `string` | `ok`, `bogon`, or `error`. |
+| `port_state` | `string` | `ok`, `zero`, or `error`. |
+| `last_addr` | `string?` | Latest observed SOCKS BND address. |
+| `last_seen_age_secs` | `u64?` | Age of latest BND sample. |
+
+### `RuntimeEdgeConnectionsSummaryData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Endpoint availability under `runtime_edge_enabled`. |
+| `reason` | `string?` | `feature_disabled` or `source_unavailable`. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeEdgeConnectionsSummaryPayload?` | Null when unavailable. |
+
+#### `RuntimeEdgeConnectionsSummaryPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `cache` | `RuntimeEdgeConnectionCacheData` | Runtime edge cache metadata. |
+| `totals` | `RuntimeEdgeConnectionTotalsData` | Connection totals block. |
+| `top` | `RuntimeEdgeConnectionTopData` | Top-N leaderboard blocks. |
+| `telemetry` | `RuntimeEdgeConnectionTelemetryData` | Telemetry-policy flags for counters. |
+
+#### `RuntimeEdgeConnectionCacheData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `ttl_ms` | `u64` | Configured cache TTL in milliseconds. |
+| `served_from_cache` | `bool` | `true` when payload is served from cache. |
+| `stale_cache_used` | `bool` | `true` when stale cache is used because recompute is busy. |
+
+#### `RuntimeEdgeConnectionTotalsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `current_connections` | `u64` | Current global live connections. |
+| `current_connections_me` | `u64` | Current live connections routed through ME. |
+| `current_connections_direct` | `u64` | Current live connections routed through direct path. |
+| `active_users` | `usize` | Users with `current_connections > 0`. |
+
+#### `RuntimeEdgeConnectionTopData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `limit` | `usize` | Effective Top-N row count. |
+| `by_connections` | `RuntimeEdgeConnectionUserData[]` | Users sorted by current connections. |
+| `by_throughput` | `RuntimeEdgeConnectionUserData[]` | Users sorted by cumulative octets. |
+
+#### `RuntimeEdgeConnectionUserData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `username` | `string` | Username. |
+| `current_connections` | `u64` | Current live connections for user. |
+| `total_octets` | `u64` | Cumulative (`client->proxy + proxy->client`) octets. |
+
+#### `RuntimeEdgeConnectionTelemetryData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `user_enabled` | `bool` | Per-user telemetry enable flag. |
+| `throughput_is_cumulative` | `bool` | Always `true` in current implementation. |
+
+### `RuntimeEdgeEventsData`
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `bool` | Endpoint availability under `runtime_edge_enabled`. |
+| `reason` | `string?` | `feature_disabled` when endpoint is disabled. |
+| `generated_at_epoch_secs` | `u64` | Snapshot generation timestamp. |
+| `data` | `RuntimeEdgeEventsPayload?` | Null when unavailable. |
+
+#### `RuntimeEdgeEventsPayload`
+| Field | Type | Description |
+| --- | --- | --- |
+| `capacity` | `usize` | Effective ring-buffer capacity. |
+| `dropped_total` | `u64` | Count of dropped oldest events due capacity pressure. |
+| `events` | `ApiEventRecord[]` | Recent events in chronological order. |
+
+#### `ApiEventRecord`
+| Field | Type | Description |
+| --- | --- | --- |
+| `seq` | `u64` | Monotonic sequence number. |
+| `ts_epoch_secs` | `u64` | Event timestamp (Unix seconds). |
+| `event_type` | `string` | Event kind identifier. |
+| `context` | `string` | Context text (truncated to implementation-defined max length). |
 
 ### `ZeroAllData`
 | Field | Type | Description |
@@ -485,7 +880,27 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `floor_mode` | `string` | Writer floor mode. |
 | `adaptive_floor_idle_secs` | `u64` | Idle threshold for adaptive floor. |
 | `adaptive_floor_min_writers_single_endpoint` | `u8` | Minimum writers for single-endpoint DC in adaptive mode. |
+| `adaptive_floor_min_writers_multi_endpoint` | `u8` | Minimum writers for multi-endpoint DC in adaptive mode. |
 | `adaptive_floor_recover_grace_secs` | `u64` | Grace period for floor recovery. |
+| `adaptive_floor_writers_per_core_total` | `u16` | Target total writers-per-core budget in adaptive mode. |
+| `adaptive_floor_cpu_cores_override` | `u16` | CPU core override (`0` means auto-detect). |
+| `adaptive_floor_max_extra_writers_single_per_core` | `u16` | Extra single-endpoint writers budget per core. |
+| `adaptive_floor_max_extra_writers_multi_per_core` | `u16` | Extra multi-endpoint writers budget per core. |
+| `adaptive_floor_max_active_writers_per_core` | `u16` | Active writer cap per core. |
+| `adaptive_floor_max_warm_writers_per_core` | `u16` | Warm writer cap per core. |
+| `adaptive_floor_max_active_writers_global` | `u32` | Global active writer cap. |
+| `adaptive_floor_max_warm_writers_global` | `u32` | Global warm writer cap. |
+| `adaptive_floor_cpu_cores_detected` | `u32` | Runtime-detected CPU cores. |
+| `adaptive_floor_cpu_cores_effective` | `u32` | Effective core count used for adaptive caps. |
+| `adaptive_floor_global_cap_raw` | `u64` | Raw global cap before clamping. |
+| `adaptive_floor_global_cap_effective` | `u64` | Effective global cap after clamping. |
+| `adaptive_floor_target_writers_total` | `u64` | Current adaptive total writer target. |
+| `adaptive_floor_active_cap_configured` | `u64` | Configured global active cap. |
+| `adaptive_floor_active_cap_effective` | `u64` | Effective global active cap. |
+| `adaptive_floor_warm_cap_configured` | `u64` | Configured global warm cap. |
+| `adaptive_floor_warm_cap_effective` | `u64` | Effective global warm cap. |
+| `adaptive_floor_active_writers_current` | `u64` | Current active writers count. |
+| `adaptive_floor_warm_writers_current` | `u64` | Current warm writers count. |
 | `me_keepalive_enabled` | `bool` | ME keepalive toggle. |
 | `me_keepalive_interval_secs` | `u64` | Keepalive period. |
 | `me_keepalive_jitter_secs` | `u64` | Keepalive jitter. |
@@ -507,6 +922,8 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `me_single_endpoint_outage_backoff_max_ms` | `u64` | Outage mode max reconnect backoff. |
 | `me_single_endpoint_shadow_rotate_every_secs` | `u64` | Shadow rotation interval. |
 | `me_deterministic_writer_sort` | `bool` | Deterministic writer ordering toggle. |
+| `me_writer_pick_mode` | `string` | Writer picker mode (`sorted_rr`, `p2c`). |
+| `me_writer_pick_sample_size` | `u8` | Candidate sample size for `p2c` picker mode. |
 | `me_socks_kdf_policy` | `string` | Current SOCKS KDF policy mode. |
 | `quarantined_endpoints_total` | `usize` | Total quarantined endpoints. |
 | `quarantined_endpoints` | `MinimalQuarantineData[]` | Quarantine details. |
@@ -572,14 +989,25 @@ Note: the request contract is defined, but the corresponding route currently ret
 | --- | --- | --- |
 | `dc` | `i16` | Telegram DC id. |
 | `endpoints` | `string[]` | Endpoints in this DC (`ip:port`). |
+| `endpoint_writers` | `DcEndpointWriters[]` | Active writer counts grouped by endpoint. |
 | `available_endpoints` | `usize` | Endpoints currently available in this DC. |
 | `available_pct` | `f64` | `available_endpoints / endpoints_total * 100`. |
 | `required_writers` | `usize` | Required writer count for this DC. |
+| `floor_min` | `usize` | Floor lower bound for this DC. |
+| `floor_target` | `usize` | Floor target writer count for this DC. |
+| `floor_max` | `usize` | Floor upper bound for this DC. |
+| `floor_capped` | `bool` | `true` when computed floor target was capped by active limits. |
 | `alive_writers` | `usize` | Alive writers in this DC. |
 | `coverage_pct` | `f64` | `alive_writers / required_writers * 100`. |
 | `rtt_ms` | `f64?` | Aggregated RTT for DC. |
 | `load` | `usize` | Active client sessions bound to this DC. |
 
+#### `DcEndpointWriters`
+| Field | Type | Description |
+| --- | --- | --- |
+| `endpoint` | `string` | Endpoint (`ip:port`). |
+| `active_writers` | `usize` | Active writers currently mapped to endpoint. |
+
 ### `UserInfo`
 | Field | Type | Description |
 | --- | --- | --- |
@@ -591,6 +1019,9 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `max_unique_ips` | `usize?` | Optional unique IP limit. |
 | `current_connections` | `u64` | Current live connections. |
 | `active_unique_ips` | `usize` | Current active unique source IPs. |
+| `active_unique_ips_list` | `ip[]` | Current active unique source IP list. |
+| `recent_unique_ips` | `usize` | Unique source IP count inside the configured recent window. |
+| `recent_unique_ips_list` | `ip[]` | Recent-window unique source IP list. |
 | `total_octets` | `u64` | Total traffic octets for this user. |
 | `links` | `UserLinks` | Active connection links derived from current config. |
 
@@ -602,11 +1033,15 @@ Note: the request contract is defined, but the corresponding route currently ret
 | `tls` | `string[]` | Active `tg://proxy` links for EE-TLS mode (for each host+TLS domain). |
 
 Link generation uses active config and enabled modes:
-- `[general.links].public_host/public_port` have priority.
-- If `public_host` is not set, startup-detected public IPs are used (`IPv4`, `IPv6`, or both when available).
-- Fallback host sources: listener `announce`, `announce_ip`, explicit listener `ip`.
-- Legacy fallback: `listen_addr_ipv4` and `listen_addr_ipv6` when routable.
-- Startup-detected IPs are fixed for process lifetime and refreshed on restart.
+- Link port is `general.links.public_port` when configured; otherwise `server.port`.
+- If `general.links.public_host` is non-empty, it is used as the single link host override.
+- If `public_host` is not set, hosts are resolved from `server.listeners` in order:
+  `announce` -> `announce_ip` -> listener bind `ip`.
+- For wildcard listener IPs (`0.0.0.0` / `::`), startup-detected external IP of the same family is used when available.
+- Listener-derived hosts are de-duplicated while preserving first-seen order.
+- If multiple hosts are resolved, API returns links for all resolved hosts in every enabled mode.
+- If no host can be resolved from listeners, fallback is startup-detected `IPv4 -> IPv6`.
+- Final compatibility fallback uses `listen_addr_ipv4`/`listen_addr_ipv6` when routable, otherwise `"UNKNOWN"`.
 - User rows are sorted by `username` in ascending lexical order.
 
 ### `CreateUserResponse`
@@ -619,10 +1054,10 @@ Link generation uses active config and enabled modes:
 
 | Endpoint | Notes |
 | --- | --- |
-| `POST /v1/users` | Creates user and validates resulting config before atomic save. |
-| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged. |
+| `POST /v1/users` | Creates user, validates config, then atomically updates only affected `access.*` TOML tables (`access.users` always, plus optional per-user tables present in request). |
+| `PATCH /v1/users/{username}` | Partial update of provided fields only. Missing fields remain unchanged. Current implementation persists full config document on success. |
 | `POST /v1/users/{username}/rotate-secret` | Currently returns `404` in runtime route matcher; request schema is reserved for intended behavior. |
-| `DELETE /v1/users/{username}` | Deletes user and related optional settings. Last user deletion is blocked. |
+| `DELETE /v1/users/{username}` | Deletes only specified user, removes this user from related optional `access.user_*` maps, blocks last-user deletion, and atomically updates only related `access.*` TOML tables. |
 
 All mutating endpoints:
 - Respect `read_only` mode.
@@ -630,6 +1065,10 @@ All mutating endpoints:
 - Return new `revision` after successful write.
 - Use process-local mutation lock + atomic write (`tmp + rename`) for config persistence.
 
+Delete path cleanup guarantees:
+- Config cleanup removes only the requested username keys.
+- Runtime unique-IP cleanup removes only this user's limiter and tracked IP state.
+
 ## Runtime State Matrix
 
 | Endpoint | `minimal_runtime_enabled=false` | `minimal_runtime_enabled=true` + source unavailable | `minimal_runtime_enabled=true` + source available |
@@ -643,6 +1082,28 @@ All mutating endpoints:
 - ME endpoints: ME pool is absent (for example direct-only mode or failed ME initialization).
 - Upstreams endpoint: non-blocking upstream snapshot lock is unavailable at request time.
 
+Additional runtime endpoint behavior:
+
+| Endpoint | Disabled by feature flag | `source_unavailable` condition | Normal mode |
+| --- | --- | --- | --- |
+| `/v1/runtime/me_pool_state` | No | ME pool snapshot unavailable | `enabled=true`, full payload |
+| `/v1/runtime/me_quality` | No | ME pool snapshot unavailable | `enabled=true`, full payload |
+| `/v1/runtime/upstream_quality` | No | Upstream runtime snapshot unavailable | `enabled=true`, full payload |
+| `/v1/runtime/nat_stun` | No | STUN shared state unavailable | `enabled=true`, full payload |
+| `/v1/runtime/me-selftest` | No | ME pool unavailable => `enabled=false`, `reason=source_unavailable` | `enabled=true`, full payload |
+| `/v1/runtime/connections/summary` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Recompute lock contention with no cache entry => `enabled=true`, `reason=source_unavailable` | `enabled=true`, full payload |
+| `/v1/runtime/events/recent` | `runtime_edge_enabled=false` => `enabled=false`, `reason=feature_disabled` | Not used in current implementation | `enabled=true`, full payload |
+
+## ME Fallback Behavior Exposed Via API
+
+When `general.use_middle_proxy=true` and `general.me2dc_fallback=true`:
+- Startup does not block on full ME pool readiness; initialization can continue in background.
+- Runtime initialization payload can expose ME stage `background_init` until pool becomes ready.
+- Admission/routing decision uses two readiness grace windows for "ME not ready" periods:
+  `80s` before first-ever readiness is observed (startup grace),
+  `6s` after readiness has been observed at least once (runtime failover timeout).
+- While in fallback window breach, new sessions are routed via Direct-DC; when ME becomes ready, routing returns to Middle mode for new sessions.
+
 ## Serialization Rules
 
 - Success responses always include `revision`.
@@ -650,6 +1111,7 @@ All mutating endpoints:
 - Optional fields with `skip_serializing_if` are omitted when absent.
 - Nullable payload fields may still be `null` where contract uses `?` (for example `UserInfo` option fields).
 - For `/v1/stats/upstreams`, authentication details of SOCKS upstreams are intentionally omitted.
+- `ip[]` fields are serialized as JSON string arrays (for example `"1.2.3.4"`, `"2001:db8::1"`).
 
 ## Operational Notes
 
@@ -665,7 +1127,7 @@ All mutating endpoints:
 | Runtime apply path | Successful writes are picked up by existing config watcher/hot-reload path. |
 | Exposure | Built-in TLS/mTLS is not provided. Use loopback bind + reverse proxy if needed. |
 | Pagination | User list currently has no pagination/filtering. |
-| Serialization side effect | Config comments/manual formatting are not preserved on write. |
+| Serialization side effect | Updated TOML table bodies are re-serialized on write. Endpoints that persist full config can still rewrite broader formatting/comments. |
 
 ## Known Limitations (Current Release)
 

src/api/config_store.rs

@@ -1,13 +1,39 @@
+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)
@@ -66,6 +92,142 @@ pub(super) async fn save_config_to_disk(
     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

src/api/mod.rs

@@ -28,6 +28,7 @@ mod model;
 mod runtime_edge;
 mod runtime_init;
 mod runtime_min;
+mod runtime_selftest;
 mod runtime_stats;
 mod runtime_watch;
 mod runtime_zero;
@@ -48,6 +49,7 @@ 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,
@@ -73,8 +75,7 @@ pub(super) struct ApiShared {
     pub(super) me_pool: Arc<RwLock<Option<Arc<MePool>>>>,
     pub(super) upstream_manager: Arc<UpstreamManager>,
     pub(super) config_path: PathBuf,
-    pub(super) startup_detected_ip_v4: Option<IpAddr>,
-    pub(super) startup_detected_ip_v6: Option<IpAddr>,
+    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>>>,
@@ -89,6 +90,10 @@ 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(
@@ -100,8 +105,7 @@ pub async fn serve(
     config_rx: watch::Receiver<Arc<ProxyConfig>>,
     admission_rx: watch::Receiver<bool>,
     config_path: PathBuf,
-    startup_detected_ip_v4: Option<IpAddr>,
-    startup_detected_ip_v6: Option<IpAddr>,
+    detected_ips_rx: watch::Receiver<(Option<IpAddr>, Option<IpAddr>)>,
     process_started_at_epoch_secs: u64,
     startup_tracker: Arc<StartupTracker>,
 ) {
@@ -132,8 +136,7 @@ pub async fn serve(
         me_pool,
         upstream_manager,
         config_path,
-        startup_detected_ip_v4,
-        startup_detected_ip_v6,
+        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)),
@@ -333,6 +336,11 @@ async fn handle(
                 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()).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;
@@ -349,12 +357,13 @@ async fn handle(
             }
             ("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,
-                    shared.startup_detected_ip_v4,
-                    shared.startup_detected_ip_v6,
+                    detected_ip_v4,
+                    detected_ip_v6,
                 )
                 .await;
                 Ok(success_response(StatusCode::OK, users, revision))
@@ -392,12 +401,13 @@ async fn handle(
                 {
                     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,
-                            shared.startup_detected_ip_v4,
-                            shared.startup_detected_ip_v6,
+                            detected_ip_v4,
+                            detected_ip_v6,
                         )
                         .await;
                         if let Some(user_info) = users.into_iter().find(|entry| entry.username == user)

src/api/runtime_selftest.rs

@@ -0,0 +1,228 @@
+use std::net::IpAddr;
+use std::sync::{Mutex, OnceLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use serde::Serialize;
+
+use crate::network::probe::{detect_interface_ipv4, detect_interface_ipv6, is_bogon};
+use crate::transport::middle_proxy::{bnd_snapshot, timeskew_snapshot};
+
+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 RuntimeMeSelftestPayload {
+    pub(super) kdf: RuntimeMeSelftestKdfData,
+    pub(super) timeskew: RuntimeMeSelftestTimeskewData,
+    pub(super) ip: RuntimeMeSelftestIpData,
+    pub(super) pid: RuntimeMeSelftestPidData,
+    pub(super) bnd: RuntimeMeSelftestBndData,
+}
+
+#[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) -> 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 bnd = bnd_snapshot();
+
+    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: RuntimeMeSelftestBndData {
+                addr_state: bnd.addr_status,
+                port_state: bnd.port_status,
+                last_addr: bnd.last_addr.map(|value| value.to_string()),
+                last_seen_age_secs: bnd.last_seen_age_secs,
+            },
+        }),
+    }
+}
+
+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 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/users.rs

@@ -8,7 +8,8 @@ use crate::stats::Stats;
 
 use super::ApiShared;
 use super::config_store::{
-    ensure_expected_revision, load_config_from_disk, save_config_to_disk,
+    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,
@@ -21,6 +22,12 @@ pub(super) async fn create_user(
     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",
@@ -84,19 +91,37 @@ pub(super) async fn create_user(
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
 
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let mut touched_sections = vec![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,
-        shared.startup_detected_ip_v4,
-        shared.startup_detected_ip_v6,
+        detected_ip_v4,
+        detected_ip_v6,
     )
     .await;
     let user = users
@@ -118,8 +143,8 @@ pub(super) async fn create_user(
             links: build_user_links(
                 &cfg,
                 &secret,
-                shared.startup_detected_ip_v4,
-                shared.startup_detected_ip_v6,
+                detected_ip_v4,
+                detected_ip_v6,
             ),
         });
 
@@ -185,12 +210,13 @@ pub(super) async fn patch_user(
     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,
-        shared.startup_detected_ip_v4,
-        shared.startup_detected_ip_v6,
+        detected_ip_v4,
+        detected_ip_v6,
     )
     .await;
     let user_info = users
@@ -229,15 +255,24 @@ pub(super) async fn rotate_secret(
     cfg.access.users.insert(user.to_string(), secret.clone());
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let 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,
-        shared.startup_detected_ip_v4,
-        shared.startup_detected_ip_v6,
+        detected_ip_v4,
+        detected_ip_v6,
     )
     .await;
     let user_info = users
@@ -287,7 +322,15 @@ pub(super) async fn delete_user(
 
     cfg.validate()
         .map_err(|e| ApiFailure::bad_request(format!("config validation failed: {}", e)))?;
-    let revision = save_config_to_disk(&shared.config_path, &cfg).await?;
+    let 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;
@@ -418,17 +461,6 @@ fn resolve_link_hosts(
         return vec![host.to_string()];
     }
 
-    let mut startup_hosts = Vec::new();
-    if let Some(ip) = startup_detected_ip_v4 {
-        push_unique_host(&mut startup_hosts, &ip.to_string());
-    }
-    if let Some(ip) = startup_detected_ip_v6 {
-        push_unique_host(&mut startup_hosts, &ip.to_string());
-    }
-    if !startup_hosts.is_empty() {
-        return startup_hosts;
-    }
-
     let mut hosts = Vec::new();
     for listener in &cfg.server.listeners {
         if let Some(host) = listener
@@ -443,24 +475,44 @@ fn resolve_link_hosts(
         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;
         }
-        if !listener.ip.is_unspecified() {
-            push_unique_host(&mut hosts, &listener.ip.to_string());
-        }
+        push_unique_host(&mut hosts, &listener.ip.to_string());
     }
 
-    if hosts.is_empty() {
-        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;
     }
 
-    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) {

src/config/defaults.rs

@@ -119,11 +119,11 @@ pub(crate) fn default_metrics_whitelist() -> Vec<IpNetwork> {
 }
 
 pub(crate) fn default_api_listen() -> String {
-    "127.0.0.1:9091".to_string()
+    "0.0.0.0:9091".to_string()
 }
 
 pub(crate) fn default_api_whitelist() -> Vec<IpNetwork> {
-    default_metrics_whitelist()
+    vec!["127.0.0.0/8".parse().unwrap()]
 }
 
 pub(crate) fn default_api_request_body_limit_bytes() -> usize {
@@ -131,7 +131,7 @@ pub(crate) fn default_api_request_body_limit_bytes() -> usize {
 }
 
 pub(crate) fn default_api_minimal_runtime_enabled() -> bool {
-    false
+    true
 }
 
 pub(crate) fn default_api_minimal_runtime_cache_ttl_ms() -> u64 {

src/config/types.rs

@@ -1044,7 +1044,7 @@ impl Default for LinksConfig {
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct ApiConfig {
     /// Enable or disable REST API.
-    #[serde(default)]
+    #[serde(default = "default_true")]
     pub enabled: bool,
 
     /// Listen address for API in `IP:PORT` format.
@@ -1096,7 +1096,7 @@ pub struct ApiConfig {
 impl Default for ApiConfig {
     fn default() -> Self {
         Self {
-            enabled: false,
+            enabled: default_true(),
             listen: default_api_listen(),
             whitelist: default_api_whitelist(),
             auth_header: String::new(),

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,320 @@
+use std::time::Duration;
+
+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, bool, Option<String>) {
+    let mut config_path = "config.toml".to_string();
+    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() {
+            "--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!("  --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, 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,515 @@
+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.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,551 @@
+//! 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, 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 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).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.is_empty() {
+        info!(
+            "IP limits configured for {} users",
+            config.access.user_max_unique_ips.len()
+        );
+    }
+    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 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,
+                    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.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);
+    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
+    let max_connections = Arc::new(Semaphore::new(10_000));
+
+    let me2dc_fallback = config.general.me2dc_fallback;
+    let me_init_retry_attempts = config.general.me_init_retry_attempts;
+    if use_middle_proxy && !decision.ipv4_me && !decision.ipv6_me {
+        if me2dc_fallback {
+            warn!("No usable IP family for Middle Proxy detected; falling back to direct DC");
+            use_middle_proxy = false;
+        } else {
+            warn!(
+                "No usable IP family for Middle Proxy detected; me2dc_fallback=false, ME init retries stay active"
+            );
+        }
+    }
+
+    if use_middle_proxy {
+        startup_tracker
+            .set_me_status(StartupMeStatus::Initializing, COMPONENT_ME_SECRET_FETCH)
+            .await;
+        startup_tracker
+            .start_component(
+                COMPONENT_ME_SECRET_FETCH,
+                Some("fetch proxy-secret from source/cache".to_string()),
+            )
+            .await;
+        startup_tracker
+            .set_me_retry_limit(if !me2dc_fallback || me_init_retry_attempts == 0 {
+                "unlimited".to_string()
+            } else {
+                me_init_retry_attempts.to_string()
+            })
+            .await;
+    } else {
+        startup_tracker
+            .set_me_status(StartupMeStatus::Skipped, "skipped")
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_SECRET_FETCH,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_PROXY_CONFIG_V4,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_PROXY_CONFIG_V6,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_POOL_CONSTRUCT,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+        startup_tracker
+            .skip_component(
+                COMPONENT_ME_POOL_INIT_STAGE1,
+                Some("middle proxy mode disabled".to_string()),
+            )
+            .await;
+    }
+
+    let me_pool: Option<Arc<MePool>> = me_startup::initialize_me_pool(
+        use_middle_proxy,
+        &config,
+        &decision,
+        &probe,
+        &startup_tracker,
+        upstream_manager.clone(),
+        rng.clone(),
+        stats.clone(),
+        api_me_pool.clone(),
+    )
+    .await;
+
+    // If ME failed to initialize, force direct-only mode.
+    if me_pool.is_some() {
+        startup_tracker
+            .set_transport_mode("middle_proxy")
+            .await;
+        startup_tracker
+            .set_degraded(false)
+            .await;
+        info!("Transport: Middle-End Proxy - all DC-over-RPC");
+    } else {
+        let _ = use_middle_proxy;
+        use_middle_proxy = false;
+        // Make runtime config reflect direct-only mode for handlers.
+        config.general.use_middle_proxy = false;
+        startup_tracker
+            .set_transport_mode("direct")
+            .await;
+        startup_tracker
+            .set_degraded(true)
+            .await;
+        if me2dc_fallback {
+            startup_tracker
+                .set_me_status(StartupMeStatus::Failed, "fallback_to_direct")
+                .await;
+        } else {
+            startup_tracker
+                .set_me_status(StartupMeStatus::Skipped, "skipped")
+                .await;
+        }
+        info!("Transport: Direct DC - TCP - standard DC-over-TCP");
+    }
+
+    // Freeze config after possible fallback decision
+    let config = Arc::new(config);
+
+    let replay_checker = Arc::new(ReplayChecker::new(
+        config.access.replay_check_len,
+        Duration::from_secs(config.access.replay_window_secs),
+    ));
+
+    let buffer_pool = Arc::new(BufferPool::with_config(16 * 1024, 4096));
+
+    connectivity::run_startup_connectivity(
+        &config,
+        &me_pool,
+        rng.clone(),
+        &startup_tracker,
+        upstream_manager.clone(),
+        prefer_ipv6,
+        &decision,
+        process_started_at,
+        api_me_pool.clone(),
+    )
+    .await;
+
+    let runtime_watches = runtime_tasks::spawn_runtime_tasks(
+        &config,
+        &config_path,
+        &probe,
+        prefer_ipv6,
+        decision.ipv4_dc,
+        decision.ipv6_dc,
+        &startup_tracker,
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        me_pool.clone(),
+        rng.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        api_config_tx.clone(),
+        me_pool.clone(),
+    )
+    .await;
+    let config_rx = runtime_watches.config_rx;
+    let log_level_rx = runtime_watches.log_level_rx;
+    let detected_ip_v4 = runtime_watches.detected_ip_v4;
+    let detected_ip_v6 = runtime_watches.detected_ip_v6;
+
+    admission::configure_admission_gate(
+        &config,
+        me_pool.clone(),
+        route_runtime.clone(),
+        &admission_tx,
+        config_rx.clone(),
+    )
+    .await;
+    let _admission_tx_hold = admission_tx;
+
+    let bound = listeners::bind_listeners(
+        &config,
+        decision.ipv4_dc,
+        decision.ipv6_dc,
+        detected_ip_v4,
+        detected_ip_v6,
+        &startup_tracker,
+        config_rx.clone(),
+        admission_rx.clone(),
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        buffer_pool.clone(),
+        rng.clone(),
+        me_pool.clone(),
+        route_runtime.clone(),
+        tls_cache.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        max_connections.clone(),
+    )
+    .await?;
+    let listeners = bound.listeners;
+    let has_unix_listener = bound.has_unix_listener;
+
+    if listeners.is_empty() && !has_unix_listener {
+        error!("No listeners. Exiting.");
+        std::process::exit(1);
+    }
+
+    runtime_tasks::apply_runtime_log_filter(
+        has_rust_log,
+        &effective_log_level,
+        filter_handle,
+        log_level_rx,
+    )
+    .await;
+
+    runtime_tasks::spawn_metrics_if_configured(
+        &config,
+        &startup_tracker,
+        stats.clone(),
+        beobachten.clone(),
+        ip_tracker.clone(),
+        config_rx.clone(),
+    )
+    .await;
+
+    runtime_tasks::mark_runtime_ready(&startup_tracker).await;
+
+    listeners::spawn_tcp_accept_loops(
+        listeners,
+        config_rx.clone(),
+        admission_rx.clone(),
+        stats.clone(),
+        upstream_manager.clone(),
+        replay_checker.clone(),
+        buffer_pool.clone(),
+        rng.clone(),
+        me_pool.clone(),
+        route_runtime.clone(),
+        tls_cache.clone(),
+        ip_tracker.clone(),
+        beobachten.clone(),
+        max_connections.clone(),
+    );
+
+    shutdown::wait_for_shutdown(process_started_at, me_pool).await;
+
+    Ok(())
+}

src/maestro/runtime_tasks.rs

@@ -0,0 +1,317 @@
+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_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 {
+                ip_tracker_policy.load_limits(&cfg.access.user_max_unique_ips).await;
+                prev_limits = cfg.access.user_max_unique_ips.clone();
+            }
+
+            if prev_mode != cfg.access.user_max_unique_ips_mode
+                || prev_window != cfg.access.user_max_unique_ips_window_secs
+            {
+                ip_tracker_policy
+                    .set_limit_policy(
+                        cfg.access.user_max_unique_ips_mode,
+                        cfg.access.user_max_unique_ips_window_secs,
+                    )
+                    .await;
+                prev_mode = cfg.access.user_max_unique_ips_mode;
+                prev_window = cfg.access.user_max_unique_ips_window_secs;
+            }
+        }
+    });
+
+    let beobachten_writer = beobachten.clone();
+    let config_rx_beobachten = config_rx.clone();
+    tokio::spawn(async move {
+        loop {
+            let cfg = config_rx_beobachten.borrow().clone();
+            let sleep_secs = cfg.general.beobachten_flush_secs.max(1);
+
+            if cfg.general.beobachten {
+                let ttl = std::time::Duration::from_secs(cfg.general.beobachten_minutes.saturating_mul(60));
+                let path = cfg.general.beobachten_file.clone();
+                let snapshot = beobachten_writer.snapshot_text(ttl);
+                if let Err(e) = write_beobachten_snapshot(&path, &snapshot).await {
+                    warn!(error = %e, path = %path, "Failed to flush beobachten snapshot");
+                }
+            }
+
+            tokio::time::sleep(std::time::Duration::from_secs(sleep_secs)).await;
+        }
+    });
+
+    if let Some(pool) = me_pool {
+        let reinit_trigger_capacity = config.general.me_reinit_trigger_channel.max(1);
+        let (reinit_tx, reinit_rx) = mpsc::channel::<MeReinitTrigger>(reinit_trigger_capacity);
+
+        let pool_clone_sched = pool.clone();
+        let rng_clone_sched = rng.clone();
+        let config_rx_clone_sched = config_rx.clone();
+        tokio::spawn(async move {
+            crate::transport::middle_proxy::me_reinit_scheduler(
+                pool_clone_sched,
+                rng_clone_sched,
+                config_rx_clone_sched,
+                reinit_rx,
+            )
+            .await;
+        });
+
+        let pool_clone = pool.clone();
+        let config_rx_clone = config_rx.clone();
+        let reinit_tx_updater = reinit_tx.clone();
+        tokio::spawn(async move {
+            crate::transport::middle_proxy::me_config_updater(
+                pool_clone,
+                config_rx_clone,
+                reinit_tx_updater,
+            )
+            .await;
+        });
+
+        let config_rx_clone_rot = config_rx.clone();
+        let reinit_tx_rotation = reinit_tx.clone();
+        tokio::spawn(async move {
+            crate::transport::middle_proxy::me_rotation_task(config_rx_clone_rot, reinit_tx_rotation)
+                .await;
+        });
+    }
+
+    RuntimeWatches {
+        config_rx,
+        log_level_rx,
+        detected_ip_v4,
+        detected_ip_v6,
+    }
+}
+
+pub(crate) async fn apply_runtime_log_filter(
+    has_rust_log: bool,
+    effective_log_level: &LogLevel,
+    filter_handle: reload::Handle<EnvFilter, tracing_subscriber::Registry>,
+    mut log_level_rx: watch::Receiver<LogLevel>,
+) {
+    let runtime_filter = if has_rust_log {
+        EnvFilter::from_default_env()
+    } else if matches!(effective_log_level, LogLevel::Silent) {
+        EnvFilter::new("warn,telemt::links=info")
+    } else {
+        EnvFilter::new(effective_log_level.to_filter_str())
+    };
+    filter_handle
+        .reload(runtime_filter)
+        .expect("Failed to switch log filter");
+
+    tokio::spawn(async move {
+        loop {
+            if log_level_rx.changed().await.is_err() {
+                break;
+            }
+            let level = log_level_rx.borrow_and_update().clone();
+            let new_filter = tracing_subscriber::EnvFilter::new(level.to_filter_str());
+            if let Err(e) = filter_handle.reload(new_filter) {
+                tracing::error!("config reload: failed to update log filter: {}", e);
+            }
+        }
+    });
+}
+
+pub(crate) async fn spawn_metrics_if_configured(
+    config: &Arc<ProxyConfig>,
+    startup_tracker: &Arc<StartupTracker>,
+    stats: Arc<Stats>,
+    beobachten: Arc<BeobachtenStore>,
+    ip_tracker: Arc<UserIpTracker>,
+    config_rx: watch::Receiver<Arc<ProxyConfig>>,
+) {
+    if let Some(port) = config.server.metrics_port {
+        startup_tracker
+            .start_component(
+                COMPONENT_METRICS_START,
+                Some(format!("spawn metrics endpoint on {}", port)),
+            )
+            .await;
+        let stats = stats.clone();
+        let beobachten = beobachten.clone();
+        let config_rx_metrics = config_rx.clone();
+        let ip_tracker_metrics = ip_tracker.clone();
+        let whitelist = config.server.metrics_whitelist.clone();
+        tokio::spawn(async move {
+            metrics::serve(
+                port,
+                stats,
+                beobachten,
+                ip_tracker_metrics,
+                config_rx_metrics,
+                whitelist,
+            )
+            .await;
+        });
+        startup_tracker
+            .complete_component(
+                COMPONENT_METRICS_START,
+                Some("metrics task spawned".to_string()),
+            )
+            .await;
+    } else {
+        startup_tracker
+            .skip_component(
+                COMPONENT_METRICS_START,
+                Some("server.metrics_port is not configured".to_string()),
+            )
+            .await;
+    }
+}
+
+pub(crate) async fn mark_runtime_ready(startup_tracker: &Arc<StartupTracker>) {
+    startup_tracker
+        .complete_component(
+            COMPONENT_RUNTIME_READY,
+            Some("startup pipeline is fully initialized".to_string()),
+        )
+        .await;
+    startup_tracker.mark_ready().await;
+}

src/maestro/shutdown.rs

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

src/maestro/tls_bootstrap.rs

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

src/metrics.rs

@@ -17,6 +17,7 @@ use crate::config::ProxyConfig;
 use crate::ip_tracker::UserIpTracker;
 use crate::stats::beobachten::BeobachtenStore;
 use crate::stats::Stats;
+use crate::transport::{ListenOptions, create_listener};
 
 pub async fn serve(
     port: u16,
@@ -26,16 +27,90 @@ pub async fn serve(
     config_rx: tokio::sync::watch::Receiver<Arc<ProxyConfig>>,
     whitelist: Vec<IpNetwork>,
 ) {
-    let addr = SocketAddr::from(([0, 0, 0, 0], port));
-    let listener = match TcpListener::bind(addr).await {
-        Ok(l) => l,
-        Err(e) => {
-            warn!(error = %e, "Failed to bind metrics on {}", addr);
-            return;
-        }
-    };
-    info!("Metrics endpoint: http://{}/metrics and /beobachten", addr);
+    let whitelist = Arc::new(whitelist);
+    let mut listener_v4 = None;
+    let mut listener_v6 = None;
 
+    let addr_v4 = SocketAddr::from(([0, 0, 0, 0], port));
+    match bind_metrics_listener(addr_v4, false) {
+        Ok(listener) => {
+            info!("Metrics endpoint: http://{}/metrics and /beobachten", addr_v4);
+            listener_v4 = Some(listener);
+        }
+        Err(e) => {
+            warn!(error = %e, "Failed to bind metrics on {}", addr_v4);
+        }
+    }
+
+    let addr_v6 = SocketAddr::from(([0, 0, 0, 0, 0, 0, 0, 0], port));
+    match bind_metrics_listener(addr_v6, true) {
+        Ok(listener) => {
+            info!("Metrics endpoint: http://[::]:{}/metrics and /beobachten", port);
+            listener_v6 = Some(listener);
+        }
+        Err(e) => {
+            warn!(error = %e, "Failed to bind metrics on {}", addr_v6);
+        }
+    }
+
+    match (listener_v4, listener_v6) {
+        (None, None) => {
+            warn!("Metrics listener is unavailable on both IPv4 and IPv6");
+        }
+        (Some(listener), None) | (None, Some(listener)) => {
+            serve_listener(
+                listener, stats, beobachten, ip_tracker, config_rx, whitelist,
+            )
+            .await;
+        }
+        (Some(listener4), Some(listener6)) => {
+            let stats_v6 = stats.clone();
+            let beobachten_v6 = beobachten.clone();
+            let ip_tracker_v6 = ip_tracker.clone();
+            let config_rx_v6 = config_rx.clone();
+            let whitelist_v6 = whitelist.clone();
+            tokio::spawn(async move {
+                serve_listener(
+                    listener6,
+                    stats_v6,
+                    beobachten_v6,
+                    ip_tracker_v6,
+                    config_rx_v6,
+                    whitelist_v6,
+                )
+                .await;
+            });
+            serve_listener(
+                listener4,
+                stats,
+                beobachten,
+                ip_tracker,
+                config_rx,
+                whitelist,
+            )
+            .await;
+        }
+    }
+}
+
+fn bind_metrics_listener(addr: SocketAddr, ipv6_only: bool) -> std::io::Result<TcpListener> {
+    let options = ListenOptions {
+        reuse_port: false,
+        ipv6_only,
+        ..Default::default()
+    };
+    let socket = create_listener(addr, &options)?;
+    TcpListener::from_std(socket.into())
+}
+
+async fn serve_listener(
+    listener: TcpListener,
+    stats: Arc<Stats>,
+    beobachten: Arc<BeobachtenStore>,
+    ip_tracker: Arc<UserIpTracker>,
+    config_rx: tokio::sync::watch::Receiver<Arc<ProxyConfig>>,
+    whitelist: Arc<Vec<IpNetwork>>,
+) {
     loop {
         let (stream, peer) = match listener.accept().await {
             Ok(v) => v,

src/network/probe.rs

@@ -280,6 +280,14 @@ fn detect_local_ip_v6() -> Option<Ipv6Addr> {
     }
 }
 
+pub fn detect_interface_ipv4() -> Option<Ipv4Addr> {
+    detect_local_ip_v4()
+}
+
+pub fn detect_interface_ipv6() -> Option<Ipv6Addr> {
+    detect_local_ip_v6()
+}
+
 pub fn is_bogon(ip: IpAddr) -> bool {
     match ip {
         IpAddr::V4(v4) => is_bogon_v4(v4),

src/proxy/client.rs

@@ -806,12 +806,8 @@ impl RunningClientHandler {
             });
         }
 
-        let mut ip_reserved = false;
-        // IP limit check
-        match ip_tracker.check_and_add(user, peer_addr.ip()).await {
-            Ok(()) => {
-                ip_reserved = true;
-            }
+        let ip_reserved = match ip_tracker.check_and_add(user, peer_addr.ip()).await {
+            Ok(()) => true,
             Err(reason) => {
                 warn!(
                     user = %user,
@@ -823,7 +819,8 @@ impl RunningClientHandler {
                     user: user.to_string(),
                 });
             }
-        }
+        };
+        // IP limit check
 
         if let Some(limit) = config.access.user_max_tcp_conns.get(user)
             && stats.get_user_curr_connects(user) >= *limit as u64

src/proxy/middle_relay.rs

@@ -382,7 +382,7 @@ where
 
                     let mut batch_frames = 0usize;
                     let mut batch_bytes = 0usize;
-                    let mut flush_immediately = false;
+                    let mut flush_immediately;
 
                     match process_me_writer_response(
                         first,

src/transport/middle_proxy/config_updater.rs

@@ -15,6 +15,7 @@ use crate::error::Result;
 use super::MePool;
 use super::rotation::{MeReinitTrigger, enqueue_reinit_trigger};
 use super::secret::download_proxy_secret_with_max_len;
+use super::selftest::record_timeskew_sample;
 use std::time::SystemTime;
 
 async fn retry_fetch(url: &str) -> Option<ProxyConfigData> {
@@ -109,6 +110,7 @@ pub async fn fetch_proxy_config_with_raw(url: &str) -> Result<(ProxyConfigData,
         })
     {
         let skew_secs = skew.as_secs();
+        record_timeskew_sample("proxy_config_date_header", skew_secs);
         if skew_secs > 60 {
             warn!(skew_secs, "Time skew >60s detected from fetch_proxy_config Date header");
         } else if skew_secs > 30 {

src/transport/middle_proxy/handshake.rs

@@ -33,6 +33,7 @@ use super::codec::{
     cbc_decrypt_inplace, cbc_encrypt_padded, parse_handshake_flags, parse_nonce_payload,
     read_rpc_frame_plaintext, rpc_crc,
 };
+use super::selftest::{BndAddrStatus, BndPortStatus, record_bnd_status};
 use super::wire::{extract_ip_material, IpMaterial};
 use super::MePool;
 
@@ -131,6 +132,14 @@ impl MePool {
         )
     }
 
+    fn bnd_port_status(bound: Option<SocketAddr>) -> BndPortStatus {
+        match bound {
+            Some(addr) if addr.port() == 0 => BndPortStatus::Zero,
+            Some(_) => BndPortStatus::Ok,
+            None => BndPortStatus::Error,
+        }
+    }
+
     /// TCP connect with timeout + return RTT in milliseconds.
     pub(crate) async fn connect_tcp(
         &self,
@@ -239,7 +248,27 @@ impl MePool {
             IpFamily::V6
         };
         let is_socks_route = Self::is_socks_route(upstream_egress);
+        let raw_socks_bound_addr = if is_socks_route {
+            upstream_egress.and_then(|info| info.socks_bound_addr)
+        } else {
+            None
+        };
         let socks_bound_addr = Self::select_socks_bound_addr(family, upstream_egress);
+        let bnd_addr_status = if !is_socks_route {
+            BndAddrStatus::Error
+        } else if raw_socks_bound_addr.is_some() && socks_bound_addr.is_none() {
+            BndAddrStatus::Bogon
+        } else if socks_bound_addr.is_some() {
+            BndAddrStatus::Ok
+        } else {
+            BndAddrStatus::Error
+        };
+        let bnd_port_status = if is_socks_route {
+            Self::bnd_port_status(raw_socks_bound_addr)
+        } else {
+            BndPortStatus::Error
+        };
+        record_bnd_status(bnd_addr_status, bnd_port_status, raw_socks_bound_addr);
         let reflected = if let Some(bound) = socks_bound_addr {
             Some(bound)
         } else if is_socks_route {

src/transport/middle_proxy/mod.rs

@@ -18,6 +18,7 @@ mod registry;
 mod rotation;
 mod send;
 mod secret;
+mod selftest;
 mod wire;
 mod pool_status;
 
@@ -37,6 +38,7 @@ pub use config_updater::{
     me_config_updater, save_proxy_config_cache,
 };
 pub use rotation::{MeReinitTrigger, me_reinit_scheduler, me_rotation_task};
+pub(crate) use selftest::{bnd_snapshot, timeskew_snapshot};
 pub use wire::proto_flags_for_tag;
 
 #[derive(Debug)]

src/transport/middle_proxy/secret.rs

@@ -3,6 +3,7 @@ use std::time::SystemTime;
 use httpdate;
 
 use crate::error::{ProxyError, Result};
+use super::selftest::record_timeskew_sample;
 
 pub const PROXY_SECRET_MIN_LEN: usize = 32;
 
@@ -98,6 +99,7 @@ pub async fn download_proxy_secret_with_max_len(max_len: usize) -> Result<Vec<u8
         })
     {
         let skew_secs = skew.as_secs();
+        record_timeskew_sample("proxy_secret_date_header", skew_secs);
         if skew_secs > 60 {
             warn!(skew_secs, "Time skew >60s detected from proxy-secret Date header");
         } else if skew_secs > 30 {

src/transport/middle_proxy/selftest.rs

@@ -0,0 +1,194 @@
+use std::collections::VecDeque;
+use std::net::SocketAddr;
+use std::sync::{Mutex, OnceLock};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum BndAddrStatus {
+    Ok,
+    Bogon,
+    Error,
+}
+
+impl BndAddrStatus {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Ok => "ok",
+            Self::Bogon => "bogon",
+            Self::Error => "error",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum BndPortStatus {
+    Ok,
+    Zero,
+    Error,
+}
+
+impl BndPortStatus {
+    pub(crate) fn as_str(self) -> &'static str {
+        match self {
+            Self::Ok => "ok",
+            Self::Zero => "zero",
+            Self::Error => "error",
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct MeBndSnapshot {
+    pub addr_status: &'static str,
+    pub port_status: &'static str,
+    pub last_addr: Option<SocketAddr>,
+    pub last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Clone, Debug, Default)]
+pub(crate) struct MeTimeskewSnapshot {
+    pub max_skew_secs_15m: Option<u64>,
+    pub samples_15m: usize,
+    pub last_skew_secs: Option<u64>,
+    pub last_source: Option<&'static str>,
+    pub last_seen_age_secs: Option<u64>,
+}
+
+#[derive(Clone, Copy, Debug)]
+struct MeTimeskewSample {
+    ts_epoch_secs: u64,
+    skew_secs: u64,
+    source: &'static str,
+}
+
+#[derive(Debug)]
+struct MeSelftestState {
+    bnd_addr_status: BndAddrStatus,
+    bnd_port_status: BndPortStatus,
+    bnd_last_addr: Option<SocketAddr>,
+    bnd_last_seen_epoch_secs: Option<u64>,
+    timeskew_samples: VecDeque<MeTimeskewSample>,
+}
+
+impl Default for MeSelftestState {
+    fn default() -> Self {
+        Self {
+            bnd_addr_status: BndAddrStatus::Error,
+            bnd_port_status: BndPortStatus::Error,
+            bnd_last_addr: None,
+            bnd_last_seen_epoch_secs: None,
+            timeskew_samples: VecDeque::new(),
+        }
+    }
+}
+
+const MAX_TIMESKEW_SAMPLES: usize = 512;
+const TIMESKEW_WINDOW_SECS: u64 = 15 * 60;
+
+static ME_SELFTEST_STATE: OnceLock<Mutex<MeSelftestState>> = OnceLock::new();
+
+fn state() -> &'static Mutex<MeSelftestState> {
+    ME_SELFTEST_STATE.get_or_init(|| Mutex::new(MeSelftestState::default()))
+}
+
+pub(crate) fn record_bnd_status(
+    addr_status: BndAddrStatus,
+    port_status: BndPortStatus,
+    last_addr: Option<SocketAddr>,
+) {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(mut guard) = state().lock() else {
+        return;
+    };
+    guard.bnd_addr_status = addr_status;
+    guard.bnd_port_status = port_status;
+    guard.bnd_last_addr = last_addr;
+    guard.bnd_last_seen_epoch_secs = Some(now_epoch_secs);
+}
+
+pub(crate) fn bnd_snapshot() -> MeBndSnapshot {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(guard) = state().lock() else {
+        return MeBndSnapshot {
+            addr_status: BndAddrStatus::Error.as_str(),
+            port_status: BndPortStatus::Error.as_str(),
+            last_addr: None,
+            last_seen_age_secs: None,
+        };
+    };
+    MeBndSnapshot {
+        addr_status: guard.bnd_addr_status.as_str(),
+        port_status: guard.bnd_port_status.as_str(),
+        last_addr: guard.bnd_last_addr,
+        last_seen_age_secs: guard
+            .bnd_last_seen_epoch_secs
+            .map(|value| now_epoch_secs.saturating_sub(value)),
+    }
+}
+
+pub(crate) fn record_timeskew_sample(source: &'static str, skew_secs: u64) {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(mut guard) = state().lock() else {
+        return;
+    };
+    guard.timeskew_samples.push_back(MeTimeskewSample {
+        ts_epoch_secs: now_epoch_secs,
+        skew_secs,
+        source,
+    });
+    while guard.timeskew_samples.len() > MAX_TIMESKEW_SAMPLES {
+        guard.timeskew_samples.pop_front();
+    }
+    let cutoff = now_epoch_secs.saturating_sub(TIMESKEW_WINDOW_SECS * 2);
+    while guard
+        .timeskew_samples
+        .front()
+        .is_some_and(|sample| sample.ts_epoch_secs < cutoff)
+    {
+        guard.timeskew_samples.pop_front();
+    }
+}
+
+pub(crate) fn timeskew_snapshot() -> MeTimeskewSnapshot {
+    let now_epoch_secs = now_epoch_secs();
+    let Ok(guard) = state().lock() else {
+        return MeTimeskewSnapshot::default();
+    };
+
+    let mut max_skew_secs_15m = None;
+    let mut samples_15m = 0usize;
+    let window_start = now_epoch_secs.saturating_sub(TIMESKEW_WINDOW_SECS);
+    for sample in &guard.timeskew_samples {
+        if sample.ts_epoch_secs < window_start {
+            continue;
+        }
+        samples_15m = samples_15m.saturating_add(1);
+        max_skew_secs_15m = Some(max_skew_secs_15m.unwrap_or(0).max(sample.skew_secs));
+    }
+
+    let (last_skew_secs, last_source, last_seen_age_secs) =
+        if let Some(last) = guard.timeskew_samples.back() {
+            (
+                Some(last.skew_secs),
+                Some(last.source),
+                Some(now_epoch_secs.saturating_sub(last.ts_epoch_secs)),
+            )
+        } else {
+            (None, None, None)
+        };
+
+    MeTimeskewSnapshot {
+        max_skew_secs_15m,
+        samples_15m,
+        last_skew_secs,
+        last_source,
+        last_seen_age_secs,
+    }
+}
+
+fn now_epoch_secs() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}