shelly_axum/

lib.rs

//! Axum adapter for Shelly LiveView.
//!
//! The adapter owns HTTP routing, initial page rendering, JavaScript asset
//! serving, and WebSocket transport. The core runtime remains in `shelly`.

use axum::{
    extract::{
        ws::{close_code, CloseFrame, Message, WebSocket},
        Path, State, WebSocketUpgrade,
    },
    http::{header, HeaderMap, Method, StatusCode, Uri},
    response::{Html as AxumHtml, IntoResponse, Response},
    routing::get,
    Json, Router,
};
use base64::{
    engine::general_purpose::{STANDARD, URL_SAFE_NO_PAD},
    Engine as _,
};
use futures_util::{SinkExt, StreamExt};
use hmac::{Hmac, Mac};
use serde::Serialize;
use serde_json::Value as JsonValue;
use sha2::Sha256;
use shelly::{
    ClientMessage, LiveSession, LiveView, PubSub, PubSubCommand, ResumeStatus, RuntimeCommand,
    ServerMessage, TelemetryEvent, TelemetryEventKind, TelemetrySink, INTERNAL_RENDER_FLUSH_EVENT,
};
use std::{
    collections::{BTreeMap, HashMap, HashSet},
    fs,
    path::PathBuf,
    sync::{Arc, Mutex as StdMutex},
    time::{SystemTime, UNIX_EPOCH},
};
use tokio::{
    io::AsyncWriteExt,
    sync::{mpsc, Mutex},
    task::JoinHandle,
    time::{sleep, timeout, Duration, Instant, MissedTickBehavior},
};
use tower_http::trace::TraceLayer;
use tracing::{debug, error, info, warn};
use tracing_subscriber::EnvFilter;
use uuid::Uuid;

const CLIENT_JS: &str = include_str!("../assets/shelly_liveview.js");
const DEFAULT_MAX_MESSAGE_SIZE: usize = 64 * 1024;
const DEFAULT_MAX_UPLOAD_SIZE: u64 = 5 * 1024 * 1024;
const PROTOCOL_VERSION: &str = "shelly/1";
const DEFAULT_RESUME_TTL_MS: u64 = 120_000;
const DEFAULT_CONNECT_HANDSHAKE_TIMEOUT_MS: u64 = 5_000;
const DEFAULT_RECONNECT_BASE_MS: u64 = 750;
const DEFAULT_RECONNECT_MAX_MS: u64 = 30_000;
const DEFAULT_RECONNECT_JITTER_MS: u64 = 250;
const DEFAULT_HEARTBEAT_INTERVAL_MS: u64 = 15_000;
const DEFAULT_HEARTBEAT_TIMEOUT_MS: u64 = 10_000;
const DEFAULT_DURABLE_LEASE_TTL_MS: u64 = 300_000;
const DEFAULT_DURABLE_JOURNAL_LIMIT: usize = 512;
const DEFAULT_OUTBOUND_QUEUE_CAPACITY: usize = 1024;
const DEFAULT_OUTBOUND_BATCH_MAX_MESSAGES: usize = 32;
const DEFAULT_OUTBOUND_BATCH_MAX_BYTES: usize = 64 * 1024;
const DEFAULT_OUTBOUND_BATCH_FLUSH_INTERVAL_MS: u64 = 2;
const DEFAULT_RENDER_CADENCE_MS: u64 = 0;
const DEFAULT_OVERLOAD_WINDOW_MS: u64 = 1_000;
const DEFAULT_SESSION_QUEUE_DEPTH_BUDGET: usize = 768;
const DEFAULT_SESSION_BYTES_PER_SEC_BUDGET: usize = 512 * 1024;
const DEFAULT_SESSION_CPU_MS_PER_SEC_BUDGET: u64 = 250;
const DEFAULT_TENANT_QUEUE_DEPTH_BUDGET: usize = 4_096;
const DEFAULT_TENANT_BYTES_PER_SEC_BUDGET: usize = 4 * 1024 * 1024;
const DEFAULT_TENANT_CPU_MS_PER_SEC_BUDGET: u64 = 1_500;
const DEFAULT_TENANT_QUOTA_WINDOW_MS: u64 = 60_000;
const DEFAULT_TENANT_SESSION_QUOTA_PER_WINDOW: usize = 1_024;
const DEFAULT_TENANT_EVENT_QUOTA_PER_WINDOW: usize = 250_000;
const DEFAULT_HTTP3_ALT_SVC: &str = r#"h3=":443"; ma=86400"#;

type HmacSha256 = Hmac<Sha256>;
type RateLimitHook = Arc<dyn Fn(&RateLimitContext) -> bool + Send + Sync>;
type AuthorizationHook = Arc<dyn Fn(&AuthorizationContext) -> AuthorizationDecision + Send + Sync>;
type QuotaPolicyHook = Arc<dyn Fn(&QuotaContext) -> QuotaDecision + Send + Sync>;
type OverloadPolicyHook =
    Arc<dyn Fn(&OverloadContext, &OverloadDecision) -> OverloadDecision + Send + Sync>;
type DurablePlacementHook =
    Arc<dyn Fn(&DurablePlacementContext) -> DurablePlacementDecision + Send + Sync>;

/// Factory for a fresh LiveView instance.
pub type LiveViewFactory = Arc<dyn Fn() -> Box<dyn LiveView> + Send + Sync>;

#[derive(Clone)]
struct AppState {
    routes: Arc<Vec<LiveRoute>>,
    target_id: String,
    max_message_size: usize,
    pubsub: PubSub,
    uploads: UploadConfig,
    security: SecurityConfig,
    telemetry: Arc<TelemetryPipeline>,
    reconnect: ReconnectConfig,
    distributed: DistributedConfig,
    durable: DurableRuntimeConfig,
    outbound: OutboundConfig,
    render: RenderConfig,
    overload: OverloadConfig,
    transport_http: HttpTransportConfig,
}

impl AppState {
    fn route_for(&self, path: &str) -> Option<MatchedRoute> {
        self.routes.iter().find_map(|route| route.match_path(path))
    }
}

impl TokenSigner {
    fn ephemeral() -> Self {
        let secret = format!("{}:{}", Uuid::new_v4(), Uuid::new_v4()).into_bytes();
        Self {
            secret: Arc::new(secret),
        }
    }

    fn new(secret: impl Into<Vec<u8>>) -> Self {
        Self {
            secret: Arc::new(secret.into()),
        }
    }

    fn sign_session(&self, session_id: &str, path: &str, node_id: &str) -> String {
        self.sign(&serde_json::json!({
            "kind": "session",
            "session_id": session_id,
            "path": path,
            "node_id": node_id,
        }))
    }

    fn verify_session(&self, token: &str) -> Option<SignedSession> {
        let payload = self.verify(token)?;
        if payload.get("kind")?.as_str()? != "session" {
            return None;
        }

        Some(SignedSession {
            session_id: payload.get("session_id")?.as_str()?.to_string(),
            path: payload.get("path")?.as_str()?.to_string(),
            node_id: payload
                .get("node_id")
                .and_then(serde_json::Value::as_str)
                .map(ToString::to_string),
        })
    }

    fn sign_resume(&self, session_id: &str, path: &str) -> String {
        self.sign(&serde_json::json!({
            "kind": "resume",
            "session_id": session_id,
            "path": path,
            "nonce": Uuid::new_v4().to_string(),
        }))
    }

    fn verify_resume(&self, token: &str) -> Option<SignedResume> {
        let payload = self.verify(token)?;
        if payload.get("kind")?.as_str()? != "resume" {
            return None;
        }

        Some(SignedResume {
            session_id: payload.get("session_id")?.as_str()?.to_string(),
            path: payload.get("path")?.as_str()?.to_string(),
            nonce: payload.get("nonce")?.as_str()?.to_string(),
        })
    }

    fn sign_csrf(&self, session_id: &str, path: &str) -> String {
        self.sign(&serde_json::json!({
            "kind": "csrf",
            "session_id": session_id,
            "path": path,
            "nonce": Uuid::new_v4().to_string(),
        }))
    }

    fn verify_csrf(&self, token: &str, session_id: &str, path: &str) -> bool {
        let Some(payload) = self.verify(token) else {
            return false;
        };

        payload.get("kind").and_then(serde_json::Value::as_str) == Some("csrf")
            && payload
                .get("session_id")
                .and_then(serde_json::Value::as_str)
                == Some(session_id)
            && payload.get("path").and_then(serde_json::Value::as_str) == Some(path)
            && payload
                .get("nonce")
                .and_then(serde_json::Value::as_str)
                .is_some()
    }

    fn sign(&self, payload: &serde_json::Value) -> String {
        let payload = serde_json::to_vec(payload).expect("token payload should serialize");
        let signature = self.mac(&payload);
        format!(
            "{}.{}",
            URL_SAFE_NO_PAD.encode(payload),
            URL_SAFE_NO_PAD.encode(signature)
        )
    }

    fn verify(&self, token: &str) -> Option<serde_json::Value> {
        let (payload, signature) = token.split_once('.')?;
        let payload = URL_SAFE_NO_PAD.decode(payload).ok()?;
        let signature = URL_SAFE_NO_PAD.decode(signature).ok()?;
        let mut mac = HmacSha256::new_from_slice(self.secret.as_slice()).ok()?;
        mac.update(&payload);
        mac.verify_slice(&signature).ok()?;
        serde_json::from_slice(&payload).ok()
    }

    fn mac(&self, payload: &[u8]) -> Vec<u8> {
        let mut mac = HmacSha256::new_from_slice(self.secret.as_slice())
            .expect("HMAC accepts arbitrary key lengths");
        mac.update(payload);
        mac.finalize().into_bytes().to_vec()
    }
}

/// Builder for an Axum-backed Shelly application.
pub struct ShellyRouter {
    routes: Vec<LiveRoute>,
    target_id: String,
    max_message_size: usize,
    pubsub: PubSub,
    uploads: UploadConfig,
    security: SecurityConfig,
    telemetry: Arc<TelemetryPipeline>,
    reconnect: ReconnectConfig,
    distributed: DistributedConfig,
    durable: DurableRuntimeConfig,
    outbound: OutboundConfig,
    render: RenderConfig,
    overload: OverloadConfig,
    transport_http: HttpTransportConfig,
}

#[derive(Clone)]
struct LiveRoute {
    pattern: String,
    segments: Vec<RouteSegment>,
    factory: LiveViewFactory,
}

#[derive(Debug, Clone, PartialEq, Eq)]
enum RouteSegment {
    Static(String),
    Param(String),
}

#[derive(Clone)]
struct MatchedRoute {
    pattern: String,
    path: String,
    params: BTreeMap<String, String>,
    factory: LiveViewFactory,
}

#[derive(Clone)]
struct SocketConfig {
    routes: Arc<Vec<LiveRoute>>,
    target_id: String,
    route_path: String,
    signed_session_id: String,
    max_message_size: usize,
    pubsub: PubSub,
    uploads: UploadConfig,
    security: SecurityConfig,
    telemetry: Arc<TelemetryPipeline>,
    correlation: CorrelationContext,
    reconnect: ReconnectConfig,
    distributed: DistributedConfig,
    durable: DurableRuntimeConfig,
    outbound: OutboundConfig,
    render: RenderConfig,
    overload: OverloadConfig,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionAffinityMode {
    Disabled,
    Required,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionAffinityContext {
    pub session_id: String,
    pub route_path: String,
    pub current_node_id: String,
    pub token_node_id: Option<String>,
}

/// Overflow handling policy for bounded outbound websocket queues.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum OutboundOverflowPolicy {
    /// Close the websocket when outbound queue is full.
    #[default]
    Disconnect,
    /// Drop the newest outbound message when queue is full.
    DropNewest,
}

/// Durable runtime takeover policy when another node currently owns a session lease.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
pub enum DurableTakeoverPolicy {
    /// Reject acquisition while another unexpired owner exists.
    Deny,
    /// Allow takeover only after the existing lease expires.
    #[default]
    AllowExpired,
    /// Force ownership transfer immediately, even if lease has not expired.
    Force,
}

/// Placement context for durable ownership acquisition decisions.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DurablePlacementContext {
    pub session_id: String,
    pub route_path: String,
    pub current_node_id: String,
    pub preferred_node_id: Option<String>,
}

/// Placement hook response for durable ownership acquisition.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DurablePlacementDecision {
    pub allowed: bool,
    pub code: Option<String>,
    pub message: Option<String>,
}

impl DurablePlacementDecision {
    pub fn allow() -> Self {
        Self {
            allowed: true,
            code: None,
            message: None,
        }
    }

    pub fn deny(code: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            allowed: false,
            code: Some(code.into()),
            message: Some(message.into()),
        }
    }
}

/// Durable store error from lease/snapshot/journal operations.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DurableStoreError {
    pub code: String,
    pub message: String,
}

impl DurableStoreError {
    fn new(code: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            code: code.into(),
            message: message.into(),
        }
    }
}

/// Durable lease acquisition request.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct DurableLeaseRequest {
    pub session_id: String,
    pub node_id: String,
    pub ttl_ms: u64,
    pub takeover_policy: DurableTakeoverPolicy,
}

/// Result of a successful durable lease acquisition/renewal.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct DurableLeaseGrant {
    pub fence_token: u64,
    pub owner_node_id: String,
    pub transferred_from: Option<String>,
    pub expires_at_unix_ms: u64,
}

/// Durable session snapshot persisted for failover recovery.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct DurableSessionSnapshot {
    pub route_path: String,
    pub route_pattern: String,
    pub target_id: String,
    pub revision: u64,
    pub resume_token: String,
    pub owner_node_id: String,
    pub updated_at_unix_ms: u64,
}

/// Durable journal entry for replaying state transitions after failover.
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct DurableJournalEntry {
    pub sequence: u64,
    pub message: ClientMessage,
    pub recorded_at_unix_ms: u64,
}

/// Durable record loaded from one store backend.
#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
pub struct DurableSessionRecord {
    pub snapshot: DurableSessionSnapshot,
    pub journal: Vec<DurableJournalEntry>,
}

/// Durable store abstraction for session ownership + recovery state.
pub trait DurableSessionStore: Send + Sync {
    fn acquire_lease(
        &self,
        request: DurableLeaseRequest,
    ) -> Result<DurableLeaseGrant, DurableStoreError>;
    fn renew_lease(
        &self,
        session_id: &str,
        node_id: &str,
        fence_token: u64,
        ttl_ms: u64,
    ) -> Result<DurableLeaseGrant, DurableStoreError>;
    fn release_lease(&self, session_id: &str, node_id: &str, fence_token: u64);
    fn load_record(&self, session_id: &str) -> Option<DurableSessionRecord>;
    fn save_snapshot(&self, session_id: &str, snapshot: DurableSessionSnapshot);
    fn append_journal_entry(
        &self,
        session_id: &str,
        node_id: &str,
        fence_token: u64,
        message: ClientMessage,
        max_journal: usize,
    ) -> Result<DurableJournalEntry, DurableStoreError>;
    fn set_node_draining(&self, node_id: &str, draining: bool);
    fn is_node_draining(&self, node_id: &str) -> bool;
}

#[derive(Default, Clone)]
pub struct InMemoryDurableSessionStore {
    inner: Arc<StdMutex<InMemoryDurableSessionStoreState>>,
}

#[derive(Default)]
struct InMemoryDurableSessionStoreState {
    sessions: HashMap<String, InMemoryDurableSessionEntry>,
    draining_nodes: HashSet<String>,
}

#[derive(Clone)]
struct InMemoryDurableSessionEntry {
    lease: Option<InMemoryDurableLease>,
    snapshot: Option<DurableSessionSnapshot>,
    journal: Vec<DurableJournalEntry>,
    next_sequence: u64,
}

#[derive(Clone)]
struct InMemoryDurableLease {
    owner_node_id: String,
    fence_token: u64,
    expires_at_unix_ms: u64,
}

impl InMemoryDurableSessionStore {
    pub fn new() -> Self {
        Self::default()
    }
}

impl DurableSessionStore for InMemoryDurableSessionStore {
    fn acquire_lease(
        &self,
        request: DurableLeaseRequest,
    ) -> Result<DurableLeaseGrant, DurableStoreError> {
        let mut state = self.inner.lock().map_err(|_| {
            DurableStoreError::new("durable_store_poisoned", "durable store mutex poisoned")
        })?;

        if state.draining_nodes.contains(&request.node_id) {
            return Err(DurableStoreError::new(
                "node_draining",
                format!(
                    "node {} is draining and cannot acquire durable session ownership",
                    request.node_id
                ),
            ));
        }

        let now = now_unix_ms();
        let entry = state
            .sessions
            .entry(request.session_id.clone())
            .or_insert_with(|| InMemoryDurableSessionEntry {
                lease: None,
                snapshot: None,
                journal: Vec::new(),
                next_sequence: 1,
            });

        let mut transferred_from = None;
        let mut next_fence = entry
            .lease
            .as_ref()
            .map(|lease| lease.fence_token + 1)
            .unwrap_or(1);

        if let Some(existing) = entry.lease.as_ref() {
            let is_owner = existing.owner_node_id == request.node_id;
            let is_expired = existing.expires_at_unix_ms <= now;
            if !is_owner && !is_expired && request.takeover_policy != DurableTakeoverPolicy::Force {
                return Err(DurableStoreError::new(
                    "lease_conflict",
                    format!(
                        "durable lease is owned by node {} until {}",
                        existing.owner_node_id, existing.expires_at_unix_ms
                    ),
                ));
            }
            if !is_owner {
                transferred_from = Some(existing.owner_node_id.clone());
            } else {
                next_fence = existing.fence_token;
            }
        }

        let expires_at_unix_ms = now + request.ttl_ms.max(1_000);
        entry.lease = Some(InMemoryDurableLease {
            owner_node_id: request.node_id.clone(),
            fence_token: next_fence,
            expires_at_unix_ms,
        });

        Ok(DurableLeaseGrant {
            fence_token: next_fence,
            owner_node_id: request.node_id,
            transferred_from,
            expires_at_unix_ms,
        })
    }

    fn renew_lease(
        &self,
        session_id: &str,
        node_id: &str,
        fence_token: u64,
        ttl_ms: u64,
    ) -> Result<DurableLeaseGrant, DurableStoreError> {
        let mut state = self.inner.lock().map_err(|_| {
            DurableStoreError::new("durable_store_poisoned", "durable store mutex poisoned")
        })?;
        let entry = state
            .sessions
            .get_mut(session_id)
            .ok_or_else(|| DurableStoreError::new("lease_not_found", "durable lease not found"))?;
        let lease = entry
            .lease
            .as_mut()
            .ok_or_else(|| DurableStoreError::new("lease_not_found", "durable lease not found"))?;
        if lease.owner_node_id != node_id || lease.fence_token != fence_token {
            return Err(DurableStoreError::new(
                "lease_not_owner",
                "cannot renew durable lease from non-owner node",
            ));
        }
        lease.expires_at_unix_ms = now_unix_ms() + ttl_ms.max(1_000);
        Ok(DurableLeaseGrant {
            fence_token: lease.fence_token,
            owner_node_id: lease.owner_node_id.clone(),
            transferred_from: None,
            expires_at_unix_ms: lease.expires_at_unix_ms,
        })
    }

    fn release_lease(&self, session_id: &str, node_id: &str, fence_token: u64) {
        let Ok(mut state) = self.inner.lock() else {
            return;
        };
        let Some(entry) = state.sessions.get_mut(session_id) else {
            return;
        };
        let should_release = entry
            .lease
            .as_ref()
            .map(|lease| lease.owner_node_id == node_id && lease.fence_token == fence_token)
            .unwrap_or(false);
        if should_release {
            entry.lease = None;
        }
    }

    fn load_record(&self, session_id: &str) -> Option<DurableSessionRecord> {
        let Ok(state) = self.inner.lock() else {
            return None;
        };
        let entry = state.sessions.get(session_id)?;
        let snapshot = entry.snapshot.clone()?;
        Some(DurableSessionRecord {
            snapshot,
            journal: entry.journal.clone(),
        })
    }

    fn save_snapshot(&self, session_id: &str, snapshot: DurableSessionSnapshot) {
        let Ok(mut state) = self.inner.lock() else {
            return;
        };
        let entry = state
            .sessions
            .entry(session_id.to_string())
            .or_insert_with(|| InMemoryDurableSessionEntry {
                lease: None,
                snapshot: None,
                journal: Vec::new(),
                next_sequence: 1,
            });
        entry.snapshot = Some(snapshot);
    }

    fn append_journal_entry(
        &self,
        session_id: &str,
        node_id: &str,
        fence_token: u64,
        message: ClientMessage,
        max_journal: usize,
    ) -> Result<DurableJournalEntry, DurableStoreError> {
        let mut state = self.inner.lock().map_err(|_| {
            DurableStoreError::new("durable_store_poisoned", "durable store mutex poisoned")
        })?;
        let entry = state
            .sessions
            .entry(session_id.to_string())
            .or_insert_with(|| InMemoryDurableSessionEntry {
                lease: None,
                snapshot: None,
                journal: Vec::new(),
                next_sequence: 1,
            });
        let lease = entry
            .lease
            .as_ref()
            .ok_or_else(|| DurableStoreError::new("lease_not_found", "durable lease not found"))?;
        if lease.owner_node_id != node_id || lease.fence_token != fence_token {
            return Err(DurableStoreError::new(
                "lease_not_owner",
                "cannot append durable journal from non-owner node",
            ));
        }

        let journal_entry = DurableJournalEntry {
            sequence: entry.next_sequence,
            message,
            recorded_at_unix_ms: now_unix_ms(),
        };
        entry.next_sequence += 1;
        entry.journal.push(journal_entry.clone());
        let max_journal = max_journal.max(1);
        if entry.journal.len() > max_journal {
            let trim_count = entry.journal.len() - max_journal;
            entry.journal.drain(0..trim_count);
        }
        Ok(journal_entry)
    }

    fn set_node_draining(&self, node_id: &str, draining: bool) {
        let Ok(mut state) = self.inner.lock() else {
            return;
        };
        if draining {
            state.draining_nodes.insert(node_id.to_string());
        } else {
            state.draining_nodes.remove(node_id);
        }
    }

    fn is_node_draining(&self, node_id: &str) -> bool {
        let Ok(state) = self.inner.lock() else {
            return false;
        };
        state.draining_nodes.contains(node_id)
    }
}

/// Durable store that persists lease/snapshot/journal state to local files.
///
/// This backend is suitable for single-host durable recovery and conformance
/// testing. Multi-node distributed deployments should still use a shared
/// backend implementation.
#[derive(Clone)]
pub struct FileDurableSessionStore {
    root_dir: Arc<PathBuf>,
    lock: Arc<StdMutex<()>>,
    draining_nodes: Arc<StdMutex<HashSet<String>>>,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
struct FileDurableSessionRecord {
    lease: Option<FileDurableLease>,
    snapshot: Option<DurableSessionSnapshot>,
    journal: Vec<DurableJournalEntry>,
    next_sequence: u64,
}

impl Default for FileDurableSessionRecord {
    fn default() -> Self {
        Self {
            lease: None,
            snapshot: None,
            journal: Vec::new(),
            next_sequence: 1,
        }
    }
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
struct FileDurableLease {
    owner_node_id: String,
    fence_token: u64,
    expires_at_unix_ms: u64,
}

impl FileDurableSessionStore {
    pub fn new(root_dir: impl Into<PathBuf>) -> Self {
        Self {
            root_dir: Arc::new(root_dir.into()),
            lock: Arc::new(StdMutex::new(())),
            draining_nodes: Arc::new(StdMutex::new(HashSet::new())),
        }
    }

    fn sessions_dir(&self) -> PathBuf {
        self.root_dir.join("sessions")
    }

    fn session_path(&self, session_id: &str) -> PathBuf {
        let encoded = URL_SAFE_NO_PAD.encode(session_id.as_bytes());
        self.sessions_dir().join(format!("{encoded}.json"))
    }

    fn ensure_sessions_dir(&self) -> Result<(), DurableStoreError> {
        fs::create_dir_all(self.sessions_dir()).map_err(|error| {
            DurableStoreError::new(
                "durable_store_io",
                format!("failed to create durable sessions dir: {error}"),
            )
        })
    }

    fn lock_guard(&self) -> Result<std::sync::MutexGuard<'_, ()>, DurableStoreError> {
        self.lock.lock().map_err(|_| {
            DurableStoreError::new("durable_store_poisoned", "durable store mutex poisoned")
        })
    }

    fn read_record_locked(
        &self,
        session_id: &str,
    ) -> Result<Option<FileDurableSessionRecord>, DurableStoreError> {
        let path = self.session_path(session_id);
        if !path.exists() {
            return Ok(None);
        }
        let raw = fs::read_to_string(&path).map_err(|error| {
            DurableStoreError::new(
                "durable_store_io",
                format!("failed to read durable record for session {session_id}: {error}"),
            )
        })?;
        let record = serde_json::from_str::<FileDurableSessionRecord>(&raw).map_err(|error| {
            DurableStoreError::new(
                "durable_store_corrupt",
                format!("failed to decode durable record for session {session_id}: {error}"),
            )
        })?;
        Ok(Some(record))
    }

    fn read_or_default_locked(
        &self,
        session_id: &str,
    ) -> Result<FileDurableSessionRecord, DurableStoreError> {
        Ok(self.read_record_locked(session_id)?.unwrap_or_default())
    }

    fn write_record_locked(
        &self,
        session_id: &str,
        record: &FileDurableSessionRecord,
    ) -> Result<(), DurableStoreError> {
        self.ensure_sessions_dir()?;
        let path = self.session_path(session_id);
        let temp_path = path.with_extension("json.tmp");
        let encoded = serde_json::to_string(record).map_err(|error| {
            DurableStoreError::new(
                "durable_store_encode",
                format!("failed to encode durable record for session {session_id}: {error}"),
            )
        })?;
        fs::write(&temp_path, encoded).map_err(|error| {
            DurableStoreError::new(
                "durable_store_io",
                format!(
                    "failed to write durable record temp file for session {session_id}: {error}"
                ),
            )
        })?;
        fs::rename(&temp_path, &path).map_err(|error| {
            DurableStoreError::new(
                "durable_store_io",
                format!("failed to persist durable record for session {session_id}: {error}"),
            )
        })?;
        Ok(())
    }
}

impl DurableSessionStore for FileDurableSessionStore {
    fn acquire_lease(
        &self,
        request: DurableLeaseRequest,
    ) -> Result<DurableLeaseGrant, DurableStoreError> {
        let _guard = self.lock_guard()?;
        if self.is_node_draining(&request.node_id) {
            return Err(DurableStoreError::new(
                "node_draining",
                format!(
                    "node {} is draining and cannot acquire durable session ownership",
                    request.node_id
                ),
            ));
        }

        let mut record = self.read_or_default_locked(&request.session_id)?;
        let now = now_unix_ms();
        let mut transferred_from = None;
        let mut next_fence = record
            .lease
            .as_ref()
            .map(|lease| lease.fence_token + 1)
            .unwrap_or(1);

        if let Some(existing) = record.lease.as_ref() {
            let is_owner = existing.owner_node_id == request.node_id;
            let is_expired = existing.expires_at_unix_ms <= now;
            if !is_owner && !is_expired && request.takeover_policy != DurableTakeoverPolicy::Force {
                return Err(DurableStoreError::new(
                    "lease_conflict",
                    format!(
                        "durable lease is owned by node {} until {}",
                        existing.owner_node_id, existing.expires_at_unix_ms
                    ),
                ));
            }
            if !is_owner {
                transferred_from = Some(existing.owner_node_id.clone());
            } else {
                next_fence = existing.fence_token;
            }
        }

        let expires_at_unix_ms = now + request.ttl_ms.max(1_000);
        record.lease = Some(FileDurableLease {
            owner_node_id: request.node_id.clone(),
            fence_token: next_fence,
            expires_at_unix_ms,
        });
        self.write_record_locked(&request.session_id, &record)?;

        Ok(DurableLeaseGrant {
            fence_token: next_fence,
            owner_node_id: request.node_id,
            transferred_from,
            expires_at_unix_ms,
        })
    }

    fn renew_lease(
        &self,
        session_id: &str,
        node_id: &str,
        fence_token: u64,
        ttl_ms: u64,
    ) -> Result<DurableLeaseGrant, DurableStoreError> {
        let _guard = self.lock_guard()?;
        let mut record = self
            .read_record_locked(session_id)?
            .ok_or_else(|| DurableStoreError::new("lease_not_found", "durable lease not found"))?;
        let lease = record
            .lease
            .as_mut()
            .ok_or_else(|| DurableStoreError::new("lease_not_found", "durable lease not found"))?;
        if lease.owner_node_id != node_id || lease.fence_token != fence_token {
            return Err(DurableStoreError::new(
                "lease_not_owner",
                "cannot renew durable lease from non-owner node",
            ));
        }
        lease.expires_at_unix_ms = now_unix_ms() + ttl_ms.max(1_000);
        let grant = DurableLeaseGrant {
            fence_token: lease.fence_token,
            owner_node_id: lease.owner_node_id.clone(),
            transferred_from: None,
            expires_at_unix_ms: lease.expires_at_unix_ms,
        };
        self.write_record_locked(session_id, &record)?;
        Ok(grant)
    }

    fn release_lease(&self, session_id: &str, node_id: &str, fence_token: u64) {
        let Ok(_guard) = self.lock_guard() else {
            return;
        };
        let Ok(Some(mut record)) = self.read_record_locked(session_id) else {
            return;
        };
        let should_release = record
            .lease
            .as_ref()
            .map(|lease| lease.owner_node_id == node_id && lease.fence_token == fence_token)
            .unwrap_or(false);
        if !should_release {
            return;
        }
        record.lease = None;
        if let Err(error) = self.write_record_locked(session_id, &record) {
            warn!(
                session_id,
                code = error.code,
                message = error.message,
                "failed to persist durable lease release"
            );
        }
    }

    fn load_record(&self, session_id: &str) -> Option<DurableSessionRecord> {
        let _guard = match self.lock_guard() {
            Ok(guard) => guard,
            Err(error) => {
                warn!(
                    session_id,
                    code = error.code,
                    message = error.message,
                    "failed to lock durable file store"
                );
                return None;
            }
        };
        let record = match self.read_record_locked(session_id) {
            Ok(record) => record,
            Err(error) => {
                warn!(
                    session_id,
                    code = error.code,
                    message = error.message,
                    "failed to load durable record"
                );
                return None;
            }
        };
        let record = record?;
        let snapshot = record.snapshot?;
        Some(DurableSessionRecord {
            snapshot,
            journal: record.journal,
        })
    }

    fn save_snapshot(&self, session_id: &str, snapshot: DurableSessionSnapshot) {
        let Ok(_guard) = self.lock_guard() else {
            return;
        };
        let mut record = match self.read_or_default_locked(session_id) {
            Ok(record) => record,
            Err(error) => {
                warn!(
                    session_id,
                    code = error.code,
                    message = error.message,
                    "failed to load durable record before snapshot save"
                );
                return;
            }
        };
        record.snapshot = Some(snapshot);
        if let Err(error) = self.write_record_locked(session_id, &record) {
            warn!(
                session_id,
                code = error.code,
                message = error.message,
                "failed to persist durable snapshot"
            );
        }
    }

    fn append_journal_entry(
        &self,
        session_id: &str,
        node_id: &str,
        fence_token: u64,
        message: ClientMessage,
        max_journal: usize,
    ) -> Result<DurableJournalEntry, DurableStoreError> {
        let _guard = self.lock_guard()?;
        let mut record = self.read_or_default_locked(session_id)?;
        let lease = record
            .lease
            .as_ref()
            .ok_or_else(|| DurableStoreError::new("lease_not_found", "durable lease not found"))?;
        if lease.owner_node_id != node_id || lease.fence_token != fence_token {
            return Err(DurableStoreError::new(
                "lease_not_owner",
                "cannot append durable journal from non-owner node",
            ));
        }

        let journal_entry = DurableJournalEntry {
            sequence: record.next_sequence,
            message,
            recorded_at_unix_ms: now_unix_ms(),
        };
        record.next_sequence += 1;
        record.journal.push(journal_entry.clone());
        let max_journal = max_journal.max(1);
        if record.journal.len() > max_journal {
            let trim_count = record.journal.len() - max_journal;
            record.journal.drain(0..trim_count);
        }
        self.write_record_locked(session_id, &record)?;
        Ok(journal_entry)
    }

    fn set_node_draining(&self, node_id: &str, draining: bool) {
        let Ok(mut draining_nodes) = self.draining_nodes.lock() else {
            return;
        };
        if draining {
            draining_nodes.insert(node_id.to_string());
        } else {
            draining_nodes.remove(node_id);
        }
    }

    fn is_node_draining(&self, node_id: &str) -> bool {
        let Ok(draining_nodes) = self.draining_nodes.lock() else {
            return false;
        };
        draining_nodes.contains(node_id)
    }
}

#[derive(Clone)]
struct DistributedConfig {
    node_id: String,
    session_affinity: SessionAffinityMode,
}

impl Default for DistributedConfig {
    fn default() -> Self {
        Self {
            node_id: format!("node-{}", Uuid::new_v4()),
            session_affinity: SessionAffinityMode::Disabled,
        }
    }
}

/// Runtime transport profile advertised to browser clients.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransportMode {
    /// WebSocket primary transport.
    WebSocket,
    /// Server-Sent Events fallback profile for server-to-client delivery.
    ServerSentEvents,
    /// HTTP long-poll fallback profile for heavily restricted networks.
    LongPoll,
}

impl TransportMode {
    fn as_str(self) -> &'static str {
        match self {
            Self::WebSocket => "websocket",
            Self::ServerSentEvents => "sse",
            Self::LongPoll => "long_poll",
        }
    }
}

#[derive(Debug, Clone)]
struct HttpTransportConfig {
    http3_alt_svc: Option<String>,
    emit_diagnostics_header: bool,
    primary_mode: TransportMode,
    fallback_modes: Vec<TransportMode>,
    progressive_enhancement: bool,
}

impl Default for HttpTransportConfig {
    fn default() -> Self {
        Self {
            http3_alt_svc: None,
            emit_diagnostics_header: false,
            primary_mode: TransportMode::WebSocket,
            fallback_modes: Vec::new(),
            progressive_enhancement: true,
        }
    }
}

impl HttpTransportConfig {
    fn fallback_names(&self) -> Vec<&'static str> {
        self.fallback_modes
            .iter()
            .copied()
            .map(TransportMode::as_str)
            .collect()
    }

    fn fallback_json(&self) -> String {
        serde_json::to_string(&self.fallback_names()).expect("transport modes serialize")
    }

    fn diagnostics_header(&self) -> String {
        let h3 = if self.http3_alt_svc.is_some() {
            "advertised"
        } else {
            "disabled"
        };
        let fallback = if self.fallback_modes.is_empty() {
            "none".to_string()
        } else {
            self.fallback_names().join(",")
        };
        let progressive = if self.progressive_enhancement {
            "enabled"
        } else {
            "disabled"
        };
        format!(
            "{}; fallback={fallback}; progressive={progressive}; h3={h3}",
            self.primary_mode.as_str()
        )
    }
}

#[derive(Debug, Serialize)]
struct TransportCapabilities {
    protocol: &'static str,
    primary: &'static str,
    fallbacks: Vec<&'static str>,
    progressive_enhancement: bool,
    http3_advertised: bool,
}

#[derive(Debug, Clone)]
struct ClientRuntimeConfig {
    reconnect_base_ms: u64,
    reconnect_max_ms: u64,
    reconnect_jitter_ms: u64,
    heartbeat_interval_ms: u64,
    heartbeat_timeout_ms: u64,
}

impl Default for ClientRuntimeConfig {
    fn default() -> Self {
        Self {
            reconnect_base_ms: DEFAULT_RECONNECT_BASE_MS,
            reconnect_max_ms: DEFAULT_RECONNECT_MAX_MS,
            reconnect_jitter_ms: DEFAULT_RECONNECT_JITTER_MS,
            heartbeat_interval_ms: DEFAULT_HEARTBEAT_INTERVAL_MS,
            heartbeat_timeout_ms: DEFAULT_HEARTBEAT_TIMEOUT_MS,
        }
    }
}

#[derive(Clone)]
struct ReconnectConfig {
    resume_ttl: Duration,
    connect_handshake_timeout: Duration,
    client: ClientRuntimeConfig,
    snapshots: Arc<Mutex<HashMap<String, ResumeSnapshot>>>,
}

impl Default for ReconnectConfig {
    fn default() -> Self {
        Self {
            resume_ttl: Duration::from_millis(DEFAULT_RESUME_TTL_MS),
            connect_handshake_timeout: Duration::from_millis(DEFAULT_CONNECT_HANDSHAKE_TIMEOUT_MS),
            client: ClientRuntimeConfig::default(),
            snapshots: Arc::new(Mutex::new(HashMap::new())),
        }
    }
}

#[derive(Clone)]
struct DurableRuntimeConfig {
    store: Option<Arc<dyn DurableSessionStore>>,
    lease_ttl: Duration,
    journal_limit: usize,
    takeover_policy: DurableTakeoverPolicy,
    drain_mode: bool,
    placement_hook: Option<DurablePlacementHook>,
}

impl Default for DurableRuntimeConfig {
    fn default() -> Self {
        Self {
            store: None,
            lease_ttl: Duration::from_millis(DEFAULT_DURABLE_LEASE_TTL_MS),
            journal_limit: DEFAULT_DURABLE_JOURNAL_LIMIT,
            takeover_policy: DurableTakeoverPolicy::default(),
            drain_mode: false,
            placement_hook: None,
        }
    }
}

#[derive(Debug, Clone)]
struct OutboundConfig {
    queue_capacity: usize,
    batch_max_messages: usize,
    batch_max_bytes: usize,
    batch_flush_interval: Duration,
    overflow_policy: OutboundOverflowPolicy,
}

impl Default for OutboundConfig {
    fn default() -> Self {
        Self {
            queue_capacity: DEFAULT_OUTBOUND_QUEUE_CAPACITY,
            batch_max_messages: DEFAULT_OUTBOUND_BATCH_MAX_MESSAGES,
            batch_max_bytes: DEFAULT_OUTBOUND_BATCH_MAX_BYTES,
            batch_flush_interval: Duration::from_millis(DEFAULT_OUTBOUND_BATCH_FLUSH_INTERVAL_MS),
            overflow_policy: OutboundOverflowPolicy::default(),
        }
    }
}

#[derive(Debug, Clone)]
struct RenderConfig {
    default_cadence_ms: u64,
}

impl Default for RenderConfig {
    fn default() -> Self {
        Self {
            default_cadence_ms: DEFAULT_RENDER_CADENCE_MS,
        }
    }
}

struct ResumeSnapshot {
    session: LiveSession,
    route_pattern: String,
    resume_token: String,
    expires_at: Instant,
}

struct ConnectHandshake {
    client_session_id: Option<String>,
    client_revision: u64,
    resume_token: Option<String>,
    tenant_id: Option<String>,
    trace_id: Option<String>,
    span_id: Option<String>,
    parent_span_id: Option<String>,
    correlation_id: Option<String>,
    request_id: Option<String>,
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
struct CorrelationContext {
    trace_id: String,
    span_id: String,
    parent_span_id: Option<String>,
    correlation_id: Option<String>,
    request_id: Option<String>,
}

impl CorrelationContext {
    fn with_new_span(&self) -> Self {
        let mut next = self.clone();
        next.parent_span_id = Some(self.span_id.clone());
        next.span_id = generate_span_id();
        next
    }

    fn apply_to_event(&self, event: TelemetryEvent) -> TelemetryEvent {
        let mut enriched = event
            .with_trace_id(self.trace_id.clone())
            .with_span_id(self.span_id.clone());
        if let Some(parent_span_id) = &self.parent_span_id {
            enriched = enriched.with_parent_span_id(parent_span_id.clone());
        }
        if let Some(correlation_id) = &self.correlation_id {
            enriched = enriched.with_correlation_id(correlation_id.clone());
        }
        if let Some(request_id) = &self.request_id {
            enriched = enriched.with_request_id(request_id.clone());
        }
        enriched
    }
}

#[derive(Clone)]
struct UploadConfig {
    max_file_size: u64,
    allowed_content_types: Arc<Vec<String>>,
    temp_dir: Arc<PathBuf>,
}

impl Default for UploadConfig {
    fn default() -> Self {
        Self {
            max_file_size: DEFAULT_MAX_UPLOAD_SIZE,
            allowed_content_types: Arc::new(Vec::new()),
            temp_dir: Arc::new(std::env::temp_dir().join("shelly-liveview-uploads")),
        }
    }
}

struct UploadEntry {
    event: String,
    target: Option<String>,
    name: String,
    size: u64,
    content_type: Option<String>,
    path: PathBuf,
    file: tokio::fs::File,
    received: u64,
}

struct TextDispatch<'a> {
    current_route_pattern: &'a mut String,
    routes: &'a [LiveRoute],
    target_id: &'a str,
    session_id: &'a str,
    upload_config: &'a UploadConfig,
    uploads: &'a mut HashMap<String, UploadEntry>,
    telemetry: &'a Arc<dyn TelemetrySink>,
}

struct UploadStartRequest {
    upload_id: String,
    event: String,
    target: Option<String>,
    name: String,
    size: u64,
    content_type: Option<String>,
}

impl LiveRoute {
    fn new(pattern: String, factory: LiveViewFactory) -> Self {
        let segments = route_segments(&pattern);
        Self {
            pattern,
            segments,
            factory,
        }
    }

    fn match_path(&self, path: &str) -> Option<MatchedRoute> {
        let path_segments = path_segments(path);
        if self.segments.len() != path_segments.len() {
            return None;
        }

        let mut params = BTreeMap::new();
        for (pattern, actual) in self.segments.iter().zip(path_segments) {
            match pattern {
                RouteSegment::Static(expected) if expected == actual => {}
                RouteSegment::Static(_) => return None,
                RouteSegment::Param(name) => {
                    params.insert(name.clone(), actual.to_string());
                }
            }
        }

        Some(MatchedRoute {
            pattern: self.pattern.clone(),
            path: path.to_string(),
            params,
            factory: self.factory.clone(),
        })
    }
}

/// Context passed to the optional transport-level rate limiter hook.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RateLimitContext {
    pub route_path: String,
    pub session_id: String,
    pub message_kind: &'static str,
}

/// Message operation surfaced to security policy hooks.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SecurityOperation {
    Connect,
    Event,
    PatchUrl,
    Navigate,
    UploadStart,
    UploadChunk,
    UploadComplete,
    Ping,
    Binary,
}

impl SecurityOperation {
    fn as_str(self) -> &'static str {
        match self {
            Self::Connect => "connect",
            Self::Event => "event",
            Self::PatchUrl => "patch_url",
            Self::Navigate => "navigate",
            Self::UploadStart => "upload_start",
            Self::UploadChunk => "upload_chunk",
            Self::UploadComplete => "upload_complete",
            Self::Ping => "ping",
            Self::Binary => "binary",
        }
    }

    fn is_mutating(self) -> bool {
        matches!(
            self,
            Self::Event
                | Self::PatchUrl
                | Self::Navigate
                | Self::UploadStart
                | Self::UploadChunk
                | Self::UploadComplete
        )
    }
}

/// Context passed to optional authorization hooks.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AuthorizationContext {
    pub route_path: String,
    pub session_id: String,
    pub tenant_id: Option<String>,
    pub message_kind: &'static str,
    pub operation: SecurityOperation,
    pub event_name: Option<String>,
    pub event_target: Option<String>,
}

/// Authorization hook response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AuthorizationDecision {
    pub allowed: bool,
    pub code: Option<String>,
    pub message: Option<String>,
}

impl AuthorizationDecision {
    pub fn allow() -> Self {
        Self {
            allowed: true,
            code: None,
            message: None,
        }
    }

    pub fn deny(code: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            allowed: false,
            code: Some(code.into()),
            message: Some(message.into()),
        }
    }
}

/// Context passed to optional quota policy hooks.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct QuotaContext {
    pub route_path: String,
    pub session_id: String,
    pub tenant_id: Option<String>,
    pub message_kind: &'static str,
    pub operation: SecurityOperation,
    pub event_name: Option<String>,
}

/// Quota policy hook response.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct QuotaDecision {
    pub allowed: bool,
    pub code: Option<String>,
    pub message: Option<String>,
}

impl QuotaDecision {
    pub fn allow() -> Self {
        Self {
            allowed: true,
            code: None,
            message: None,
        }
    }

    pub fn deny(code: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            allowed: false,
            code: Some(code.into()),
            message: Some(message.into()),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TenantQuotaBudgets {
    pub max_sessions_per_window: usize,
    pub max_events_per_window: usize,
    pub require_tenant_id: bool,
}

impl Default for TenantQuotaBudgets {
    fn default() -> Self {
        Self {
            max_sessions_per_window: DEFAULT_TENANT_SESSION_QUOTA_PER_WINDOW,
            max_events_per_window: DEFAULT_TENANT_EVENT_QUOTA_PER_WINDOW,
            require_tenant_id: true,
        }
    }
}

#[derive(Debug, Clone)]
struct TenantQuotaWindow {
    started_at: Instant,
    sessions: HashSet<String>,
    events: usize,
}

impl TenantQuotaWindow {
    fn new(now: Instant) -> Self {
        Self {
            started_at: now,
            sessions: HashSet::new(),
            events: 0,
        }
    }

    fn roll_if_needed(&mut self, now: Instant, window: Duration) {
        if now.duration_since(self.started_at) >= window {
            *self = Self::new(now);
        }
    }
}

#[derive(Debug, Default, Clone)]
struct TenantQuotaState {
    windows: HashMap<String, TenantQuotaWindow>,
}

#[derive(Clone)]
pub struct TenantQuotaPolicy {
    budgets: TenantQuotaBudgets,
    window: Duration,
    state: Arc<StdMutex<TenantQuotaState>>,
}

impl TenantQuotaPolicy {
    pub fn new() -> Self {
        Self {
            budgets: TenantQuotaBudgets::default(),
            window: Duration::from_millis(DEFAULT_TENANT_QUOTA_WINDOW_MS),
            state: Arc::new(StdMutex::new(TenantQuotaState::default())),
        }
    }

    pub fn with_budgets(mut self, budgets: TenantQuotaBudgets) -> Self {
        self.budgets = budgets;
        self
    }

    pub fn with_window_ms(mut self, window_ms: u64) -> Self {
        self.window = Duration::from_millis(window_ms.max(1));
        self
    }

    pub fn evaluate(&self, context: &QuotaContext) -> QuotaDecision {
        let tenant_id = normalize_tenant_id_ref(context.tenant_id.as_deref());
        if self.budgets.require_tenant_id && tenant_id.is_none() {
            return QuotaDecision::deny(
                "tenant_context_required",
                "tenant_id is required for quota policy evaluation",
            );
        }
        let Some(tenant_id) = tenant_id else {
            return QuotaDecision::allow();
        };

        let now = Instant::now();
        let Ok(mut state) = self.state.lock() else {
            return QuotaDecision::deny(
                "tenant_quota_unavailable",
                "tenant quota state is unavailable",
            );
        };
        let window = state
            .windows
            .entry(tenant_id)
            .or_insert_with(|| TenantQuotaWindow::new(now));
        window.roll_if_needed(now, self.window);

        if matches!(context.operation, SecurityOperation::Connect) {
            let is_new_session = window.sessions.insert(context.session_id.clone());
            if is_new_session && window.sessions.len() > self.budgets.max_sessions_per_window.max(1)
            {
                return QuotaDecision::deny(
                    "tenant_session_quota_exceeded",
                    "tenant session quota exceeded",
                );
            }
            return QuotaDecision::allow();
        }

        if context.operation.is_mutating() {
            let next_events = window.events.saturating_add(1);
            if next_events > self.budgets.max_events_per_window.max(1) {
                return QuotaDecision::deny(
                    "tenant_event_quota_exceeded",
                    "tenant event quota exceeded",
                );
            }
            window.events = next_events;
        }

        QuotaDecision::allow()
    }
}

impl Default for TenantQuotaPolicy {
    fn default() -> Self {
        Self::new()
    }
}

/// Priority class used by overload scheduler decisions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OverloadPriority {
    Interactive,
    Background,
}

impl OverloadPriority {
    fn as_str(self) -> &'static str {
        match self {
            Self::Interactive => "interactive",
            Self::Background => "background",
        }
    }
}

/// Overload shed strategy for saturated runtime paths.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum OverloadShedPolicy {
    /// Shed background traffic first and preserve interactive traffic where possible.
    #[default]
    PreferInteractive,
    /// Apply strict shedding to all traffic classes once saturated.
    Strict,
}

/// Budget configuration for adaptive overload control.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OverloadBudgets {
    pub session_queue_depth: usize,
    pub session_bytes_per_sec: usize,
    pub session_cpu_ms_per_sec: u64,
    pub tenant_queue_depth: usize,
    pub tenant_bytes_per_sec: usize,
    pub tenant_cpu_ms_per_sec: u64,
}

impl Default for OverloadBudgets {
    fn default() -> Self {
        Self {
            session_queue_depth: DEFAULT_SESSION_QUEUE_DEPTH_BUDGET,
            session_bytes_per_sec: DEFAULT_SESSION_BYTES_PER_SEC_BUDGET,
            session_cpu_ms_per_sec: DEFAULT_SESSION_CPU_MS_PER_SEC_BUDGET,
            tenant_queue_depth: DEFAULT_TENANT_QUEUE_DEPTH_BUDGET,
            tenant_bytes_per_sec: DEFAULT_TENANT_BYTES_PER_SEC_BUDGET,
            tenant_cpu_ms_per_sec: DEFAULT_TENANT_CPU_MS_PER_SEC_BUDGET,
        }
    }
}

/// Context passed to optional overload policy hooks.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OverloadContext {
    pub route_path: String,
    pub session_id: String,
    pub tenant_id: Option<String>,
    pub message_kind: &'static str,
    pub operation: SecurityOperation,
    pub event_name: Option<String>,
    pub priority: OverloadPriority,
    pub queue_depth: usize,
    pub queue_capacity: usize,
    pub inbound_bytes: usize,
}

/// Overload policy decision.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OverloadDecision {
    pub allowed: bool,
    pub throttle_ms: u64,
    pub code: Option<String>,
    pub message: Option<String>,
    pub reason: Option<String>,
}

impl OverloadDecision {
    pub fn allow() -> Self {
        Self {
            allowed: true,
            throttle_ms: 0,
            code: None,
            message: None,
            reason: None,
        }
    }

    pub fn throttle(ms: u64, reason: impl Into<String>) -> Self {
        Self {
            allowed: true,
            throttle_ms: ms,
            code: Some("overload_throttle".to_string()),
            message: Some("overload throttling applied".to_string()),
            reason: Some(reason.into()),
        }
    }

    pub fn shed(reason: impl Into<String>) -> Self {
        Self {
            allowed: false,
            throttle_ms: 0,
            code: Some("overload_shed".to_string()),
            message: Some("server overloaded; request shed by policy".to_string()),
            reason: Some(reason.into()),
        }
    }
}

#[derive(Debug, Clone)]
struct OverloadBudgetWindow {
    started_at: Instant,
    events: usize,
    bytes: usize,
    cpu_ms: u64,
    queue_depth_peak: usize,
}

impl OverloadBudgetWindow {
    fn new(now: Instant) -> Self {
        Self {
            started_at: now,
            events: 0,
            bytes: 0,
            cpu_ms: 0,
            queue_depth_peak: 0,
        }
    }

    fn roll_window_if_needed(&mut self, now: Instant, window: Duration) {
        if now.duration_since(self.started_at) >= window {
            *self = Self::new(now);
        }
    }
}

#[derive(Debug, Default)]
struct OverloadState {
    session_windows: HashMap<String, OverloadBudgetWindow>,
    tenant_windows: HashMap<String, OverloadBudgetWindow>,
}

#[derive(Clone)]
struct OverloadConfig {
    budgets: OverloadBudgets,
    shed_policy: OverloadShedPolicy,
    policy_hook: Option<OverloadPolicyHook>,
    window: Duration,
    state: Arc<Mutex<OverloadState>>,
}

impl Default for OverloadConfig {
    fn default() -> Self {
        Self {
            budgets: OverloadBudgets::default(),
            shed_policy: OverloadShedPolicy::default(),
            policy_hook: None,
            window: Duration::from_millis(DEFAULT_OVERLOAD_WINDOW_MS),
            state: Arc::new(Mutex::new(OverloadState::default())),
        }
    }
}

#[derive(Clone)]
struct SecurityConfig {
    signer: TokenSigner,
    allowed_origins: Arc<Vec<String>>,
    rate_limiter: Option<RateLimitHook>,
    authorization: Option<AuthorizationHook>,
    quota_policy: Option<QuotaPolicyHook>,
}

impl Default for SecurityConfig {
    fn default() -> Self {
        Self {
            signer: TokenSigner::ephemeral(),
            allowed_origins: Arc::new(Vec::new()),
            rate_limiter: None,
            authorization: None,
            quota_policy: None,
        }
    }
}

/// Console log formatting mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConsoleLogFormat {
    /// Newline-delimited JSON logs for cloud ingestion.
    Json,
    /// Human-readable local development logs.
    Pretty,
}

impl ConsoleLogFormat {
    fn parse(raw: &str) -> Self {
        match raw.trim().to_ascii_lowercase().as_str() {
            "pretty" | "text" | "plain" => Self::Pretty,
            _ => Self::Json,
        }
    }

    fn as_str(self) -> &'static str {
        match self {
            Self::Json => "json",
            Self::Pretty => "pretty",
        }
    }
}

/// Initialize a standardized Shelly tracing subscriber for console logs.
///
/// Environment variables:
/// - `RUST_LOG` controls filter directives.
/// - `SHELLY_LOG_FORMAT` controls output format (`json` default, `pretty` optional).
/// - `SHELLY_ENV` adds environment context to startup logs.
pub fn init_console_logging(service_name: impl AsRef<str>) -> Result<(), String> {
    let format = std::env::var("SHELLY_LOG_FORMAT")
        .map(|raw| ConsoleLogFormat::parse(&raw))
        .unwrap_or(ConsoleLogFormat::Json);
    let log_filter =
        std::env::var("RUST_LOG").unwrap_or_else(|_| "shelly_axum=info,info".to_string());
    let env_name = std::env::var("SHELLY_ENV").unwrap_or_else(|_| "development".to_string());
    let env_filter = EnvFilter::new(log_filter);

    match format {
        ConsoleLogFormat::Json => tracing_subscriber::fmt()
            .with_env_filter(env_filter)
            .with_target(true)
            .json()
            .flatten_event(true)
            .try_init(),
        ConsoleLogFormat::Pretty => tracing_subscriber::fmt()
            .with_env_filter(env_filter)
            .with_target(true)
            .pretty()
            .try_init(),
    }
    .map_err(|err| format!("failed to initialize Shelly logging subscriber: {err}"))?;

    info!(
        target: "shelly.startup",
        service = %service_name.as_ref(),
        environment = %env_name,
        log_format = %format.as_str(),
        "Shelly logging initialized"
    );
    Ok(())
}

/// Export mode for Shelly telemetry events.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TelemetryExporter {
    /// Emit telemetry through structured tracing logs.
    Tracing,
    /// Emit telemetry as OpenTelemetry-compatible JSON log records.
    OpenTelemetryJson,
    /// Emit telemetry as Axiom-ready JSON logs.
    AxiomJson {
        dataset: String,
        org_id: Option<String>,
    },
}

/// Telemetry configuration for the Axum adapter.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TelemetryConfig {
    pub service_name: String,
    pub exporter: TelemetryExporter,
}

impl TelemetryConfig {
    pub fn tracing(service_name: impl Into<String>) -> Self {
        Self {
            service_name: service_name.into(),
            exporter: TelemetryExporter::Tracing,
        }
    }

    pub fn otel_json(service_name: impl Into<String>) -> Self {
        Self {
            service_name: service_name.into(),
            exporter: TelemetryExporter::OpenTelemetryJson,
        }
    }

    pub fn axiom_json(
        service_name: impl Into<String>,
        dataset: impl Into<String>,
        org_id: Option<String>,
    ) -> Self {
        Self {
            service_name: service_name.into(),
            exporter: TelemetryExporter::AxiomJson {
                dataset: dataset.into(),
                org_id,
            },
        }
    }
}

#[derive(Clone)]
struct TelemetryPipeline {
    config: Option<TelemetryConfig>,
}

impl TelemetryPipeline {
    fn disabled() -> Self {
        Self { config: None }
    }

    fn enabled(config: TelemetryConfig) -> Self {
        Self {
            config: Some(config),
        }
    }
}

impl TelemetrySink for TelemetryPipeline {
    fn emit(&self, event: TelemetryEvent) -> Result<(), String> {
        let Some(config) = &self.config else {
            return Ok(());
        };
        let attributes = redacted_attributes(&event.attributes);

        match &config.exporter {
            TelemetryExporter::Tracing => {
                tracing::info!(
                    target: "shelly.telemetry",
                    schema = "shelly.telemetry.v1",
                    service = %config.service_name,
                    kind = ?event.kind,
                    trace_id = event.trace_id.as_deref().unwrap_or("-"),
                    span_id = event.span_id.as_deref().unwrap_or("-"),
                    parent_span_id = event.parent_span_id.as_deref().unwrap_or("-"),
                    correlation_id = event.correlation_id.as_deref().unwrap_or("-"),
                    request_id = event.request_id.as_deref().unwrap_or("-"),
                    session_id = event.session_id.as_deref().unwrap_or("-"),
                    route_path = event.route_path.as_deref().unwrap_or("-"),
                    event_name = event.event_name.as_deref().unwrap_or("-"),
                    ok = event.ok,
                    latency_ms = event.latency_ms.unwrap_or(0),
                    bytes = event.bytes.unwrap_or(0),
                    count = event.count.unwrap_or(0),
                    attributes = ?attributes,
                    "shelly telemetry event"
                );
            }
            TelemetryExporter::OpenTelemetryJson => {
                let payload = serde_json::json!({
                    "schema": "shelly.telemetry.v1",
                    "resource": {
                        "service.name": config.service_name,
                    },
                    "otel_log": {
                        "severity_text": "INFO",
                        "body": "shelly telemetry event",
                        "trace_id": event.trace_id,
                        "span_id": event.span_id,
                        "attributes": {
                            "event.kind": event.kind,
                            "event.session_id": event.session_id,
                            "event.route_path": event.route_path,
                            "event.event_name": event.event_name,
                            "event.ok": event.ok,
                            "event.latency_ms": event.latency_ms,
                            "event.bytes": event.bytes,
                            "event.count": event.count,
                            "event.parent_span_id": event.parent_span_id,
                            "event.correlation_id": event.correlation_id,
                            "event.request_id": event.request_id,
                            "event.attributes": attributes,
                        }
                    }
                });
                tracing::info!(target: "shelly.telemetry.otel", payload = %payload);
            }
            TelemetryExporter::AxiomJson { dataset, org_id } => {
                let payload = serde_json::json!({
                    "schema": "shelly.telemetry.v1",
                    "_time": chrono_like_timestamp(),
                    "dataset": dataset,
                    "org_id": org_id,
                    "service": config.service_name,
                    "event": {
                        "kind": event.kind,
                        "trace_id": event.trace_id,
                        "span_id": event.span_id,
                        "parent_span_id": event.parent_span_id,
                        "correlation_id": event.correlation_id,
                        "request_id": event.request_id,
                        "session_id": event.session_id,
                        "route_path": event.route_path,
                        "event_name": event.event_name,
                        "ok": event.ok,
                        "latency_ms": event.latency_ms,
                        "bytes": event.bytes,
                        "count": event.count,
                        "attributes": attributes,
                    },
                });
                tracing::info!(target: "shelly.telemetry.axiom", payload = %payload);
            }
        }

        Ok(())
    }
}

#[derive(Clone)]
struct SessionTelemetrySink {
    inner: Arc<TelemetryPipeline>,
    correlation: CorrelationContext,
}

impl SessionTelemetrySink {
    fn new(inner: Arc<TelemetryPipeline>, correlation: CorrelationContext) -> Self {
        Self { inner, correlation }
    }
}

impl TelemetrySink for SessionTelemetrySink {
    fn emit(&self, event: TelemetryEvent) -> Result<(), String> {
        self.inner.emit(self.correlation.apply_to_event(event))
    }
}

#[derive(Clone)]
struct TokenSigner {
    secret: Arc<Vec<u8>>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct SignedSession {
    session_id: String,
    path: String,
    node_id: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct SignedResume {
    session_id: String,
    path: String,
    nonce: String,
}

struct ShellConfig<'a> {
    target_id: &'a str,
    inner_html: &'a str,
    path: &'a str,
    title: &'a str,
    session_id: &'a str,
    session_token: &'a str,
    csrf_token: &'a str,
    protocol: &'a str,
    trace_id: &'a str,
    span_id: &'a str,
    correlation_id: Option<&'a str>,
    request_id: Option<&'a str>,
    reconnect_base_ms: u64,
    reconnect_max_ms: u64,
    reconnect_jitter_ms: u64,
    heartbeat_interval_ms: u64,
    heartbeat_timeout_ms: u64,
    transport_mode: &'a str,
    transport_fallbacks: &'a str,
    progressive_enhancement: bool,
}

impl Default for ShellyRouter {
    fn default() -> Self {
        Self::new()
    }
}

impl ShellyRouter {
    /// Create an empty Shelly router.
    pub fn new() -> Self {
        Self {
            routes: Vec::new(),
            target_id: "shelly-root".to_string(),
            max_message_size: DEFAULT_MAX_MESSAGE_SIZE,
            pubsub: PubSub::default(),
            uploads: UploadConfig::default(),
            security: SecurityConfig::default(),
            telemetry: Arc::new(TelemetryPipeline::disabled()),
            reconnect: ReconnectConfig::default(),
            distributed: DistributedConfig::default(),
            durable: DurableRuntimeConfig::default(),
            outbound: OutboundConfig::default(),
            render: RenderConfig::default(),
            overload: OverloadConfig::default(),
            transport_http: HttpTransportConfig::default(),
        }
    }

    /// Override the root DOM id that receives patches.
    pub fn with_target_id(mut self, target_id: impl Into<String>) -> Self {
        self.target_id = target_id.into();
        self
    }

    /// Override the maximum accepted WebSocket payload size in bytes.
    pub fn with_max_message_size(mut self, max_message_size: usize) -> Self {
        self.max_message_size = max_message_size;
        self
    }

    /// Override the in-process PubSub backend.
    pub fn with_pubsub(mut self, pubsub: PubSub) -> Self {
        self.pubsub = pubsub;
        self
    }

    /// Override the maximum accepted upload size in bytes.
    pub fn with_max_upload_size(mut self, max_file_size: u64) -> Self {
        self.uploads.max_file_size = max_file_size;
        self
    }

    /// Allow one exact upload content type. Empty allow-list accepts any type.
    pub fn with_allowed_upload_content_type(mut self, content_type: impl Into<String>) -> Self {
        let mut allowed = (*self.uploads.allowed_content_types).clone();
        allowed.push(content_type.into());
        self.uploads.allowed_content_types = Arc::new(allowed);
        self
    }

    /// Override the directory used for temporary upload files.
    pub fn with_upload_temp_dir(mut self, temp_dir: impl Into<PathBuf>) -> Self {
        self.uploads.temp_dir = Arc::new(temp_dir.into());
        self
    }

    /// Override the secret used to sign session and CSRF tokens.
    pub fn with_secret(mut self, secret: impl Into<Vec<u8>>) -> Self {
        self.security.signer = TokenSigner::new(secret);
        self
    }

    /// Allow an additional exact WebSocket Origin value.
    ///
    /// Same-origin requests are accepted by default.
    pub fn with_allowed_origin(mut self, origin: impl Into<String>) -> Self {
        let mut origins = (*self.security.allowed_origins).clone();
        origins.push(origin.into());
        self.security.allowed_origins = Arc::new(origins);
        self
    }

    /// Register a transport-level rate limiter hook.
    ///
    /// Return `true` to allow the message, or `false` to reject it with a
    /// structured `rate_limited` protocol error.
    pub fn with_rate_limiter<F>(mut self, rate_limiter: F) -> Self
    where
        F: Fn(&RateLimitContext) -> bool + Send + Sync + 'static,
    {
        self.security.rate_limiter = Some(Arc::new(rate_limiter));
        self
    }

    /// Register a message-level authorization hook for WebSocket traffic.
    ///
    /// Return `AuthorizationDecision::allow()` to accept a client operation.
    /// Return `AuthorizationDecision::deny(...)` to reject it with a structured
    /// protocol error.
    pub fn with_authorization_hook<F>(mut self, authorization: F) -> Self
    where
        F: Fn(&AuthorizationContext) -> AuthorizationDecision + Send + Sync + 'static,
    {
        self.security.authorization = Some(Arc::new(authorization));
        self
    }

    /// Register a quota policy hook for route/session/event scoped limits.
    ///
    /// Return `QuotaDecision::allow()` to accept a client operation.
    /// Return `QuotaDecision::deny(...)` to reject it with a structured
    /// protocol error.
    pub fn with_quota_policy<F>(mut self, quota_policy: F) -> Self
    where
        F: Fn(&QuotaContext) -> QuotaDecision + Send + Sync + 'static,
    {
        self.security.quota_policy = Some(Arc::new(quota_policy));
        self
    }

    /// Register an in-memory tenant quota policy for connect/event enforcement.
    pub fn with_tenant_quota_policy(mut self, tenant_quota_policy: TenantQuotaPolicy) -> Self {
        self.security
            .quota_policy
            .replace(Arc::new(move |ctx| tenant_quota_policy.evaluate(ctx)));
        self
    }

    /// Enable first-class telemetry emission for runtime and transport events.
    pub fn with_telemetry(mut self, config: TelemetryConfig) -> Self {
        self.telemetry = Arc::new(TelemetryPipeline::enabled(config));
        self
    }

    /// Configure browser reconnect backoff tuning (in milliseconds).
    pub fn with_reconnect_backoff(mut self, base_ms: u64, max_ms: u64, jitter_ms: u64) -> Self {
        self.reconnect.client.reconnect_base_ms = base_ms.max(100);
        self.reconnect.client.reconnect_max_ms =
            max_ms.max(self.reconnect.client.reconnect_base_ms);
        self.reconnect.client.reconnect_jitter_ms = jitter_ms;
        self
    }

    /// Configure browser heartbeat intervals (in milliseconds).
    pub fn with_heartbeat(mut self, interval_ms: u64, timeout_ms: u64) -> Self {
        self.reconnect.client.heartbeat_interval_ms = interval_ms.max(1_000);
        self.reconnect.client.heartbeat_timeout_ms = timeout_ms.max(1_000);
        self
    }

    /// Configure resumable session snapshot retention (in milliseconds).
    pub fn with_resume_ttl_ms(mut self, ttl_ms: u64) -> Self {
        self.reconnect.resume_ttl = Duration::from_millis(ttl_ms.max(1_000));
        self
    }

    /// Configure the timeout for receiving the initial `connect` handshake.
    pub fn with_connect_handshake_timeout_ms(mut self, timeout_ms: u64) -> Self {
        self.reconnect.connect_handshake_timeout = Duration::from_millis(timeout_ms.max(500));
        self
    }

    /// Advertise HTTP/3 availability to capable clients via `Alt-Svc`.
    ///
    /// Set an empty string to clear any existing value.
    pub fn with_http3_alt_svc(mut self, alt_svc: impl Into<String>) -> Self {
        let alt_svc = alt_svc.into();
        let alt_svc = alt_svc.trim();
        self.transport_http.http3_alt_svc = if alt_svc.is_empty() {
            None
        } else {
            Some(alt_svc.to_string())
        };
        self
    }

    /// Apply the default HTTP/3 `Alt-Svc` profile (`h3=":443"; ma=86400`).
    pub fn with_http3_default_alt_svc(mut self) -> Self {
        self.transport_http.http3_alt_svc = Some(DEFAULT_HTTP3_ALT_SVC.to_string());
        self
    }

    /// Emit a diagnostics response header describing transport mode.
    pub fn with_transport_diagnostics_header(mut self, enabled: bool) -> Self {
        self.transport_http.emit_diagnostics_header = enabled;
        self
    }

    /// Configure the advertised transport compatibility profile.
    ///
    /// WebSocket remains the authoritative protocol transport. Fallback modes
    /// advertise supported degraded profiles so clients and proxies can reason
    /// about capability downgrade without application-specific branching.
    pub fn with_transport_modes(
        mut self,
        primary: TransportMode,
        fallback_modes: impl IntoIterator<Item = TransportMode>,
    ) -> Self {
        let mut fallbacks = Vec::new();
        for mode in fallback_modes {
            if mode != primary && !fallbacks.contains(&mode) {
                fallbacks.push(mode);
            }
        }
        self.transport_http.primary_mode = primary;
        self.transport_http.fallback_modes = fallbacks;
        self
    }

    /// Enable the standard progressive fallback profile (`SSE`, then long poll).
    pub fn with_progressive_transport_fallbacks(mut self) -> Self {
        self.transport_http.fallback_modes =
            vec![TransportMode::ServerSentEvents, TransportMode::LongPoll];
        self.transport_http.progressive_enhancement = true;
        self
    }

    /// Enable or disable browser progressive-enhancement behavior.
    pub fn with_progressive_enhancement(mut self, enabled: bool) -> Self {
        self.transport_http.progressive_enhancement = enabled;
        self
    }

    /// Set a stable node id for clustered runtime deployments.
    pub fn with_node_id(mut self, node_id: impl Into<String>) -> Self {
        self.distributed.node_id = node_id.into();
        self
    }

    /// Configure session-affinity policy for WebSocket upgrades.
    pub fn with_session_affinity_mode(mut self, mode: SessionAffinityMode) -> Self {
        self.distributed.session_affinity = mode;
        self
    }

    /// Enable durable session runtime using a pluggable store backend.
    pub fn with_durable_session_store(mut self, store: Arc<dyn DurableSessionStore>) -> Self {
        self.durable.store = Some(store);
        self
    }

    /// Configure durable lease TTL in milliseconds.
    pub fn with_durable_lease_ttl_ms(mut self, ttl_ms: u64) -> Self {
        self.durable.lease_ttl = Duration::from_millis(ttl_ms.max(1_000));
        self
    }

    /// Configure maximum durable journal entries retained per session.
    pub fn with_durable_journal_limit(mut self, max_entries: usize) -> Self {
        self.durable.journal_limit = max_entries.max(1);
        self
    }

    /// Configure durable takeover policy for competing session owners.
    pub fn with_durable_takeover_policy(mut self, policy: DurableTakeoverPolicy) -> Self {
        self.durable.takeover_policy = policy;
        self
    }

    /// Mark this node as draining for durable ownership acquisition.
    ///
    /// Draining nodes reject new durable lease acquisition attempts.
    pub fn with_durable_drain_mode(mut self, draining: bool) -> Self {
        self.durable.drain_mode = draining;
        self
    }

    /// Register a placement policy hook for durable ownership acquisition.
    pub fn with_durable_placement_hook<F>(mut self, placement_hook: F) -> Self
    where
        F: Fn(&DurablePlacementContext) -> DurablePlacementDecision + Send + Sync + 'static,
    {
        self.durable.placement_hook = Some(Arc::new(placement_hook));
        self
    }

    /// Configure bounded outbound queue capacity for one websocket session.
    pub fn with_outbound_queue_capacity(mut self, queue_capacity: usize) -> Self {
        self.outbound.queue_capacity = queue_capacity.max(1);
        self
    }

    /// Configure outbound frame batching behavior.
    pub fn with_outbound_batching(
        mut self,
        batch_max_messages: usize,
        batch_max_bytes: usize,
        flush_interval_ms: u64,
    ) -> Self {
        self.outbound.batch_max_messages = batch_max_messages.max(1);
        self.outbound.batch_max_bytes = batch_max_bytes.max(256);
        self.outbound.batch_flush_interval = Duration::from_millis(flush_interval_ms.max(1));
        self
    }

    /// Configure overflow policy for bounded outbound websocket queues.
    pub fn with_outbound_overflow_policy(mut self, policy: OutboundOverflowPolicy) -> Self {
        self.outbound.overflow_policy = policy;
        self
    }

    /// Configure default root-render cadence in milliseconds for all sessions.
    ///
    /// Use `0` to keep immediate render behavior. Views can override at runtime
    /// via `Context::set_render_cadence_ms`.
    pub fn with_default_render_cadence_ms(mut self, cadence_ms: u64) -> Self {
        self.render.default_cadence_ms = cadence_ms;
        self
    }

    /// Configure overload control budgets for per-session and per-tenant limits.
    pub fn with_overload_budgets(mut self, budgets: OverloadBudgets) -> Self {
        self.overload.budgets = budgets;
        self
    }

    /// Configure overload shed policy for interactive/background traffic classes.
    pub fn with_overload_shed_policy(mut self, policy: OverloadShedPolicy) -> Self {
        self.overload.shed_policy = policy;
        self
    }

    /// Register a runtime overload policy hook for app/operator overrides.
    pub fn with_overload_policy_hook<F>(mut self, policy_hook: F) -> Self
    where
        F: Fn(&OverloadContext, &OverloadDecision) -> OverloadDecision + Send + Sync + 'static,
    {
        self.overload.policy_hook = Some(Arc::new(policy_hook));
        self
    }

    /// Register one LiveView route.
    pub fn live<V, F>(mut self, path: impl Into<String>, factory: F) -> Self
    where
        V: LiveView,
        F: Fn() -> V + Send + Sync + 'static,
    {
        let factory: LiveViewFactory = Arc::new(move || Box::new(factory()) as Box<dyn LiveView>);
        let pattern = normalize_path(path.into());
        self.routes.push(LiveRoute::new(pattern, factory));
        self
    }

    /// Convert the Shelly router into an Axum router.
    pub fn into_router(self) -> Router {
        if let Some(store) = self.durable.store.as_ref() {
            store.set_node_draining(&self.distributed.node_id, self.durable.drain_mode);
        }
        let state = Arc::new(AppState {
            routes: Arc::new(self.routes),
            target_id: self.target_id,
            max_message_size: self.max_message_size,
            pubsub: self.pubsub,
            uploads: self.uploads,
            security: self.security,
            telemetry: self.telemetry,
            reconnect: self.reconnect,
            distributed: self.distributed,
            durable: self.durable,
            outbound: self.outbound,
            render: self.render,
            overload: self.overload,
            transport_http: self.transport_http,
        });

        Router::new()
            .route("/__shelly/client.js", get(client_js))
            .route("/__shelly/transport", get(transport_capabilities))
            .route("/__shelly/ws/{*view_path}", get(ws_handler))
            .fallback(get(initial_handler))
            .layer(TraceLayer::new_for_http())
            .with_state(state)
    }
}

fn normalize_path(path: String) -> String {
    if path.is_empty() {
        return "/".to_string();
    }

    if path.starts_with('/') {
        path
    } else {
        format!("/{path}")
    }
}

fn route_segments(path: &str) -> Vec<RouteSegment> {
    path.trim_matches('/')
        .split('/')
        .filter(|segment| !segment.is_empty())
        .map(|segment| {
            if let Some(name) = segment.strip_prefix(':') {
                RouteSegment::Param(name.to_string())
            } else {
                RouteSegment::Static(segment.to_string())
            }
        })
        .collect()
}

fn path_segments(path: &str) -> Vec<&str> {
    path.trim_matches('/')
        .split('/')
        .filter(|segment| !segment.is_empty())
        .collect()
}

fn log_http_ingress(
    endpoint: &'static str,
    method: &Method,
    uri: &Uri,
    headers: &HeaderMap,
) -> CorrelationContext {
    let correlation = correlation_from_headers(headers);
    let user_agent = headers
        .get(header::USER_AGENT)
        .and_then(|value| value.to_str().ok())
        .unwrap_or("-");
    let origin = headers
        .get(header::ORIGIN)
        .and_then(|value| value.to_str().ok())
        .unwrap_or("-");
    let host = headers
        .get(header::HOST)
        .and_then(|value| value.to_str().ok())
        .unwrap_or("-");
    info!(
        target: "shelly.incoming.http",
        schema = "shelly.incoming.http.v1",
        endpoint,
        method = %method,
        path = uri.path(),
        query = sanitize_query_for_log(uri.query()),
        trace_id = %correlation.trace_id,
        span_id = %correlation.span_id,
        parent_span_id = correlation.parent_span_id.as_deref().unwrap_or("-"),
        correlation_id = correlation.correlation_id.as_deref().unwrap_or("-"),
        request_id = correlation.request_id.as_deref().unwrap_or("-"),
        user_agent,
        origin,
        host,
        "Shelly HTTP request received"
    );
    correlation
}

fn correlation_from_headers(headers: &HeaderMap) -> CorrelationContext {
    let request_id = header_value(headers, "x-request-id");
    let correlation_id = header_value(headers, "x-correlation-id").or_else(|| request_id.clone());
    let explicit_trace_id = header_value(headers, "x-trace-id")
        .and_then(|value| normalize_hex_id(&value, 32))
        .or_else(|| {
            header_value(headers, "trace-id").and_then(|value| normalize_hex_id(&value, 32))
        });
    let (trace_from_parent, parent_span_id) = headers
        .get("traceparent")
        .and_then(|value| value.to_str().ok())
        .and_then(parse_traceparent)
        .unwrap_or((String::new(), String::new()));

    let trace_id = if let Some(value) = explicit_trace_id {
        value
    } else if !trace_from_parent.is_empty() {
        trace_from_parent
    } else {
        generate_trace_id()
    };
    let parent_span_id = if parent_span_id.is_empty() {
        None
    } else {
        Some(parent_span_id)
    };

    CorrelationContext {
        trace_id,
        span_id: generate_span_id(),
        parent_span_id,
        correlation_id,
        request_id,
    }
}

fn correlation_from_query(
    query: &HashMap<String, String>,
    fallback: &CorrelationContext,
) -> CorrelationContext {
    let request_id = query
        .get("request_id")
        .and_then(|value| non_empty_text(value))
        .or_else(|| fallback.request_id.clone());
    let correlation_id = query
        .get("correlation_id")
        .and_then(|value| non_empty_text(value))
        .or_else(|| fallback.correlation_id.clone())
        .or_else(|| request_id.clone());
    let trace_id = query
        .get("trace_id")
        .and_then(|value| normalize_hex_id(value, 32))
        .unwrap_or_else(|| fallback.trace_id.clone());
    let parent_span_id = query
        .get("parent_span_id")
        .and_then(|value| normalize_hex_id(value, 16))
        .or_else(|| Some(fallback.span_id.clone()));

    CorrelationContext {
        trace_id,
        span_id: generate_span_id(),
        parent_span_id,
        correlation_id,
        request_id,
    }
}

fn header_value(headers: &HeaderMap, name: &str) -> Option<String> {
    headers
        .get(name)
        .and_then(|value| value.to_str().ok())
        .and_then(non_empty_text)
}

fn non_empty_text(value: &str) -> Option<String> {
    let trimmed = value.trim();
    if trimmed.is_empty() {
        None
    } else {
        Some(trimmed.to_string())
    }
}

fn normalize_hex_id(value: &str, expected_len: usize) -> Option<String> {
    let mut out = String::with_capacity(expected_len);
    for ch in value.chars() {
        if ch == '-' {
            continue;
        }
        if !ch.is_ascii_hexdigit() {
            return None;
        }
        out.push(ch.to_ascii_lowercase());
    }
    if out.len() == expected_len {
        Some(out)
    } else {
        None
    }
}

fn parse_traceparent(value: &str) -> Option<(String, String)> {
    let mut parts = value.trim().split('-');
    let _version = parts.next()?;
    let trace_id = normalize_hex_id(parts.next()?, 32)?;
    let span_id = normalize_hex_id(parts.next()?, 16)?;
    let _flags = parts.next()?;
    Some((trace_id, span_id))
}

fn generate_trace_id() -> String {
    Uuid::new_v4().simple().to_string()
}

fn generate_span_id() -> String {
    let hex = Uuid::new_v4().simple().to_string();
    hex[..16].to_string()
}

fn sanitize_query_for_log(query: Option<&str>) -> String {
    let Some(query) = query else {
        return String::new();
    };
    if query.is_empty() {
        return String::new();
    }

    query
        .split('&')
        .filter(|pair| !pair.is_empty())
        .map(|pair| {
            let (key, value) = pair.split_once('=').unwrap_or((pair, ""));
            if is_sensitive_key(key) {
                format!("{key}=<redacted>")
            } else if value.is_empty() {
                key.to_string()
            } else {
                format!("{key}={value}")
            }
        })
        .collect::<Vec<_>>()
        .join("&")
}

fn is_sensitive_key(key: &str) -> bool {
    let key = key.to_ascii_lowercase();
    matches!(
        key.as_str(),
        "session" | "csrf" | "token" | "authorization" | "api_key" | "password"
    ) || key.contains("secret")
        || key.ends_with("_token")
        || key.ends_with("_secret")
}

fn redacted_attributes(
    attributes: &serde_json::Map<String, JsonValue>,
) -> serde_json::Map<String, JsonValue> {
    attributes
        .iter()
        .map(|(key, value)| {
            if is_sensitive_key(key) {
                (key.clone(), JsonValue::String("<redacted>".to_string()))
            } else {
                (key.clone(), value.clone())
            }
        })
        .collect()
}

fn apply_http_transport_headers(headers: &mut HeaderMap, config: &HttpTransportConfig) {
    if let Some(value) = config.http3_alt_svc.as_deref() {
        match header::HeaderValue::from_str(value) {
            Ok(value) => {
                headers.insert("alt-svc", value);
            }
            Err(_) => {
                warn!(value, "invalid Alt-Svc header value configured");
            }
        }
    }

    if config.emit_diagnostics_header {
        let diagnostics = config.diagnostics_header();
        if let Ok(value) = header::HeaderValue::from_str(&diagnostics) {
            headers.insert("x-shelly-transport", value);
        }
        let progressive = if config.progressive_enhancement {
            header::HeaderValue::from_static("enabled")
        } else {
            header::HeaderValue::from_static("disabled")
        };
        headers.insert("x-shelly-progressive-enhancement", progressive);
    }
}

fn with_http_transport_headers(mut response: Response, config: &HttpTransportConfig) -> Response {
    apply_http_transport_headers(response.headers_mut(), config);
    response
}

async fn client_js(
    State(state): State<Arc<AppState>>,
    method: Method,
    headers: HeaderMap,
    uri: Uri,
) -> impl IntoResponse {
    let _ = log_http_ingress("client_js", &method, &uri, &headers);
    with_http_transport_headers(
        (
            [("content-type", "text/javascript; charset=utf-8")],
            CLIENT_JS,
        )
            .into_response(),
        &state.transport_http,
    )
}

async fn transport_capabilities(
    State(state): State<Arc<AppState>>,
    method: Method,
    headers: HeaderMap,
    uri: Uri,
) -> Response {
    let _ = log_http_ingress("transport_capabilities", &method, &uri, &headers);
    let capabilities = TransportCapabilities {
        protocol: PROTOCOL_VERSION,
        primary: state.transport_http.primary_mode.as_str(),
        fallbacks: state.transport_http.fallback_names(),
        progressive_enhancement: state.transport_http.progressive_enhancement,
        http3_advertised: state.transport_http.http3_alt_svc.is_some(),
    };
    with_http_transport_headers(Json(capabilities).into_response(), &state.transport_http)
}

async fn initial_handler(
    State(state): State<Arc<AppState>>,
    method: Method,
    headers: HeaderMap,
    uri: Uri,
) -> Response {
    let correlation = log_http_ingress("initial_render", &method, &uri, &headers);
    let path = uri.path();
    let Some(route) = state.route_for(path) else {
        warn!(path, "Shelly route not found");
        return with_http_transport_headers(
            (
                StatusCode::NOT_FOUND,
                format!("No Shelly route registered for {path}"),
            )
                .into_response(),
            &state.transport_http,
        );
    };

    debug!(path, "rendering initial Shelly route");
    let mut session = LiveSession::new_with_route(
        (route.factory)(),
        state.target_id.clone(),
        route.path.clone(),
        route.params,
    );
    let session_telemetry: Arc<dyn TelemetrySink> = Arc::new(SessionTelemetrySink::new(
        state.telemetry.clone(),
        correlation.with_new_span(),
    ));
    session.set_telemetry_sink(session_telemetry);
    if let Err(err) = session.mount() {
        error!(path, ?err, "Shelly mount failed during initial render");
        return with_http_transport_headers(
            (
                StatusCode::INTERNAL_SERVER_ERROR,
                format!("Shelly mount failed: {err}"),
            )
                .into_response(),
            &state.transport_http,
        );
    }

    let session_token =
        state
            .security
            .signer
            .sign_session(session.session_id(), path, &state.distributed.node_id);
    let csrf_token = state.security.signer.sign_csrf(session.session_id(), path);
    let transport_fallbacks = state.transport_http.fallback_json();
    let body = render_shell(ShellConfig {
        target_id: &state.target_id,
        inner_html: session.render_html().as_str(),
        path,
        title: "Shelly LiveView",
        session_id: session.session_id(),
        session_token: &session_token,
        csrf_token: &csrf_token,
        protocol: PROTOCOL_VERSION,
        trace_id: &correlation.trace_id,
        span_id: &correlation.span_id,
        correlation_id: correlation.correlation_id.as_deref(),
        request_id: correlation.request_id.as_deref(),
        reconnect_base_ms: state.reconnect.client.reconnect_base_ms,
        reconnect_max_ms: state.reconnect.client.reconnect_max_ms,
        reconnect_jitter_ms: state.reconnect.client.reconnect_jitter_ms,
        heartbeat_interval_ms: state.reconnect.client.heartbeat_interval_ms,
        heartbeat_timeout_ms: state.reconnect.client.heartbeat_timeout_ms,
        transport_mode: state.transport_http.primary_mode.as_str(),
        transport_fallbacks: &transport_fallbacks,
        progressive_enhancement: state.transport_http.progressive_enhancement,
    });

    with_http_transport_headers(AxumHtml(body).into_response(), &state.transport_http)
}

async fn ws_handler(
    Path(view_path): Path<String>,
    State(state): State<Arc<AppState>>,
    method: Method,
    headers: HeaderMap,
    uri: Uri,
    ws: WebSocketUpgrade,
) -> Response {
    let route_path = if view_path == "__root__" {
        "/".to_string()
    } else {
        normalize_path(view_path)
    };
    let query = parse_query(uri.query().unwrap_or_default());
    let ingress_correlation = log_http_ingress("ws_upgrade", &method, &uri, &headers);
    let socket_correlation = correlation_from_query(&query, &ingress_correlation);
    info!(
        target: "shelly.incoming.http",
        schema = "shelly.incoming.http.v1",
        transport = "ws",
        stage = "upgrade_request",
        route = %route_path,
        trace_id = %socket_correlation.trace_id,
        span_id = %socket_correlation.span_id,
        parent_span_id = socket_correlation.parent_span_id.as_deref().unwrap_or("-"),
        correlation_id = socket_correlation.correlation_id.as_deref().unwrap_or("-"),
        request_id = socket_correlation.request_id.as_deref().unwrap_or("-"),
        protocol = query
            .get("protocol")
            .map(String::as_str)
            .unwrap_or("unknown"),
        has_session_token = query.contains_key("session"),
        has_csrf_token = query.contains_key("csrf"),
        "Shelly websocket upgrade request received"
    );

    let Some(route) = state.route_for(&route_path) else {
        warn!(path = route_path, "Shelly websocket route not found");
        return with_http_transport_headers(
            (
                StatusCode::NOT_FOUND,
                format!("No Shelly route registered for {route_path}"),
            )
                .into_response(),
            &state.transport_http,
        );
    };

    if !origin_allowed(&headers, &state.security) {
        emit_security_audit(
            &state.telemetry,
            &socket_correlation,
            &route_path,
            None,
            None,
            "origin_check",
            false,
            Some("origin_rejected"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("origin rejected by websocket policy"),
        );
        warn!(
            path = route_path,
            "Shelly websocket rejected cross-origin request"
        );
        return with_http_transport_headers(
            (
                StatusCode::FORBIDDEN,
                "Shelly WebSocket origin rejected".to_string(),
            )
                .into_response(),
            &state.transport_http,
        );
    }

    if query.get("protocol").map(String::as_str) != Some(PROTOCOL_VERSION) {
        emit_security_audit(
            &state.telemetry,
            &socket_correlation,
            &route_path,
            None,
            None,
            "protocol_check",
            false,
            Some("unsupported_protocol"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("unsupported websocket protocol version"),
        );
        warn!(
            path = route_path,
            "Shelly websocket rejected unsupported protocol"
        );
        return with_http_transport_headers(
            (
                StatusCode::BAD_REQUEST,
                format!("Shelly WebSocket requires protocol {PROTOCOL_VERSION}"),
            )
                .into_response(),
            &state.transport_http,
        );
    }

    let Some(signed_session) = verify_websocket_tokens(&state.security.signer, &query, &route_path)
    else {
        emit_security_audit(
            &state.telemetry,
            &socket_correlation,
            &route_path,
            None,
            None,
            "token_check",
            false,
            Some("signed_session_required"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("signed session or csrf token validation failed"),
        );
        warn!(
            path = route_path,
            "Shelly websocket rejected unsigned or invalid session"
        );
        return with_http_transport_headers(
            (
                StatusCode::UNAUTHORIZED,
                "Shelly WebSocket requires a valid signed session".to_string(),
            )
                .into_response(),
            &state.transport_http,
        );
    };
    if let Some(affinity_context) =
        session_affinity_mismatch(&state.distributed, &signed_session, &route_path)
    {
        emit_security_audit(
            &state.telemetry,
            &socket_correlation,
            &route_path,
            Some(&affinity_context.session_id),
            None,
            "session_affinity",
            false,
            Some("session_affinity_mismatch"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("session affinity policy rejected websocket ownership"),
        );
        warn!(
            path = affinity_context.route_path,
            session_id = affinity_context.session_id,
            current_node_id = affinity_context.current_node_id,
            token_node_id = affinity_context.token_node_id.as_deref().unwrap_or("-"),
            "Shelly websocket rejected session-affinity mismatch"
        );
        return with_http_transport_headers(
            (
                StatusCode::CONFLICT,
                "Shelly WebSocket session-affinity mismatch".to_string(),
            )
                .into_response(),
            &state.transport_http,
        );
    }

    let config = SocketConfig {
        routes: state.routes.clone(),
        target_id: state.target_id.clone(),
        route_path: route_path.clone(),
        signed_session_id: signed_session.session_id,
        max_message_size: state.max_message_size,
        pubsub: state.pubsub.clone(),
        uploads: state.uploads.clone(),
        security: state.security.clone(),
        telemetry: state.telemetry.clone(),
        correlation: socket_correlation,
        reconnect: state.reconnect.clone(),
        distributed: state.distributed.clone(),
        durable: state.durable.clone(),
        outbound: state.outbound.clone(),
        render: state.render.clone(),
        overload: state.overload.clone(),
    };
    with_http_transport_headers(
        ws.on_upgrade(move |socket| handle_socket(socket, route, config))
            .into_response(),
        &state.transport_http,
    )
}

fn cleanup_expired_snapshots(snapshots: &mut HashMap<String, ResumeSnapshot>) {
    let now = Instant::now();
    snapshots.retain(|_, snapshot| snapshot.expires_at > now);
}

fn session_affinity_mismatch(
    distributed: &DistributedConfig,
    signed_session: &SignedSession,
    route_path: &str,
) -> Option<SessionAffinityContext> {
    if distributed.session_affinity != SessionAffinityMode::Required {
        return None;
    }
    if signed_session.node_id.as_deref() == Some(distributed.node_id.as_str()) {
        return None;
    }
    Some(SessionAffinityContext {
        session_id: signed_session.session_id.clone(),
        route_path: route_path.to_string(),
        current_node_id: distributed.node_id.clone(),
        token_node_id: signed_session.node_id.clone(),
    })
}

async fn take_resume_snapshot(
    reconnect: &ReconnectConfig,
    session_id: &str,
) -> Option<ResumeSnapshot> {
    let mut snapshots = reconnect.snapshots.lock().await;
    cleanup_expired_snapshots(&mut snapshots);
    snapshots.remove(session_id)
}

async fn put_resume_snapshot(
    reconnect: &ReconnectConfig,
    session_id: String,
    snapshot: ResumeSnapshot,
) {
    let mut snapshots = reconnect.snapshots.lock().await;
    cleanup_expired_snapshots(&mut snapshots);
    snapshots.insert(session_id, snapshot);
}

async fn stash_reconnect_snapshot(
    reconnect: &ReconnectConfig,
    session_id: String,
    session: LiveSession,
    route_pattern: String,
    resume_token: Option<String>,
) {
    let Some(resume_token) = resume_token else {
        return;
    };
    let snapshot = ResumeSnapshot {
        session,
        route_pattern,
        resume_token,
        expires_at: Instant::now() + reconnect.resume_ttl,
    };
    put_resume_snapshot(reconnect, session_id, snapshot).await;
}

#[derive(Debug, Clone)]
struct DurableLeaseHandle {
    owner_node_id: String,
    fence_token: u64,
}

struct DurableRecoveryResult {
    snapshot: ResumeSnapshot,
    replayed_entries: usize,
    source_owner_node_id: String,
}

fn durable_error_message(error: &DurableStoreError) -> ServerMessage {
    ServerMessage::Error {
        message: error.message.clone(),
        code: Some(error.code.clone()),
    }
}

fn durable_message_should_journal(message: &ClientMessage) -> bool {
    match message {
        ClientMessage::Event { event, .. } => event != INTERNAL_RENDER_FLUSH_EVENT,
        ClientMessage::PatchUrl { .. } | ClientMessage::Navigate { .. } => true,
        _ => false,
    }
}

fn contains_server_error(messages: &[ServerMessage]) -> bool {
    messages
        .iter()
        .any(|message| matches!(message, ServerMessage::Error { .. }))
}

fn durable_save_snapshot(
    durable: &DurableRuntimeConfig,
    lease: &DurableLeaseHandle,
    session: &LiveSession,
    route_pattern: &str,
    target_id: &str,
    resume_token: &str,
) {
    let Some(store) = durable.store.as_ref() else {
        return;
    };
    store.save_snapshot(
        session.session_id(),
        DurableSessionSnapshot {
            route_path: session.route_path().to_string(),
            route_pattern: route_pattern.to_string(),
            target_id: target_id.to_string(),
            revision: session.revision(),
            resume_token: resume_token.to_string(),
            owner_node_id: lease.owner_node_id.clone(),
            updated_at_unix_ms: now_unix_ms(),
        },
    );
}

fn durable_append_journal_entry(
    durable: &DurableRuntimeConfig,
    lease: &DurableLeaseHandle,
    session_id: &str,
    message: &ClientMessage,
) -> Result<Option<DurableJournalEntry>, DurableStoreError> {
    if !durable_message_should_journal(message) {
        return Ok(None);
    }
    let Some(store) = durable.store.as_ref() else {
        return Ok(None);
    };
    let entry = store.append_journal_entry(
        session_id,
        &lease.owner_node_id,
        lease.fence_token,
        message.clone(),
        durable.journal_limit,
    )?;
    Ok(Some(entry))
}

fn durable_release_lease(
    durable: &DurableRuntimeConfig,
    session_id: &str,
    lease: Option<&DurableLeaseHandle>,
) {
    let (Some(store), Some(lease)) = (durable.store.as_ref(), lease) else {
        return;
    };
    store.release_lease(session_id, &lease.owner_node_id, lease.fence_token);
}

fn durable_acquire_lease(
    durable: &DurableRuntimeConfig,
    distributed: &DistributedConfig,
    session_id: &str,
    route_path: &str,
) -> Result<Option<DurableLeaseHandle>, DurableStoreError> {
    let Some(store) = durable.store.as_ref() else {
        return Ok(None);
    };

    if durable.drain_mode || store.is_node_draining(&distributed.node_id) {
        return Err(DurableStoreError::new(
            "node_draining",
            format!(
                "node {} is draining and cannot accept durable sessions",
                distributed.node_id
            ),
        ));
    }

    if let Some(placement_hook) = durable.placement_hook.as_ref() {
        let preferred_node_id = store
            .load_record(session_id)
            .map(|record| record.snapshot.owner_node_id);
        let decision = placement_hook(&DurablePlacementContext {
            session_id: session_id.to_string(),
            route_path: route_path.to_string(),
            current_node_id: distributed.node_id.clone(),
            preferred_node_id,
        });
        if !decision.allowed {
            return Err(DurableStoreError::new(
                decision
                    .code
                    .unwrap_or_else(|| "placement_rejected".to_string()),
                decision
                    .message
                    .unwrap_or_else(|| "durable placement policy rejected ownership".to_string()),
            ));
        }
    }

    let lease = store.acquire_lease(DurableLeaseRequest {
        session_id: session_id.to_string(),
        node_id: distributed.node_id.clone(),
        ttl_ms: durable.lease_ttl.as_millis() as u64,
        takeover_policy: durable.takeover_policy,
    })?;
    Ok(Some(DurableLeaseHandle {
        owner_node_id: lease.owner_node_id,
        fence_token: lease.fence_token,
    }))
}

fn replay_durable_journal_entry(
    session: &mut LiveSession,
    current_route_pattern: &mut String,
    routes: &[LiveRoute],
    target_id: &str,
    session_id: &str,
    telemetry: &Arc<dyn TelemetrySink>,
    entry: &DurableJournalEntry,
) -> Result<(), String> {
    let messages = match &entry.message {
        ClientMessage::PatchUrl { to } => {
            handle_patch_url(session, current_route_pattern, routes, to)
        }
        ClientMessage::Navigate { to } => handle_navigate(
            session,
            current_route_pattern,
            routes,
            target_id,
            session_id,
            telemetry,
            to,
        ),
        ClientMessage::Event { .. } => session.handle_client_message(entry.message.clone()),
        _ => Vec::new(),
    };
    if let Some(ServerMessage::Error { code, message }) = messages
        .into_iter()
        .find(|message| matches!(message, ServerMessage::Error { .. }))
    {
        return Err(format!(
            "durable journal replay failed: code={} message={}",
            code.unwrap_or_else(|| "-".to_string()),
            message
        ));
    }
    Ok(())
}

fn recover_from_durable_record(
    config: &SocketConfig,
    session_id: &str,
    telemetry: &Arc<dyn TelemetrySink>,
) -> Option<DurableRecoveryResult> {
    let store = config.durable.store.as_ref()?;
    let record = store.load_record(session_id)?;
    let DurableSessionRecord {
        snapshot: stored_snapshot,
        mut journal,
    } = record;
    let recovered_path = normalize_path(stored_snapshot.route_path.clone());
    let matched_route = config
        .routes
        .iter()
        .find_map(|route| route.match_path(&recovered_path))
        .or_else(|| {
            config
                .routes
                .iter()
                .find_map(|route| route.match_path(&config.route_path))
        })?;

    let mut current_route_pattern = matched_route.pattern.clone();
    let mut session = LiveSession::new_with_route_and_session_id(
        (matched_route.factory)(),
        session_id.to_string(),
        config.target_id.clone(),
        matched_route.path,
        matched_route.params,
    );
    session.set_telemetry_sink(telemetry.clone());
    if session.mount().is_err() {
        return None;
    }

    let mut replayed_entries = 0usize;
    journal.sort_by_key(|entry| entry.sequence);
    for entry in journal {
        if replay_durable_journal_entry(
            &mut session,
            &mut current_route_pattern,
            &config.routes,
            &config.target_id,
            session_id,
            telemetry,
            &entry,
        )
        .is_err()
        {
            return None;
        }
        replayed_entries += 1;
    }

    Some(DurableRecoveryResult {
        snapshot: ResumeSnapshot {
            session,
            route_pattern: current_route_pattern,
            resume_token: stored_snapshot.resume_token.clone(),
            expires_at: Instant::now() + config.reconnect.resume_ttl,
        },
        replayed_entries,
        source_owner_node_id: stored_snapshot.owner_node_id,
    })
}

fn correlation_from_connect(
    base: &CorrelationContext,
    connect: &ConnectHandshake,
) -> CorrelationContext {
    let trace_id = connect
        .trace_id
        .as_deref()
        .and_then(|value| normalize_hex_id(value, 32))
        .unwrap_or_else(|| base.trace_id.clone());
    let parent_span_id = connect
        .span_id
        .as_deref()
        .and_then(|value| normalize_hex_id(value, 16))
        .or_else(|| {
            connect
                .parent_span_id
                .as_deref()
                .and_then(|value| normalize_hex_id(value, 16))
        })
        .or_else(|| Some(base.span_id.clone()));
    let correlation_id = connect
        .correlation_id
        .as_deref()
        .and_then(non_empty_text)
        .or_else(|| base.correlation_id.clone());
    let request_id = connect
        .request_id
        .as_deref()
        .and_then(non_empty_text)
        .or_else(|| base.request_id.clone());

    CorrelationContext {
        trace_id,
        span_id: generate_span_id(),
        parent_span_id,
        correlation_id,
        request_id,
    }
}

fn reconnect_event(
    session_id: &str,
    route_path: &str,
    correlation: &CorrelationContext,
    ok: bool,
    status: ResumeStatus,
    reason: Option<&str>,
) -> TelemetryEvent {
    let mut event = TelemetryEvent::new(TelemetryEventKind::Connect)
        .with_session(session_id.to_string())
        .with_route(route_path.to_string())
        .with_ok(ok)
        .with_attribute(
            "resume_status".to_string(),
            JsonValue::String(
                match status {
                    ResumeStatus::Fresh => "fresh",
                    ResumeStatus::Resumed => "resumed",
                    ResumeStatus::Fallback => "fallback",
                }
                .to_string(),
            ),
        );
    event = correlation.apply_to_event(event);
    if let Some(reason) = reason {
        event = event.with_attribute(
            "resume_reason".to_string(),
            JsonValue::String(reason.to_string()),
        );
    }
    event
}

async fn read_connect_handshake(
    receiver: &mut futures_util::stream::SplitStream<WebSocket>,
    timeout_window: Duration,
) -> Result<ConnectHandshake, ServerMessage> {
    let maybe_frame = timeout(timeout_window, receiver.next())
        .await
        .map_err(|_| ServerMessage::Error {
            message: "connect handshake timed out".to_string(),
            code: Some("connect_timeout".to_string()),
        })?;
    let Some(frame) = maybe_frame else {
        return Err(ServerMessage::Error {
            message: "websocket closed before connect handshake".to_string(),
            code: Some("connect_missing".to_string()),
        });
    };
    let frame = frame.map_err(|err| ServerMessage::Error {
        message: format!("websocket receive error during connect handshake: {err}"),
        code: Some("connect_io_error".to_string()),
    })?;
    let Message::Text(text) = frame else {
        return Err(ServerMessage::Error {
            message: "first websocket frame must be a connect message".to_string(),
            code: Some("connect_required".to_string()),
        });
    };

    let parsed = serde_json::from_str::<ClientMessage>(text.as_str()).map_err(|err| {
        ServerMessage::Error {
            message: format!("invalid protocol message: {err}"),
            code: Some("invalid_protocol".to_string()),
        }
    })?;

    let ClientMessage::Connect {
        protocol,
        session_id,
        last_revision,
        resume_token,
        tenant_id,
        trace_id,
        span_id,
        parent_span_id,
        correlation_id,
        request_id,
    } = parsed
    else {
        return Err(ServerMessage::Error {
            message: "first websocket message must be type connect".to_string(),
            code: Some("connect_required".to_string()),
        });
    };

    if protocol != PROTOCOL_VERSION {
        return Err(ServerMessage::Error {
            message: format!(
                "unsupported protocol in connect: expected {PROTOCOL_VERSION}, got {protocol}"
            ),
            code: Some("unsupported_protocol".to_string()),
        });
    }

    Ok(ConnectHandshake {
        client_session_id: session_id,
        client_revision: last_revision.unwrap_or(0),
        resume_token,
        tenant_id: normalize_tenant_id(tenant_id),
        trace_id,
        span_id,
        parent_span_id,
        correlation_id,
        request_id,
    })
}

async fn handle_socket(socket: WebSocket, route: MatchedRoute, config: SocketConfig) {
    let (mut sender, mut receiver) = socket.split();
    let mut current_route_pattern: String;
    let (pubsub_tx, mut pubsub_rx) = mpsc::unbounded_channel();
    let (runtime_tx, mut runtime_rx) = mpsc::unbounded_channel();
    let mut pubsub_tasks = Vec::new();
    let mut runtime_tasks = HashMap::new();
    let mut subscribed_topics = HashSet::new();
    let mut uploads = HashMap::new();
    let session_id = config.signed_session_id.clone();
    let connect =
        match read_connect_handshake(&mut receiver, config.reconnect.connect_handshake_timeout)
            .await
        {
            Ok(connect) => connect,
            Err(message) => {
                emit_security_audit(
                    &config.telemetry,
                    &config.correlation,
                    &config.route_path,
                    Some(&session_id),
                    None,
                    "connect_handshake",
                    false,
                    Some("connect_required"),
                    SecurityOperation::Connect,
                    "text",
                    None,
                    Some("first websocket message was not a valid connect handshake"),
                );
                warn!(
                    path = config.route_path,
                    session_id, "Shelly websocket connect handshake failed"
                );
                let _ = send_server_message(&mut sender, &message).await;
                return;
            }
        };

    if connect
        .client_session_id
        .as_deref()
        .map(|id| id != session_id.as_str())
        .unwrap_or(false)
    {
        emit_security_audit(
            &config.telemetry,
            &config.correlation,
            &config.route_path,
            Some(&session_id),
            connect.tenant_id.as_deref(),
            "connect_session_match",
            false,
            Some("session_mismatch"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("connect session id does not match signed session"),
        );
        let _ = send_server_message(
            &mut sender,
            &ServerMessage::Error {
                message: "connect session id does not match signed session".to_string(),
                code: Some("session_mismatch".to_string()),
            },
        )
        .await;
        return;
    }
    let connection_correlation = correlation_from_connect(&config.correlation, &connect);
    let session_telemetry: Arc<dyn TelemetrySink> = Arc::new(SessionTelemetrySink::new(
        config.telemetry.clone(),
        connection_correlation.clone(),
    ));
    if let Some(rejection) = quota_denied(
        &config.security,
        &config.route_path,
        &session_id,
        connect.tenant_id.as_deref(),
        "text",
        SecurityOperation::Connect,
        None,
    ) {
        emit_security_audit(
            &config.telemetry,
            &connection_correlation,
            &config.route_path,
            Some(&session_id),
            connect.tenant_id.as_deref(),
            "quota_policy",
            false,
            Some("quota_exceeded"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("tenant/session quota policy rejected connect handshake"),
        );
        let _ = send_server_message(&mut sender, &rejection).await;
        return;
    }
    if let Some(rejection) = authorization_denied(
        &config.security,
        AuthorizationInput {
            route_path: &config.route_path,
            session_id: &session_id,
            tenant_id: connect.tenant_id.as_deref(),
            message_kind: "text",
            operation: SecurityOperation::Connect,
            event_name: None,
            event_target: None,
        },
    ) {
        emit_security_audit(
            &config.telemetry,
            &connection_correlation,
            &config.route_path,
            Some(&session_id),
            connect.tenant_id.as_deref(),
            "authorization_policy",
            false,
            Some("unauthorized"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("tenant/session authorization policy rejected connect handshake"),
        );
        let _ = send_server_message(&mut sender, &rejection).await;
        return;
    }
    emit_security_audit(
        &config.telemetry,
        &connection_correlation,
        &config.route_path,
        Some(&session_id),
        connect.tenant_id.as_deref(),
        "connect_gate",
        true,
        Some("allowed"),
        SecurityOperation::Connect,
        "text",
        None,
        Some("connect gate accepted websocket session"),
    );

    let durable_lease = match durable_acquire_lease(
        &config.durable,
        &config.distributed,
        &session_id,
        &config.route_path,
    ) {
        Ok(lease) => lease,
        Err(err) => {
            warn!(
                path = config.route_path,
                session_id,
                code = err.code,
                message = err.message,
                "Shelly durable ownership rejected websocket connect"
            );
            let _ = send_server_message(&mut sender, &durable_error_message(&err)).await;
            return;
        }
    };

    let mut resume_status = ResumeStatus::Fresh;
    let mut resume_reason: Option<String> = None;
    let hello_revision: u64;
    let mut hello_server_revision: Option<u64> = None;
    let mut reconciliation_patch: Option<ServerMessage> = None;
    let mut recovered_from_durable = false;
    let mut durable_replay_metadata: Option<(usize, String)> = None;

    let recoverable_snapshot = if let Some(snapshot) =
        take_resume_snapshot(&config.reconnect, &session_id).await
    {
        Some(snapshot)
    } else if let Some(recovery) =
        recover_from_durable_record(&config, &session_id, &session_telemetry)
    {
        recovered_from_durable = true;
        durable_replay_metadata = Some((recovery.replayed_entries, recovery.source_owner_node_id));
        Some(recovery.snapshot)
    } else {
        None
    };

    let mut session = if let Some(snapshot) = recoverable_snapshot {
        let token_reason = match connect.resume_token.as_deref() {
            None => Some("resume_token_missing"),
            Some(token) => match config.security.signer.verify_resume(token) {
                None => Some("resume_token_invalid"),
                Some(signed_resume) => {
                    if signed_resume.session_id != session_id
                        || signed_resume.path != config.route_path
                    {
                        Some("resume_token_scope_mismatch")
                    } else if token != snapshot.resume_token {
                        Some("resume_token_stale")
                    } else {
                        None
                    }
                }
            },
        };

        if let Some(reason) = token_reason {
            resume_status = ResumeStatus::Fallback;
            resume_reason = Some(reason.to_string());
            let mut fresh = LiveSession::new_with_route_and_session_id(
                (route.factory)(),
                session_id.clone(),
                config.target_id.clone(),
                route.path.clone(),
                route.params.clone(),
            );
            fresh.set_tenant_id_optional(connect.tenant_id.clone());
            fresh.set_telemetry_sink(session_telemetry.clone());
            if let Err(err) = fresh.mount() {
                error!(
                    path = config.route_path,
                    session_id,
                    ?err,
                    "Shelly websocket mount failed"
                );
                let _ = send_server_message(
                    &mut sender,
                    &ServerMessage::Error {
                        message: format!("mount failed: {err}"),
                        code: Some("mount_failed".to_string()),
                    },
                )
                .await;
                durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
                return;
            }
            current_route_pattern = route.pattern.clone();
            hello_revision = fresh.revision();
            fresh
        } else {
            let mut resumed = snapshot.session;
            resumed.set_telemetry_sink(session_telemetry.clone());
            let server_revision = resumed.revision();
            if connect.client_revision > server_revision {
                resume_status = ResumeStatus::Fallback;
                resume_reason = Some("resume_revision_ahead".to_string());
                let mut fresh = LiveSession::new_with_route_and_session_id(
                    (route.factory)(),
                    session_id.clone(),
                    config.target_id.clone(),
                    route.path.clone(),
                    route.params.clone(),
                );
                fresh.set_tenant_id_optional(connect.tenant_id.clone());
                fresh.set_telemetry_sink(session_telemetry.clone());
                if let Err(err) = fresh.mount() {
                    error!(
                        path = config.route_path,
                        session_id,
                        ?err,
                        "Shelly websocket mount failed"
                    );
                    let _ = send_server_message(
                        &mut sender,
                        &ServerMessage::Error {
                            message: format!("mount failed: {err}"),
                            code: Some("mount_failed".to_string()),
                        },
                    )
                    .await;
                    durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
                    return;
                }
                current_route_pattern = route.pattern.clone();
                hello_revision = fresh.revision();
                fresh
            } else {
                resume_status = ResumeStatus::Resumed;
                current_route_pattern = snapshot.route_pattern;
                if connect.client_revision < server_revision {
                    hello_revision = connect.client_revision;
                    hello_server_revision = Some(server_revision);
                    reconciliation_patch = Some(resumed.render_snapshot_patch());
                    if recovered_from_durable {
                        if let Some((replayed_entries, source_owner)) =
                            durable_replay_metadata.as_ref()
                        {
                            resume_reason = Some(format!(
                                    "durable_revision_reconciled:from={source_owner}:entries={replayed_entries}"
                                ));
                        } else {
                            resume_reason = Some("durable_revision_reconciled".to_string());
                        }
                    } else {
                        resume_reason = Some("revision_reconciled".to_string());
                    }
                } else {
                    hello_revision = server_revision;
                    if recovered_from_durable {
                        if let Some((replayed_entries, source_owner)) =
                            durable_replay_metadata.as_ref()
                        {
                            resume_reason = Some(format!(
                                "durable_replay:from={source_owner}:entries={replayed_entries}"
                            ));
                        } else {
                            resume_reason = Some("durable_replay".to_string());
                        }
                    }
                }
                resumed
            }
        }
    } else {
        if connect.resume_token.is_some() || connect.client_revision > 0 {
            resume_status = ResumeStatus::Fallback;
            resume_reason = Some("resume_snapshot_missing".to_string());
        }
        let mut fresh = LiveSession::new_with_route_and_session_id(
            (route.factory)(),
            session_id.clone(),
            config.target_id.clone(),
            route.path.clone(),
            route.params.clone(),
        );
        fresh.set_tenant_id_optional(connect.tenant_id.clone());
        fresh.set_telemetry_sink(session_telemetry.clone());
        if let Err(err) = fresh.mount() {
            error!(
                path = config.route_path,
                session_id,
                ?err,
                "Shelly websocket mount failed"
            );
            let _ = send_server_message(
                &mut sender,
                &ServerMessage::Error {
                    message: format!("mount failed: {err}"),
                    code: Some("mount_failed".to_string()),
                },
            )
            .await;
            durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
            return;
        }
        current_route_pattern = route.pattern.clone();
        hello_revision = fresh.revision();
        fresh
    };
    if tenant_context_conflict(session.tenant_id(), connect.tenant_id.as_deref()) {
        emit_security_audit(
            &config.telemetry,
            &connection_correlation,
            &config.route_path,
            Some(&session_id),
            session.tenant_id(),
            "tenant_policy",
            false,
            Some("tenant_mismatch"),
            SecurityOperation::Connect,
            "text",
            None,
            Some("connect tenant_id does not match restored session tenant context"),
        );
        let _ = send_server_message(
            &mut sender,
            &ServerMessage::Error {
                message: "connect tenant_id does not match restored session tenant context"
                    .to_string(),
                code: Some("tenant_mismatch".to_string()),
            },
        )
        .await;
        durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
        return;
    }
    if session.tenant_id().is_none() {
        session.set_tenant_id_optional(connect.tenant_id.clone());
    }
    session.set_default_render_cadence_ms(config.render.default_cadence_ms);

    let resume_token = if matches!(resume_status, ResumeStatus::Resumed) {
        connect.resume_token.clone().unwrap_or_else(|| {
            config
                .security
                .signer
                .sign_resume(session.session_id(), session.route_path())
        })
    } else {
        config
            .security
            .signer
            .sign_resume(session.session_id(), session.route_path())
    };
    let resume_expires_in_ms = config.reconnect.resume_ttl.as_millis() as u64;
    let hello = ServerMessage::Hello {
        session_id: session.session_id().to_string(),
        target: config.target_id.clone(),
        revision: hello_revision,
        protocol: PROTOCOL_VERSION.to_string(),
        server_revision: hello_server_revision,
        resume_status: Some(resume_status),
        resume_reason: resume_reason.clone(),
        resume_token: Some(resume_token.clone()),
        resume_expires_in_ms: Some(resume_expires_in_ms),
    };

    process_pubsub_commands(
        session.drain_pubsub_commands(),
        &config.pubsub,
        &pubsub_tx,
        &mut pubsub_tasks,
        &mut subscribed_topics,
        &session_id,
        &config.distributed.node_id,
        &config.telemetry,
        &connection_correlation,
    );
    process_runtime_commands(
        session.drain_runtime_commands(),
        &runtime_tx,
        &mut runtime_tasks,
    );

    info!(
        path = config.route_path,
        trace_id = %connection_correlation.trace_id,
        span_id = %connection_correlation.span_id,
        parent_span_id = connection_correlation.parent_span_id.as_deref().unwrap_or("-"),
        correlation_id = connection_correlation.correlation_id.as_deref().unwrap_or("-"),
        request_id = connection_correlation.request_id.as_deref().unwrap_or("-"),
        session_id, "Shelly websocket connected"
    );
    let _ = config.telemetry.emit(reconnect_event(
        &session_id,
        session.route_path(),
        &connection_correlation,
        matches!(resume_status, ResumeStatus::Fresh | ResumeStatus::Resumed),
        resume_status,
        resume_reason.as_deref(),
    ));

    let mut active_resume_token = Some(resume_token.clone());
    let (outbound_tx, outbound_rx) = mpsc::channel(config.outbound.queue_capacity);
    let mut writer_task = Some(tokio::spawn(run_outbound_writer(
        sender,
        outbound_rx,
        config.outbound.clone(),
        config.telemetry.clone(),
        connection_correlation.clone(),
        config.route_path.clone(),
        session_id.clone(),
    )));
    if let (Some(lease), Some(token)) = (durable_lease.as_ref(), active_resume_token.as_deref()) {
        durable_save_snapshot(
            &config.durable,
            lease,
            &session,
            &current_route_pattern,
            &config.target_id,
            token,
        );
    }

    match queue_server_message(
        &outbound_tx,
        &hello,
        &config.outbound,
        &config.telemetry,
        &connection_correlation,
        &config.route_path,
        &session_id,
    ) {
        OutboundQueuePush::Queued | OutboundQueuePush::Dropped => {}
        OutboundQueuePush::Disconnect => {
            warn!(
                path = config.route_path,
                session_id, "Shelly websocket closed before hello"
            );
            if let Some(task) = writer_task.take() {
                task.abort();
                let _ = task.await;
            }
            unregister_pubsub_presence(
                &config.pubsub,
                &subscribed_topics,
                &session_id,
                &config.distributed.node_id,
            );
            abort_pubsub_tasks(pubsub_tasks);
            abort_runtime_tasks(runtime_tasks);
            stash_reconnect_snapshot(
                &config.reconnect,
                session_id.clone(),
                session,
                current_route_pattern.clone(),
                active_resume_token.take(),
            )
            .await;
            durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
            return;
        }
    }

    let should_skip_initial_patch = matches!(resume_status, ResumeStatus::Resumed)
        && connect.client_revision == session.revision();
    if !should_skip_initial_patch {
        let initial_patch = reconciliation_patch.unwrap_or_else(|| session.render_patch());
        match queue_server_message(
            &outbound_tx,
            &initial_patch,
            &config.outbound,
            &config.telemetry,
            &connection_correlation,
            &config.route_path,
            &session_id,
        ) {
            OutboundQueuePush::Queued | OutboundQueuePush::Dropped => {}
            OutboundQueuePush::Disconnect => {
                warn!(
                    path = config.route_path,
                    session_id, "Shelly websocket closed before initial patch"
                );
                if let Some(task) = writer_task.take() {
                    task.abort();
                    let _ = task.await;
                }
                unregister_pubsub_presence(
                    &config.pubsub,
                    &subscribed_topics,
                    &session_id,
                    &config.distributed.node_id,
                );
                abort_pubsub_tasks(pubsub_tasks);
                abort_runtime_tasks(runtime_tasks);
                stash_reconnect_snapshot(
                    &config.reconnect,
                    session_id.clone(),
                    session,
                    current_route_pattern.clone(),
                    active_resume_token.take(),
                )
                .await;
                durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
                return;
            }
        }
    }
    if let (Some(lease), Some(token)) = (durable_lease.as_ref(), active_resume_token.as_deref()) {
        durable_save_snapshot(
            &config.durable,
            lease,
            &session,
            &current_route_pattern,
            &config.target_id,
            token,
        );
    }

    macro_rules! abort_with_resume {
        () => {{
            unregister_pubsub_presence(
                &config.pubsub,
                &subscribed_topics,
                &session_id,
                &config.distributed.node_id,
            );
            abort_pubsub_tasks(pubsub_tasks);
            abort_runtime_tasks(runtime_tasks);
            stash_reconnect_snapshot(
                &config.reconnect,
                session_id.clone(),
                session,
                current_route_pattern.clone(),
                active_resume_token.take(),
            )
            .await;
            durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
            if let Some(task) = writer_task.take() {
                task.abort();
                let _ = task.await;
            }
            return;
        }};
    }

    loop {
        tokio::select! {
            maybe_message = pubsub_rx.recv() => {
                let Some(message) = maybe_message else {
                    break;
                };
                let topic = message.topic;

                for server_message in message.messages {
                    match queue_server_message(
                        &outbound_tx,
                        &server_message,
                        &config.outbound,
                        &config.telemetry,
                        &connection_correlation,
                        &config.route_path,
                        &session_id,
                    ) {
                        OutboundQueuePush::Queued => {}
                        OutboundQueuePush::Dropped => {
                            warn!(
                                path = config.route_path,
                                session_id,
                                topic,
                                "Shelly websocket dropped PubSub message due outbound backpressure"
                            );
                        }
                        OutboundQueuePush::Disconnect => {
                            warn!(
                                path = config.route_path,
                                session_id,
                                topic,
                                "Shelly websocket closed while sending PubSub message"
                            );
                            abort_with_resume!();
                        }
                    }
                }
            }
            maybe_runtime = runtime_rx.recv() => {
                let Some(runtime_event) = maybe_runtime else {
                    break;
                };
                runtime_tasks.retain(|_, task| !task.is_finished());

                let runtime_client_message = ClientMessage::Event {
                    event: runtime_event.event,
                    target: runtime_event.target,
                    value: runtime_event.value,
                    metadata: runtime_event.metadata.into_iter().collect(),
                };
                let runtime_priority = overload_priority_for_client_message(&runtime_client_message);
                let runtime_tenant_id = effective_tenant_id_for_message(
                    session.tenant_id(),
                    tenant_id_for_client_message(&runtime_client_message).as_deref(),
                );
                let (runtime_operation, runtime_event_name, _) =
                    security_operation_for_message(&runtime_client_message);
                let runtime_overload_context = OverloadContext {
                    route_path: config.route_path.clone(),
                    session_id: session_id.clone(),
                    tenant_id: runtime_tenant_id.clone(),
                    message_kind: "runtime",
                    operation: runtime_operation,
                    event_name: runtime_event_name.map(ToString::to_string),
                    priority: runtime_priority,
                    queue_depth: outbound_queue_depth(&outbound_tx, config.outbound.queue_capacity),
                    queue_capacity: config.outbound.queue_capacity,
                    inbound_bytes: serde_json::to_vec(&runtime_client_message)
                        .map(|bytes| bytes.len())
                        .unwrap_or_default(),
                };
                let runtime_overload_decision =
                    overload_decision_for_dispatch(&config.overload, &runtime_overload_context).await;
                emit_overload_telemetry(
                    &config.telemetry,
                    &connection_correlation,
                    &runtime_overload_context,
                    &runtime_overload_decision,
                );
                if !runtime_overload_decision.allowed {
                    warn!(
                        path = config.route_path,
                        session_id,
                        priority = runtime_priority.as_str(),
                        reason = runtime_overload_decision.reason.as_deref().unwrap_or("shed"),
                        "Shelly runtime event shed by overload policy"
                    );
                    if runtime_priority == OverloadPriority::Interactive
                        && matches!(
                            queue_server_message(
                                &outbound_tx,
                                &overload_decision_to_error(&runtime_overload_decision),
                                &config.outbound,
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                &session_id,
                            ),
                            OutboundQueuePush::Disconnect
                        )
                    {
                        abort_with_resume!();
                    }
                    continue;
                }
                apply_overload_throttle(&runtime_overload_decision).await;
                let runtime_dispatch_started = Instant::now();
                let messages = session.handle_client_message(runtime_client_message.clone());
                overload_record_cpu_usage(
                    &config.overload,
                    &session_id,
                    runtime_tenant_id.as_deref(),
                    runtime_dispatch_started
                        .elapsed()
                        .as_millis()
                        .max(1)
                        .try_into()
                        .unwrap_or(u64::MAX),
                )
                .await;
                process_pubsub_commands(
                    session.drain_pubsub_commands(),
                    &config.pubsub,
                    &pubsub_tx,
                    &mut pubsub_tasks,
                    &mut subscribed_topics,
                    &session_id,
                    &config.distributed.node_id,
                    &config.telemetry,
                    &connection_correlation,
                );
                process_runtime_commands(
                    session.drain_runtime_commands(),
                    &runtime_tx,
                    &mut runtime_tasks,
                );
                if let (Some(lease), Some(active_resume_token)) =
                    (durable_lease.as_ref(), active_resume_token.as_deref())
                {
                    if !contains_server_error(&messages) {
                                if let Err(err) = durable_append_journal_entry(
                                    &config.durable,
                                    lease,
                                    &session_id,
                                    &runtime_client_message,
                                ) {
                                    let rejection = durable_error_message(&err);
                                    if matches!(
                                        queue_server_message(
                                            &outbound_tx,
                                            &rejection,
                                            &config.outbound,
                                            &config.telemetry,
                                            &connection_correlation,
                                            &config.route_path,
                                            &session_id,
                                        ),
                                        OutboundQueuePush::Disconnect
                                    ) {
                                        abort_with_resume!();
                                    }
                                    abort_with_resume!();
                                }
                        durable_save_snapshot(
                            &config.durable,
                            lease,
                            &session,
                            &current_route_pattern,
                            &config.target_id,
                            active_resume_token,
                        );
                    }
                }

                for message in messages {
                    match queue_server_message(
                        &outbound_tx,
                        &message,
                        &config.outbound,
                        &config.telemetry,
                        &connection_correlation,
                        &config.route_path,
                        &session_id,
                    ) {
                        OutboundQueuePush::Queued => {}
                        OutboundQueuePush::Dropped => {
                            warn!(
                                path = config.route_path,
                                session_id,
                                "Shelly websocket dropped runtime response due outbound backpressure"
                            );
                        }
                        OutboundQueuePush::Disconnect => {
                            warn!(
                                path = config.route_path,
                                session_id, "Shelly websocket closed while sending runtime response"
                            );
                            abort_with_resume!();
                        }
                    }
                }
            }
            result = receiver.next() => {
                let Some(result) = result else {
                    break;
                };

                let message = match result {
                    Ok(message) => message,
                    Err(err) => {
                        error!(?err, "websocket receive error");
                        break;
                    }
                };

                match message {
                    Message::Text(text) => {
                        let text = text.as_str();
                        if rate_limited(&config.security, &config.route_path, &session_id, "text") {
                            emit_security_audit(
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                Some(&session_id),
                                session.tenant_id(),
                                "rate_limiter",
                                false,
                                Some("rate_limited"),
                                SecurityOperation::Event,
                                "text",
                                None,
                                Some("rate limiter rejected text frame"),
                            );
                            warn!(
                                path = config.route_path,
                                session_id, "Shelly websocket rate limited text message"
                            );
                            if matches!(
                                queue_server_message(
                                    &outbound_tx,
                                    &rate_limited_error(),
                                    &config.outbound,
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    &session_id,
                                ),
                                OutboundQueuePush::Disconnect
                            ) {
                                abort_with_resume!();
                            }
                            continue;
                        }

                        if text.len() > config.max_message_size {
                            warn!(
                                path = config.route_path,
                                session_id,
                                size = text.len(),
                                max_message_size = config.max_message_size,
                                "Shelly websocket text payload too large"
                            );
                            let _ = queue_server_message(
                                &outbound_tx,
                                &payload_too_large_error(text.len(), config.max_message_size),
                                &config.outbound,
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                &session_id,
                            );
                            let _ = queue_close_frame(
                                &outbound_tx,
                                Some(payload_too_large_close()),
                                &config.outbound,
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                &session_id,
                            );
                            unregister_pubsub_presence(
                                &config.pubsub,
                                &subscribed_topics,
                                &session_id,
                                &config.distributed.node_id,
                            );
                            abort_pubsub_tasks(pubsub_tasks);
                            abort_runtime_tasks(runtime_tasks);
                            if let Some(task) = writer_task.take() {
                                let _ = timeout(Duration::from_millis(25), task).await;
                            }
                            durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
                            return;
                        }

                        let parsed_client_message = serde_json::from_str::<ClientMessage>(text);
                        log_ws_text_ingress(
                            &config.route_path,
                            &session_id,
                            text.len(),
                            parsed_client_message.as_ref(),
                            &connection_correlation,
                        );
                        let mut overload_tenant_id: Option<String> = None;
                        let mut overload_dispatch_started: Option<Instant> = None;
                        if let Ok(client_message) = parsed_client_message.as_ref() {
                            let (operation, event_name, event_target) =
                                security_operation_for_message(client_message);
                            let message_tenant_id = tenant_id_for_client_message(client_message);
                            if tenant_context_conflict(
                                session.tenant_id(),
                                message_tenant_id.as_deref(),
                            ) {
                                let rejection = ServerMessage::Error {
                                    message:
                                        "tenant context mismatch for session-bound message"
                                            .to_string(),
                                    code: Some("tenant_mismatch".to_string()),
                                };
                                emit_security_audit(
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    Some(&session_id),
                                    session.tenant_id(),
                                    "tenant_policy",
                                    false,
                                    Some("tenant_mismatch"),
                                    operation,
                                    "text",
                                    event_name,
                                    Some("message tenant_id does not match session tenant context"),
                                );
                                if matches!(
                                    queue_server_message(
                                        &outbound_tx,
                                        &rejection,
                                        &config.outbound,
                                        &config.telemetry,
                                        &connection_correlation,
                                        &config.route_path,
                                        &session_id,
                                    ),
                                    OutboundQueuePush::Disconnect
                                ) {
                                    abort_with_resume!();
                                }
                                continue;
                            }
                            let effective_tenant_id = effective_tenant_id_for_message(
                                session.tenant_id(),
                                message_tenant_id.as_deref(),
                            );
                            if let Some(rejection) = quota_denied(
                                &config.security,
                                &config.route_path,
                                &session_id,
                                effective_tenant_id.as_deref(),
                                "text",
                                operation,
                                event_name,
                            ) {
                                emit_security_audit(
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    Some(&session_id),
                                    effective_tenant_id.as_deref(),
                                    "quota_policy",
                                    false,
                                    Some("quota_exceeded"),
                                    operation,
                                    "text",
                                    event_name,
                                    Some("tenant/session quota policy rejected message"),
                                );
                                if matches!(
                                    queue_server_message(
                                        &outbound_tx,
                                        &rejection,
                                        &config.outbound,
                                        &config.telemetry,
                                        &connection_correlation,
                                        &config.route_path,
                                        &session_id,
                                    ),
                                    OutboundQueuePush::Disconnect
                                ) {
                                    abort_with_resume!();
                                }
                                continue;
                            }
                            if let Some(rejection) = authorization_denied(
                                &config.security,
                                AuthorizationInput {
                                    route_path: &config.route_path,
                                    session_id: &session_id,
                                    tenant_id: effective_tenant_id.as_deref(),
                                    message_kind: "text",
                                    operation,
                                    event_name,
                                    event_target,
                                },
                            ) {
                                emit_security_audit(
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    Some(&session_id),
                                    effective_tenant_id.as_deref(),
                                    "authorization_policy",
                                    false,
                                    Some("unauthorized"),
                                    operation,
                                    "text",
                                    event_name,
                                    Some("tenant/session authorization policy rejected message"),
                                );
                                if matches!(
                                    queue_server_message(
                                        &outbound_tx,
                                        &rejection,
                                        &config.outbound,
                                        &config.telemetry,
                                        &connection_correlation,
                                        &config.route_path,
                                        &session_id,
                                    ),
                                    OutboundQueuePush::Disconnect
                                ) {
                                    abort_with_resume!();
                                }
                                continue;
                            }
                            let overload_context = OverloadContext {
                                route_path: config.route_path.clone(),
                                session_id: session_id.clone(),
                                tenant_id: effective_tenant_id.clone(),
                                message_kind: "text",
                                operation,
                                event_name: event_name.map(ToString::to_string),
                                priority: overload_priority_for_client_message(client_message),
                                queue_depth: outbound_queue_depth(&outbound_tx, config.outbound.queue_capacity),
                                queue_capacity: config.outbound.queue_capacity,
                                inbound_bytes: text.len(),
                            };
                            let overload_decision =
                                overload_decision_for_dispatch(&config.overload, &overload_context).await;
                            emit_overload_telemetry(
                                &config.telemetry,
                                &connection_correlation,
                                &overload_context,
                                &overload_decision,
                            );
                            if !overload_decision.allowed {
                                warn!(
                                    path = config.route_path,
                                    session_id,
                                    priority = overload_context.priority.as_str(),
                                    reason = overload_decision.reason.as_deref().unwrap_or("shed"),
                                    "Shelly websocket message shed by overload policy"
                                );
                                if matches!(
                                    queue_server_message(
                                        &outbound_tx,
                                        &overload_decision_to_error(&overload_decision),
                                        &config.outbound,
                                        &config.telemetry,
                                        &connection_correlation,
                                        &config.route_path,
                                        &session_id,
                                    ),
                                    OutboundQueuePush::Disconnect
                                ) {
                                    abort_with_resume!();
                                }
                                continue;
                            }
                            apply_overload_throttle(&overload_decision).await;
                            overload_tenant_id = overload_context.tenant_id.clone();
                            overload_dispatch_started = Some(Instant::now());
                            if operation.is_mutating() {
                                emit_security_audit(
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    Some(&session_id),
                                    effective_tenant_id.as_deref(),
                                    "mutation_dispatch",
                                    true,
                                    Some("allowed"),
                                    operation,
                                    "text",
                                    event_name,
                                    Some("tenant/session policy accepted mutating operation"),
                                );
                            }
                        }
                        let journal_candidate = parsed_client_message.as_ref().ok().cloned();
                        let messages = messages_for_client_message_with_navigation(
                            &mut session,
                            parsed_client_message,
                            TextDispatch {
                                current_route_pattern: &mut current_route_pattern,
                                routes: &config.routes,
                                target_id: &config.target_id,
                                session_id: &session_id,
                                upload_config: &config.uploads,
                                uploads: &mut uploads,
                                telemetry: &session_telemetry,
                            },
                        )
                        .await;
                        if let Some(started) = overload_dispatch_started {
                            overload_record_cpu_usage(
                                &config.overload,
                                &session_id,
                                overload_tenant_id.as_deref(),
                                started
                                    .elapsed()
                                    .as_millis()
                                    .max(1)
                                    .try_into()
                                    .unwrap_or(u64::MAX),
                            )
                            .await;
                        }
                        process_pubsub_commands(
                            session.drain_pubsub_commands(),
                            &config.pubsub,
                            &pubsub_tx,
                            &mut pubsub_tasks,
                            &mut subscribed_topics,
                            &session_id,
                            &config.distributed.node_id,
                            &config.telemetry,
                            &connection_correlation,
                        );
                        process_runtime_commands(
                            session.drain_runtime_commands(),
                            &runtime_tx,
                            &mut runtime_tasks,
                        );
                        if let (Some(lease), Some(client_message), Some(active_resume_token)) = (
                            durable_lease.as_ref(),
                            journal_candidate.as_ref(),
                            active_resume_token.as_deref(),
                        ) {
                            if durable_message_should_journal(client_message)
                                && !contains_server_error(&messages)
                            {
                                if let Err(err) = durable_append_journal_entry(
                                    &config.durable,
                                    lease,
                                    &session_id,
                                    client_message,
                                ) {
                                    let rejection = durable_error_message(&err);
                                    if matches!(
                                        queue_server_message(
                                            &outbound_tx,
                                            &rejection,
                                            &config.outbound,
                                            &config.telemetry,
                                            &connection_correlation,
                                            &config.route_path,
                                            &session_id,
                                        ),
                                        OutboundQueuePush::Disconnect
                                    ) {
                                        abort_with_resume!();
                                    }
                                    abort_with_resume!();
                                }
                                durable_save_snapshot(
                                    &config.durable,
                                    lease,
                                    &session,
                                    &current_route_pattern,
                                    &config.target_id,
                                    active_resume_token,
                                );
                            }
                        }

                        for message in messages {
                            emit_upload_lifecycle_telemetry(
                                &config.telemetry,
                                session.session_id(),
                                session.route_path(),
                                &message,
                                &connection_correlation,
                            );
                            match queue_server_message(
                                &outbound_tx,
                                &message,
                                &config.outbound,
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                &session_id,
                            ) {
                                OutboundQueuePush::Queued => {}
                                OutboundQueuePush::Dropped => {
                                    warn!(
                                        path = config.route_path,
                                        session_id,
                                        "Shelly websocket dropped response due outbound backpressure"
                                    );
                                }
                                OutboundQueuePush::Disconnect => {
                                    warn!(
                                        path = config.route_path,
                                        session_id, "Shelly websocket closed while sending response"
                                    );
                                    abort_with_resume!();
                                }
                            }
                        }
                    }
                    Message::Binary(payload) if payload.len() > config.max_message_size => {
                        info!(
                            target: "shelly.incoming.ws",
                            schema = "shelly.incoming.ws.v1",
                            route = %config.route_path,
                            session_id,
                            trace_id = %connection_correlation.trace_id,
                            span_id = %connection_correlation.span_id,
                            parent_span_id = connection_correlation.parent_span_id.as_deref().unwrap_or("-"),
                            correlation_id = connection_correlation.correlation_id.as_deref().unwrap_or("-"),
                            request_id = connection_correlation.request_id.as_deref().unwrap_or("-"),
                            frame_kind = "binary",
                            bytes = payload.len(),
                            "Shelly websocket frame received"
                        );
                        if rate_limited(&config.security, &config.route_path, &session_id, "binary") {
                            emit_security_audit(
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                Some(&session_id),
                                session.tenant_id(),
                                "rate_limiter",
                                false,
                                Some("rate_limited"),
                                SecurityOperation::Binary,
                                "binary",
                                None,
                                Some("rate limiter rejected binary frame"),
                            );
                            warn!(
                                path = config.route_path,
                                session_id, "Shelly websocket rate limited binary message"
                            );
                            if matches!(
                                queue_server_message(
                                    &outbound_tx,
                                    &rate_limited_error(),
                                    &config.outbound,
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    &session_id,
                                ),
                                OutboundQueuePush::Disconnect
                            ) {
                                abort_with_resume!();
                            }
                            continue;
                        }

                        warn!(
                            path = config.route_path,
                            session_id,
                            size = payload.len(),
                            max_message_size = config.max_message_size,
                            "Shelly websocket binary payload too large"
                        );
                        let _ = queue_server_message(
                            &outbound_tx,
                            &payload_too_large_error(payload.len(), config.max_message_size),
                            &config.outbound,
                            &config.telemetry,
                            &connection_correlation,
                            &config.route_path,
                            &session_id,
                        );
                        let _ = queue_close_frame(
                            &outbound_tx,
                            Some(payload_too_large_close()),
                            &config.outbound,
                            &config.telemetry,
                            &connection_correlation,
                            &config.route_path,
                            &session_id,
                        );
                        abort_with_resume!();
                    }
                    Message::Binary(_) => {
                        info!(
                            target: "shelly.incoming.ws",
                            schema = "shelly.incoming.ws.v1",
                            route = %config.route_path,
                            session_id,
                            trace_id = %connection_correlation.trace_id,
                            span_id = %connection_correlation.span_id,
                            parent_span_id = connection_correlation.parent_span_id.as_deref().unwrap_or("-"),
                            correlation_id = connection_correlation.correlation_id.as_deref().unwrap_or("-"),
                            request_id = connection_correlation.request_id.as_deref().unwrap_or("-"),
                            frame_kind = "binary",
                            "Shelly websocket frame received"
                        );
                        if rate_limited(&config.security, &config.route_path, &session_id, "binary") {
                            emit_security_audit(
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                Some(&session_id),
                                session.tenant_id(),
                                "rate_limiter",
                                false,
                                Some("rate_limited"),
                                SecurityOperation::Binary,
                                "binary",
                                None,
                                Some("rate limiter rejected binary frame"),
                            );
                            warn!(
                                path = config.route_path,
                                session_id, "Shelly websocket rate limited binary message"
                            );
                            if matches!(
                                queue_server_message(
                                    &outbound_tx,
                                    &rate_limited_error(),
                                    &config.outbound,
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    &session_id,
                                ),
                                OutboundQueuePush::Disconnect
                            ) {
                                abort_with_resume!();
                            }
                            continue;
                        }
                        if let Some(rejection) = quota_denied(
                            &config.security,
                            &config.route_path,
                            &session_id,
                            session.tenant_id(),
                            "binary",
                            SecurityOperation::Binary,
                            None,
                        ) {
                            emit_security_audit(
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                Some(&session_id),
                                session.tenant_id(),
                                "quota_policy",
                                false,
                                Some("quota_exceeded"),
                                SecurityOperation::Binary,
                                "binary",
                                None,
                                Some("tenant/session quota policy rejected binary frame"),
                            );
                            if matches!(
                                queue_server_message(
                                    &outbound_tx,
                                    &rejection,
                                    &config.outbound,
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    &session_id,
                                ),
                                OutboundQueuePush::Disconnect
                            ) {
                                abort_with_resume!();
                            }
                            continue;
                        }
                        if let Some(rejection) = authorization_denied(
                            &config.security,
                            AuthorizationInput {
                                route_path: &config.route_path,
                                session_id: &session_id,
                                tenant_id: session.tenant_id(),
                                message_kind: "binary",
                                operation: SecurityOperation::Binary,
                                event_name: None,
                                event_target: None,
                            },
                        ) {
                            emit_security_audit(
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                Some(&session_id),
                                session.tenant_id(),
                                "authorization_policy",
                                false,
                                Some("unauthorized"),
                                SecurityOperation::Binary,
                                "binary",
                                None,
                                Some("tenant/session authorization policy rejected binary frame"),
                            );
                            if matches!(
                                queue_server_message(
                                    &outbound_tx,
                                    &rejection,
                                    &config.outbound,
                                    &config.telemetry,
                                    &connection_correlation,
                                    &config.route_path,
                                    &session_id,
                                ),
                                OutboundQueuePush::Disconnect
                            ) {
                                abort_with_resume!();
                            }
                            continue;
                        }

                        warn!(
                            path = config.route_path,
                            session_id, "Shelly websocket rejected binary message"
                        );
                        if matches!(
                            queue_server_message(
                                &outbound_tx,
                                &unsupported_binary_error(),
                                &config.outbound,
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                &session_id,
                            ),
                            OutboundQueuePush::Disconnect
                        ) {
                            abort_with_resume!();
                        }
                    }
                    Message::Ping(payload) => {
                        info!(
                            target: "shelly.incoming.ws",
                            schema = "shelly.incoming.ws.v1",
                            route = %config.route_path,
                            session_id,
                            trace_id = %connection_correlation.trace_id,
                            span_id = %connection_correlation.span_id,
                            parent_span_id = connection_correlation.parent_span_id.as_deref().unwrap_or("-"),
                            correlation_id = connection_correlation.correlation_id.as_deref().unwrap_or("-"),
                            request_id = connection_correlation.request_id.as_deref().unwrap_or("-"),
                            frame_kind = "ping",
                            bytes = payload.len(),
                            "Shelly websocket frame received"
                        );
                        if matches!(
                            queue_pong_frame(
                                &outbound_tx,
                                payload.to_vec(),
                                &config.outbound,
                                &config.telemetry,
                                &connection_correlation,
                                &config.route_path,
                                &session_id,
                            ),
                            OutboundQueuePush::Disconnect
                        ) {
                            abort_with_resume!();
                        }
                    }
                    Message::Close(frame) => {
                        info!(
                            target: "shelly.incoming.ws",
                            schema = "shelly.incoming.ws.v1",
                            route = %config.route_path,
                            session_id,
                            trace_id = %connection_correlation.trace_id,
                            span_id = %connection_correlation.span_id,
                            parent_span_id = connection_correlation.parent_span_id.as_deref().unwrap_or("-"),
                            correlation_id = connection_correlation.correlation_id.as_deref().unwrap_or("-"),
                            request_id = connection_correlation.request_id.as_deref().unwrap_or("-"),
                            frame_kind = "close",
                            close_frame = ?frame,
                            "Shelly websocket frame received"
                        );
                        break
                    }
                    Message::Pong(payload) => {
                        info!(
                            target: "shelly.incoming.ws",
                            schema = "shelly.incoming.ws.v1",
                            route = %config.route_path,
                            session_id,
                            trace_id = %connection_correlation.trace_id,
                            span_id = %connection_correlation.span_id,
                            parent_span_id = connection_correlation.parent_span_id.as_deref().unwrap_or("-"),
                            correlation_id = connection_correlation.correlation_id.as_deref().unwrap_or("-"),
                            request_id = connection_correlation.request_id.as_deref().unwrap_or("-"),
                            frame_kind = "pong",
                            bytes = payload.len(),
                            "Shelly websocket frame received"
                        );
                    }
                }
            }
        }
    }

    unregister_pubsub_presence(
        &config.pubsub,
        &subscribed_topics,
        &session_id,
        &config.distributed.node_id,
    );
    abort_pubsub_tasks(pubsub_tasks);
    abort_runtime_tasks(runtime_tasks);
    drop(outbound_tx);
    if let Some(task) = writer_task.take() {
        let _ = task.await;
    }
    let final_route_path = session.route_path().to_string();
    stash_reconnect_snapshot(
        &config.reconnect,
        session_id.clone(),
        session,
        current_route_pattern.clone(),
        active_resume_token.take(),
    )
    .await;
    durable_release_lease(&config.durable, &session_id, durable_lease.as_ref());
    info!(
        path = config.route_path,
        trace_id = %connection_correlation.trace_id,
        span_id = %connection_correlation.span_id,
        parent_span_id = connection_correlation.parent_span_id.as_deref().unwrap_or("-"),
        correlation_id = connection_correlation.correlation_id.as_deref().unwrap_or("-"),
        request_id = connection_correlation.request_id.as_deref().unwrap_or("-"),
        session_id, "Shelly websocket disconnected"
    );
    let _ = config.telemetry.emit(
        connection_correlation.apply_to_event(
            TelemetryEvent::new(TelemetryEventKind::Disconnect)
                .with_session(session_id)
                .with_route(final_route_path),
        ),
    );
}

#[allow(clippy::too_many_arguments)]
fn process_pubsub_commands(
    commands: Vec<PubSubCommand>,
    pubsub: &PubSub,
    sender: &mpsc::UnboundedSender<shelly::PubSubMessage>,
    tasks: &mut Vec<JoinHandle<()>>,
    subscribed_topics: &mut HashSet<String>,
    session_id: &str,
    node_id: &str,
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
) {
    for command in commands {
        match command {
            PubSubCommand::Subscribe { topic } => {
                if subscribed_topics.insert(topic.clone()) {
                    pubsub.register_presence(topic.clone(), session_id, node_id);
                    let mut subscription = pubsub.subscribe(topic);
                    let sender = sender.clone();
                    tasks.push(tokio::spawn(async move {
                        loop {
                            match subscription.recv().await {
                                Ok(message) => {
                                    if sender.send(message).is_err() {
                                        break;
                                    }
                                }
                                Err(shelly::PubSubReceiveError::Lagged(skipped)) => {
                                    warn!(skipped, "Shelly PubSub subscriber lagged");
                                }
                                Err(shelly::PubSubReceiveError::Closed) => break,
                            }
                        }
                    }));
                }
            }
            PubSubCommand::Broadcast { topic, messages } => {
                let message_count = messages.len();
                let recipients = pubsub.broadcast(topic.clone(), messages);
                let _ = telemetry.emit(
                    correlation.apply_to_event(
                        TelemetryEvent::new(TelemetryEventKind::PubSubFanout)
                            .with_ok(true)
                            .with_count(recipients)
                            .with_attribute("topic".to_string(), serde_json::Value::String(topic))
                            .with_attribute(
                                "message_count".to_string(),
                                JsonValue::Number(serde_json::Number::from(message_count)),
                            ),
                    ),
                );
            }
        }
    }
}

fn process_runtime_commands(
    commands: Vec<RuntimeCommand>,
    sender: &mpsc::UnboundedSender<shelly::RuntimeEvent>,
    tasks: &mut HashMap<String, JoinHandle<()>>,
) {
    tasks.retain(|_, task| !task.is_finished());

    for command in commands {
        match command {
            RuntimeCommand::ScheduleOnce {
                id,
                delay_ms,
                dispatch,
            } => {
                if let Some(task) = tasks.remove(&id) {
                    task.abort();
                }
                let sender = sender.clone();
                tasks.insert(
                    id,
                    tokio::spawn(async move {
                        tokio::time::sleep(Duration::from_millis(delay_ms)).await;
                        let _ = sender.send(dispatch);
                    }),
                );
            }
            RuntimeCommand::ScheduleInterval {
                id,
                every_ms,
                dispatch,
            } => {
                if let Some(task) = tasks.remove(&id) {
                    task.abort();
                }
                let sender = sender.clone();
                tasks.insert(
                    id,
                    tokio::spawn(async move {
                        let interval_ms = every_ms.max(1);
                        let mut interval = tokio::time::interval_at(
                            Instant::now() + Duration::from_millis(interval_ms),
                            Duration::from_millis(interval_ms),
                        );
                        interval.set_missed_tick_behavior(MissedTickBehavior::Delay);
                        loop {
                            interval.tick().await;
                            if sender.send(dispatch.clone()).is_err() {
                                break;
                            }
                        }
                    }),
                );
            }
            RuntimeCommand::Cancel { id } => {
                if let Some(task) = tasks.remove(&id) {
                    task.abort();
                }
            }
        }
    }
}

fn unregister_pubsub_presence(
    pubsub: &PubSub,
    subscribed_topics: &HashSet<String>,
    session_id: &str,
    node_id: &str,
) {
    for topic in subscribed_topics {
        pubsub.unregister_presence(topic.clone(), session_id.to_string(), node_id.to_string());
    }
}

fn abort_pubsub_tasks(tasks: Vec<JoinHandle<()>>) {
    for task in tasks {
        task.abort();
    }
}

fn abort_runtime_tasks(tasks: HashMap<String, JoinHandle<()>>) {
    for task in tasks.into_values() {
        task.abort();
    }
}

fn chrono_like_timestamp() -> String {
    use std::time::{SystemTime, UNIX_EPOCH};
    let millis = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis();
    format!("{millis}")
}

fn now_unix_ms() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|duration| duration.as_millis() as u64)
        .unwrap_or(0)
}

#[cfg(test)]
fn messages_for_text_payload(session: &mut LiveSession, text: &str) -> Vec<ServerMessage> {
    match serde_json::from_str::<ClientMessage>(text) {
        Ok(message) => session.handle_client_message(message),
        Err(err) => vec![ServerMessage::Error {
            message: format!("invalid protocol message: {err}"),
            code: Some("invalid_protocol".to_string()),
        }],
    }
}

#[derive(Debug)]
struct ClientMessageLogFields {
    message_type: &'static str,
    connect_session_id: Option<String>,
    connect_last_revision: Option<u64>,
    has_resume_token: Option<bool>,
    event_name: Option<String>,
    event_target: Option<String>,
    navigation_to: Option<String>,
    upload_id: Option<String>,
    upload_event: Option<String>,
}

fn client_message_log_fields(message: &ClientMessage) -> ClientMessageLogFields {
    match message {
        ClientMessage::Connect {
            session_id,
            last_revision,
            resume_token,
            ..
        } => ClientMessageLogFields {
            message_type: "connect",
            connect_session_id: session_id.clone(),
            connect_last_revision: *last_revision,
            has_resume_token: Some(
                resume_token
                    .as_ref()
                    .map(|token| !token.is_empty())
                    .unwrap_or(false),
            ),
            event_name: None,
            event_target: None,
            navigation_to: None,
            upload_id: None,
            upload_event: None,
        },
        ClientMessage::Event { event, target, .. } => ClientMessageLogFields {
            message_type: "event",
            connect_session_id: None,
            connect_last_revision: None,
            has_resume_token: None,
            event_name: Some(event.clone()),
            event_target: target.clone(),
            navigation_to: None,
            upload_id: None,
            upload_event: None,
        },
        ClientMessage::Ping { .. } => ClientMessageLogFields {
            message_type: "ping",
            connect_session_id: None,
            connect_last_revision: None,
            has_resume_token: None,
            event_name: None,
            event_target: None,
            navigation_to: None,
            upload_id: None,
            upload_event: None,
        },
        ClientMessage::PatchUrl { to } => ClientMessageLogFields {
            message_type: "patch_url",
            connect_session_id: None,
            connect_last_revision: None,
            has_resume_token: None,
            event_name: None,
            event_target: None,
            navigation_to: Some(to.clone()),
            upload_id: None,
            upload_event: None,
        },
        ClientMessage::Navigate { to } => ClientMessageLogFields {
            message_type: "navigate",
            connect_session_id: None,
            connect_last_revision: None,
            has_resume_token: None,
            event_name: None,
            event_target: None,
            navigation_to: Some(to.clone()),
            upload_id: None,
            upload_event: None,
        },
        ClientMessage::UploadStart {
            upload_id,
            event,
            target,
            ..
        } => ClientMessageLogFields {
            message_type: "upload_start",
            connect_session_id: None,
            connect_last_revision: None,
            has_resume_token: None,
            event_name: None,
            event_target: target.clone(),
            navigation_to: None,
            upload_id: Some(upload_id.clone()),
            upload_event: Some(event.clone()),
        },
        ClientMessage::UploadChunk { upload_id, .. } => ClientMessageLogFields {
            message_type: "upload_chunk",
            connect_session_id: None,
            connect_last_revision: None,
            has_resume_token: None,
            event_name: None,
            event_target: None,
            navigation_to: None,
            upload_id: Some(upload_id.clone()),
            upload_event: None,
        },
        ClientMessage::UploadComplete { upload_id } => ClientMessageLogFields {
            message_type: "upload_complete",
            connect_session_id: None,
            connect_last_revision: None,
            has_resume_token: None,
            event_name: None,
            event_target: None,
            navigation_to: None,
            upload_id: Some(upload_id.clone()),
            upload_event: None,
        },
    }
}

fn log_ws_text_ingress(
    route_path: &str,
    session_id: &str,
    payload_size: usize,
    message: Result<&ClientMessage, &serde_json::Error>,
    correlation: &CorrelationContext,
) {
    match message {
        Ok(message) => {
            let fields = client_message_log_fields(message);
            info!(
                target: "shelly.incoming.ws",
                schema = "shelly.incoming.ws.v1",
                route = route_path,
                session_id,
                trace_id = %correlation.trace_id,
                span_id = %correlation.span_id,
                parent_span_id = correlation.parent_span_id.as_deref().unwrap_or("-"),
                correlation_id = correlation.correlation_id.as_deref().unwrap_or("-"),
                request_id = correlation.request_id.as_deref().unwrap_or("-"),
                frame_kind = "text",
                bytes = payload_size,
                protocol_message_type = fields.message_type,
                connect_session_id = ?fields.connect_session_id,
                connect_last_revision = ?fields.connect_last_revision,
                has_resume_token = ?fields.has_resume_token,
                event_name = ?fields.event_name,
                event_target = ?fields.event_target,
                navigation_to = ?fields.navigation_to,
                upload_id = ?fields.upload_id,
                upload_event = ?fields.upload_event,
                "Shelly websocket frame received"
            );
        }
        Err(err) => {
            warn!(
                target: "shelly.incoming.ws",
                schema = "shelly.incoming.ws.v1",
                route = route_path,
                session_id,
                trace_id = %correlation.trace_id,
                span_id = %correlation.span_id,
                parent_span_id = correlation.parent_span_id.as_deref().unwrap_or("-"),
                correlation_id = correlation.correlation_id.as_deref().unwrap_or("-"),
                request_id = correlation.request_id.as_deref().unwrap_or("-"),
                frame_kind = "text",
                bytes = payload_size,
                protocol_message_type = "invalid_protocol",
                parse_error = %err,
                "Shelly websocket frame failed protocol parsing"
            );
        }
    }
}

async fn messages_for_client_message_with_navigation(
    session: &mut LiveSession,
    message: Result<ClientMessage, serde_json::Error>,
    dispatch: TextDispatch<'_>,
) -> Vec<ServerMessage> {
    match message {
        Ok(ClientMessage::PatchUrl { to }) => handle_patch_url(
            session,
            dispatch.current_route_pattern,
            dispatch.routes,
            &to,
        ),
        Ok(ClientMessage::Navigate { to }) => handle_navigate(
            session,
            dispatch.current_route_pattern,
            dispatch.routes,
            dispatch.target_id,
            dispatch.session_id,
            dispatch.telemetry,
            &to,
        ),
        Ok(ClientMessage::UploadStart {
            upload_id,
            event,
            target,
            name,
            size,
            content_type,
        }) => {
            handle_upload_start(
                dispatch.uploads,
                dispatch.upload_config,
                UploadStartRequest {
                    upload_id,
                    event,
                    target,
                    name,
                    size,
                    content_type,
                },
            )
            .await
        }
        Ok(ClientMessage::UploadChunk {
            upload_id,
            offset,
            data,
        }) => handle_upload_chunk(dispatch.uploads, &upload_id, offset, &data).await,
        Ok(ClientMessage::UploadComplete { upload_id }) => {
            handle_upload_complete(session, dispatch.uploads, &upload_id).await
        }
        Ok(message) => session.handle_client_message(message),
        Err(err) => vec![ServerMessage::Error {
            message: format!("invalid protocol message: {err}"),
            code: Some("invalid_protocol".to_string()),
        }],
    }
}

async fn handle_upload_start(
    uploads: &mut HashMap<String, UploadEntry>,
    config: &UploadConfig,
    request: UploadStartRequest,
) -> Vec<ServerMessage> {
    if request.size > config.max_file_size {
        return vec![upload_error(
            request.upload_id,
            "upload exceeds configured size limit",
            "upload_too_large",
        )];
    }

    if !upload_content_type_allowed(config, request.content_type.as_deref()) {
        return vec![upload_error(
            request.upload_id,
            "upload content type is not allowed",
            "upload_type_not_allowed",
        )];
    }

    if let Err(err) = tokio::fs::create_dir_all(config.temp_dir.as_ref()).await {
        return vec![upload_error(
            request.upload_id,
            format!("upload temp directory failed: {err}"),
            "upload_temp_failed",
        )];
    }

    let path = config
        .temp_dir
        .join(format!("{}.upload", request.upload_id));
    let file = match tokio::fs::File::create(&path).await {
        Ok(file) => file,
        Err(err) => {
            return vec![upload_error(
                request.upload_id,
                format!("upload temp file failed: {err}"),
                "upload_temp_failed",
            )];
        }
    };

    let upload_id = request.upload_id;
    let size = request.size;
    uploads.insert(
        upload_id.clone(),
        UploadEntry {
            event: request.event,
            target: request.target,
            name: request.name,
            size,
            content_type: request.content_type,
            path,
            file,
            received: 0,
        },
    );

    vec![ServerMessage::UploadProgress {
        upload_id,
        received: 0,
        total: size,
    }]
}

async fn handle_upload_chunk(
    uploads: &mut HashMap<String, UploadEntry>,
    upload_id: &str,
    offset: u64,
    data: &str,
) -> Vec<ServerMessage> {
    let Some(entry) = uploads.get_mut(upload_id) else {
        return vec![upload_error(
            upload_id,
            "unknown upload",
            "upload_not_found",
        )];
    };

    if offset != entry.received {
        return vec![upload_error(
            upload_id,
            "upload chunk offset is out of order",
            "upload_offset_mismatch",
        )];
    }

    let bytes = match STANDARD.decode(data) {
        Ok(bytes) => bytes,
        Err(_) => {
            return vec![upload_error(
                upload_id,
                "upload chunk is not valid base64",
                "upload_invalid_chunk",
            )];
        }
    };

    let next_received = entry.received + bytes.len() as u64;
    if next_received > entry.size {
        return vec![upload_error(
            upload_id,
            "upload chunk exceeds negotiated size",
            "upload_too_large",
        )];
    }

    if let Err(err) = entry.file.write_all(&bytes).await {
        return vec![upload_error(
            upload_id,
            format!("upload chunk write failed: {err}"),
            "upload_write_failed",
        )];
    }

    entry.received = next_received;
    vec![ServerMessage::UploadProgress {
        upload_id: upload_id.to_string(),
        received: entry.received,
        total: entry.size,
    }]
}

async fn handle_upload_complete(
    session: &mut LiveSession,
    uploads: &mut HashMap<String, UploadEntry>,
    upload_id: &str,
) -> Vec<ServerMessage> {
    let Some(mut entry) = uploads.remove(upload_id) else {
        return vec![upload_error(
            upload_id,
            "unknown upload",
            "upload_not_found",
        )];
    };

    if entry.received != entry.size {
        let _ = tokio::fs::remove_file(&entry.path).await;
        return vec![upload_error(
            upload_id,
            "upload completed before all bytes were received",
            "upload_incomplete",
        )];
    }

    if let Err(err) = entry.file.flush().await {
        let _ = tokio::fs::remove_file(&entry.path).await;
        return vec![upload_error(
            upload_id,
            format!("upload flush failed: {err}"),
            "upload_write_failed",
        )];
    }

    let mut messages = vec![ServerMessage::UploadComplete {
        upload_id: upload_id.to_string(),
        name: entry.name.clone(),
        size: entry.size,
        content_type: entry.content_type.clone(),
    }];
    messages.extend(session.handle_client_message(ClientMessage::Event {
        event: entry.event,
        target: entry.target,
        value: serde_json::json!({
            "upload_id": upload_id,
            "name": entry.name,
            "size": entry.size,
            "content_type": entry.content_type,
            "path": entry.path.display().to_string(),
        }),
        metadata: serde_json::Map::from_iter([
            (
                "tag".to_string(),
                serde_json::Value::String("INPUT".to_string()),
            ),
            (
                "name".to_string(),
                serde_json::Value::String("upload".to_string()),
            ),
        ]),
    }));
    messages
}

fn upload_content_type_allowed(config: &UploadConfig, content_type: Option<&str>) -> bool {
    config.allowed_content_types.is_empty()
        || content_type
            .map(|value| {
                config
                    .allowed_content_types
                    .iter()
                    .any(|allowed| allowed == value)
            })
            .unwrap_or(false)
}

fn upload_error(
    upload_id: impl Into<String>,
    message: impl Into<String>,
    code: impl Into<String>,
) -> ServerMessage {
    ServerMessage::UploadError {
        upload_id: upload_id.into(),
        message: message.into(),
        code: Some(code.into()),
    }
}

fn emit_upload_lifecycle_telemetry(
    telemetry: &Arc<TelemetryPipeline>,
    session_id: &str,
    route_path: &str,
    message: &ServerMessage,
    correlation: &CorrelationContext,
) {
    let Some(event) = upload_lifecycle_event(session_id, route_path, message, correlation) else {
        return;
    };
    let _ = telemetry.emit(event);
}

fn upload_lifecycle_event(
    session_id: &str,
    route_path: &str,
    message: &ServerMessage,
    correlation: &CorrelationContext,
) -> Option<TelemetryEvent> {
    let event = match message {
        ServerMessage::UploadProgress {
            upload_id,
            received,
            total,
        } => {
            let phase = if *received == 0 { "start" } else { "progress" };
            TelemetryEvent::new(TelemetryEventKind::UploadLifecycle)
                .with_session(session_id.to_string())
                .with_route(route_path.to_string())
                .with_ok(true)
                .with_bytes(*received as usize)
                .with_count(1)
                .with_attribute("phase".to_string(), JsonValue::String(phase.to_string()))
                .with_attribute(
                    "upload_id".to_string(),
                    JsonValue::String(upload_id.clone()),
                )
                .with_attribute(
                    "received".to_string(),
                    JsonValue::Number(serde_json::Number::from(*received)),
                )
                .with_attribute(
                    "total".to_string(),
                    JsonValue::Number(serde_json::Number::from(*total)),
                )
        }
        ServerMessage::UploadComplete {
            upload_id,
            name,
            size,
            content_type,
        } => TelemetryEvent::new(TelemetryEventKind::UploadLifecycle)
            .with_session(session_id.to_string())
            .with_route(route_path.to_string())
            .with_ok(true)
            .with_bytes(*size as usize)
            .with_count(1)
            .with_attribute(
                "phase".to_string(),
                JsonValue::String("complete".to_string()),
            )
            .with_attribute(
                "upload_id".to_string(),
                JsonValue::String(upload_id.clone()),
            )
            .with_attribute("name".to_string(), JsonValue::String(name.clone()))
            .with_attribute("size".to_string(), JsonValue::Number((*size).into()))
            .with_attribute(
                "content_type".to_string(),
                content_type
                    .as_ref()
                    .map(|value| JsonValue::String(value.clone()))
                    .unwrap_or(JsonValue::Null),
            ),
        ServerMessage::UploadError {
            upload_id,
            code,
            message,
        } => TelemetryEvent::new(TelemetryEventKind::UploadLifecycle)
            .with_session(session_id.to_string())
            .with_route(route_path.to_string())
            .with_ok(false)
            .with_count(1)
            .with_attribute("phase".to_string(), JsonValue::String("error".to_string()))
            .with_attribute(
                "upload_id".to_string(),
                JsonValue::String(upload_id.clone()),
            )
            .with_attribute("message".to_string(), JsonValue::String(message.clone()))
            .with_attribute(
                "code".to_string(),
                code.as_ref()
                    .map(|value| JsonValue::String(value.clone()))
                    .unwrap_or(JsonValue::Null),
            ),
        _ => return None,
    };

    Some(correlation.apply_to_event(event))
}

fn handle_patch_url(
    session: &mut LiveSession,
    current_route_pattern: &mut String,
    routes: &[LiveRoute],
    to: &str,
) -> Vec<ServerMessage> {
    let Some(path) = internal_path(to) else {
        return vec![navigation_error(
            "invalid_navigation",
            format!("internal navigation requires an absolute path: {to}"),
        )];
    };

    let Some(route) = routes.iter().find_map(|route| route.match_path(&path)) else {
        return vec![navigation_error(
            "navigation_route_not_found",
            format!("no Shelly route registered for {path}"),
        )];
    };

    if route.pattern != *current_route_pattern {
        return vec![navigation_error(
            "navigation_route_mismatch",
            format!(
                "shelly-patch cannot switch from {current_route_pattern} to {}",
                route.pattern
            ),
        )];
    }

    if let Err(err) = session.patch_route(route.path, route.params) {
        return vec![ServerMessage::Error {
            message: err.to_string(),
            code: Some("route_patch_failed".to_string()),
        }];
    }

    vec![
        ServerMessage::PatchUrl { to: to.to_string() },
        session.render_update(),
    ]
}

fn handle_navigate(
    session: &mut LiveSession,
    current_route_pattern: &mut String,
    routes: &[LiveRoute],
    target_id: &str,
    session_id: &str,
    telemetry: &Arc<dyn TelemetrySink>,
    to: &str,
) -> Vec<ServerMessage> {
    let Some(path) = internal_path(to) else {
        return vec![navigation_error(
            "invalid_navigation",
            format!("internal navigation requires an absolute path: {to}"),
        )];
    };

    let Some(route) = routes.iter().find_map(|route| route.match_path(&path)) else {
        return vec![navigation_error(
            "navigation_route_not_found",
            format!("no Shelly route registered for {path}"),
        )];
    };

    let mut next = LiveSession::new_with_route_and_session_id(
        (route.factory)(),
        session_id.to_string(),
        target_id.to_string(),
        route.path,
        route.params,
    );
    next.set_telemetry_sink(telemetry.clone());
    if let Err(err) = next.mount() {
        return vec![ServerMessage::Error {
            message: format!("navigation mount failed: {err}"),
            code: Some("navigation_failed".to_string()),
        }];
    }

    *current_route_pattern = route.pattern;
    *session = next;
    vec![
        ServerMessage::Navigate { to: to.to_string() },
        session.hello(),
        session.render_patch(),
    ]
}

fn internal_path(to: &str) -> Option<String> {
    if !to.starts_with('/') || to.starts_with("//") {
        return None;
    }

    let path = to
        .split(['?', '#'])
        .next()
        .filter(|path| !path.is_empty())?;
    Some(normalize_path(path.to_string()))
}

fn navigation_error(code: impl Into<String>, message: impl Into<String>) -> ServerMessage {
    ServerMessage::Error {
        message: message.into(),
        code: Some(code.into()),
    }
}

fn parse_query(query: &str) -> HashMap<String, String> {
    query
        .split('&')
        .filter(|part| !part.is_empty())
        .filter_map(|part| {
            let (key, value) = part.split_once('=')?;
            Some((percent_decode(key)?, percent_decode(value)?))
        })
        .collect()
}

fn percent_decode(value: &str) -> Option<String> {
    let bytes = value.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
    let mut index = 0;

    while index < bytes.len() {
        match bytes[index] {
            b'+' => {
                out.push(b' ');
                index += 1;
            }
            b'%' => {
                if index + 2 >= bytes.len() {
                    return None;
                }
                let high = from_hex(bytes[index + 1])?;
                let low = from_hex(bytes[index + 2])?;
                out.push((high << 4) | low);
                index += 3;
            }
            byte => {
                out.push(byte);
                index += 1;
            }
        }
    }

    String::from_utf8(out).ok()
}

fn from_hex(byte: u8) -> Option<u8> {
    match byte {
        b'0'..=b'9' => Some(byte - b'0'),
        b'a'..=b'f' => Some(byte - b'a' + 10),
        b'A'..=b'F' => Some(byte - b'A' + 10),
        _ => None,
    }
}

fn verify_websocket_tokens(
    signer: &TokenSigner,
    query: &HashMap<String, String>,
    route_path: &str,
) -> Option<SignedSession> {
    let session = signer.verify_session(query.get("session")?)?;
    if session.path != route_path {
        return None;
    }

    let csrf = query.get("csrf")?;
    if !signer.verify_csrf(csrf, &session.session_id, route_path) {
        return None;
    }

    Some(session)
}

fn origin_allowed(headers: &HeaderMap, security: &SecurityConfig) -> bool {
    let Some(origin) = headers
        .get(header::ORIGIN)
        .and_then(|value| value.to_str().ok())
    else {
        return true;
    };

    if security
        .allowed_origins
        .iter()
        .any(|allowed| allowed == origin)
    {
        return true;
    }

    let Some(host) = headers
        .get(header::HOST)
        .and_then(|value| value.to_str().ok())
    else {
        return false;
    };

    origin == format!("http://{host}") || origin == format!("https://{host}")
}

fn security_operation_for_message(
    message: &ClientMessage,
) -> (SecurityOperation, Option<&str>, Option<&str>) {
    match message {
        ClientMessage::Connect { .. } => (SecurityOperation::Connect, None, None),
        ClientMessage::Event { event, target, .. } => (
            SecurityOperation::Event,
            Some(event.as_str()),
            target.as_deref(),
        ),
        ClientMessage::Ping { .. } => (SecurityOperation::Ping, None, None),
        ClientMessage::PatchUrl { .. } => (SecurityOperation::PatchUrl, None, None),
        ClientMessage::Navigate { .. } => (SecurityOperation::Navigate, None, None),
        ClientMessage::UploadStart { event, target, .. } => (
            SecurityOperation::UploadStart,
            Some(event.as_str()),
            target.as_deref(),
        ),
        ClientMessage::UploadChunk { .. } => (SecurityOperation::UploadChunk, None, None),
        ClientMessage::UploadComplete { .. } => (SecurityOperation::UploadComplete, None, None),
    }
}

struct AuthorizationInput<'a> {
    route_path: &'a str,
    session_id: &'a str,
    tenant_id: Option<&'a str>,
    message_kind: &'static str,
    operation: SecurityOperation,
    event_name: Option<&'a str>,
    event_target: Option<&'a str>,
}

fn authorization_denied(
    security: &SecurityConfig,
    input: AuthorizationInput<'_>,
) -> Option<ServerMessage> {
    let hook = security.authorization.as_ref()?;
    let decision = hook(&AuthorizationContext {
        route_path: input.route_path.to_string(),
        session_id: input.session_id.to_string(),
        tenant_id: input.tenant_id.map(ToString::to_string),
        message_kind: input.message_kind,
        operation: input.operation,
        event_name: input.event_name.map(ToString::to_string),
        event_target: input.event_target.map(ToString::to_string),
    });
    if decision.allowed {
        None
    } else {
        Some(ServerMessage::Error {
            message: decision
                .message
                .unwrap_or_else(|| "authorization policy rejected message".to_string()),
            code: Some(decision.code.unwrap_or_else(|| "unauthorized".to_string())),
        })
    }
}

fn quota_denied(
    security: &SecurityConfig,
    route_path: &str,
    session_id: &str,
    tenant_id: Option<&str>,
    message_kind: &'static str,
    operation: SecurityOperation,
    event_name: Option<&str>,
) -> Option<ServerMessage> {
    let hook = security.quota_policy.as_ref()?;
    let decision = hook(&QuotaContext {
        route_path: route_path.to_string(),
        session_id: session_id.to_string(),
        tenant_id: tenant_id.map(ToString::to_string),
        message_kind,
        operation,
        event_name: event_name.map(ToString::to_string),
    });
    if decision.allowed {
        None
    } else {
        Some(ServerMessage::Error {
            message: decision
                .message
                .unwrap_or_else(|| "quota policy rejected message".to_string()),
            code: Some(
                decision
                    .code
                    .unwrap_or_else(|| "quota_exceeded".to_string()),
            ),
        })
    }
}

fn overload_priority_for_client_message(message: &ClientMessage) -> OverloadPriority {
    match message {
        ClientMessage::Event {
            event, metadata, ..
        } => {
            let metadata_priority = metadata
                .get("priority")
                .and_then(JsonValue::as_str)
                .map(|value| value.trim().to_ascii_lowercase());
            if matches!(metadata_priority.as_deref(), Some("background"))
                || event.starts_with("bg:")
                || event.starts_with("cron:")
            {
                OverloadPriority::Background
            } else {
                OverloadPriority::Interactive
            }
        }
        _ => OverloadPriority::Interactive,
    }
}

fn tenant_id_for_client_message(message: &ClientMessage) -> Option<String> {
    match message {
        ClientMessage::Connect { tenant_id, .. } => normalize_tenant_id(tenant_id.clone()),
        ClientMessage::Event {
            metadata, value, ..
        } => metadata
            .get("tenant_id")
            .and_then(JsonValue::as_str)
            .or_else(|| value.get("tenant_id").and_then(JsonValue::as_str))
            .and_then(|value| normalize_tenant_id(Some(value.to_string()))),
        _ => None,
    }
}

fn normalize_tenant_id(tenant_id: Option<String>) -> Option<String> {
    tenant_id
        .map(|value| value.trim().to_string())
        .filter(|value| !value.is_empty())
}

fn normalize_tenant_id_ref(tenant_id: Option<&str>) -> Option<String> {
    tenant_id
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .map(ToString::to_string)
}

fn tenant_context_conflict(
    session_tenant_id: Option<&str>,
    message_tenant_id: Option<&str>,
) -> bool {
    match (
        normalize_tenant_id_ref(session_tenant_id),
        normalize_tenant_id_ref(message_tenant_id),
    ) {
        (Some(session_tenant), Some(message_tenant)) => session_tenant != message_tenant,
        _ => false,
    }
}

fn effective_tenant_id_for_message(
    session_tenant_id: Option<&str>,
    message_tenant_id: Option<&str>,
) -> Option<String> {
    normalize_tenant_id_ref(message_tenant_id)
        .or_else(|| normalize_tenant_id_ref(session_tenant_id))
}

fn outbound_queue_depth(sender: &mpsc::Sender<OutboundEnvelope>, queue_capacity: usize) -> usize {
    queue_capacity.saturating_sub(sender.capacity())
}

fn overload_saturation_reason(
    session_saturated: bool,
    tenant_saturated: bool,
    queue_saturated: bool,
) -> String {
    let mut reasons = Vec::new();
    if queue_saturated {
        reasons.push("queue_depth");
    }
    if session_saturated {
        reasons.push("session_budget");
    }
    if tenant_saturated {
        reasons.push("tenant_budget");
    }
    if reasons.is_empty() {
        "none".to_string()
    } else {
        reasons.join("+")
    }
}

async fn overload_decision_for_dispatch(
    overload: &OverloadConfig,
    context: &OverloadContext,
) -> OverloadDecision {
    let mut state = overload.state.lock().await;
    let now = Instant::now();
    let (projected_session_bytes, projected_session_cpu_ms, projected_session_queue) = {
        let session_window = state
            .session_windows
            .entry(context.session_id.clone())
            .or_insert_with(|| OverloadBudgetWindow::new(now));
        session_window.roll_window_if_needed(now, overload.window);
        (
            session_window.bytes.saturating_add(context.inbound_bytes),
            session_window.cpu_ms,
            session_window.queue_depth_peak.max(context.queue_depth),
        )
    };
    let session_saturated = projected_session_queue > overload.budgets.session_queue_depth
        || projected_session_bytes > overload.budgets.session_bytes_per_sec
        || projected_session_cpu_ms > overload.budgets.session_cpu_ms_per_sec;

    let mut tenant_saturated = false;
    if let Some(tenant_id) = context.tenant_id.as_deref() {
        let tenant_window = state
            .tenant_windows
            .entry(tenant_id.to_string())
            .or_insert_with(|| OverloadBudgetWindow::new(now));
        tenant_window.roll_window_if_needed(now, overload.window);
        let projected_tenant_bytes = tenant_window.bytes.saturating_add(context.inbound_bytes);
        let projected_tenant_cpu_ms = tenant_window.cpu_ms;
        let projected_tenant_queue = tenant_window.queue_depth_peak.max(context.queue_depth);
        tenant_saturated = projected_tenant_queue > overload.budgets.tenant_queue_depth
            || projected_tenant_bytes > overload.budgets.tenant_bytes_per_sec
            || projected_tenant_cpu_ms > overload.budgets.tenant_cpu_ms_per_sec;
    }

    let queue_saturated = context.queue_depth >= context.queue_capacity;
    let saturated = queue_saturated || session_saturated || tenant_saturated;
    let saturation_reason =
        overload_saturation_reason(session_saturated, tenant_saturated, queue_saturated);

    let base_decision = if !saturated {
        OverloadDecision::allow()
    } else if context.priority == OverloadPriority::Background
        && overload.shed_policy == OverloadShedPolicy::PreferInteractive
    {
        OverloadDecision::shed(format!("background_shed:{saturation_reason}"))
    } else if queue_saturated || overload.shed_policy == OverloadShedPolicy::Strict {
        OverloadDecision::shed(format!("shed:{saturation_reason}"))
    } else {
        OverloadDecision::throttle(10, format!("throttle:{saturation_reason}"))
    };

    let decision = if let Some(policy_hook) = overload.policy_hook.as_ref() {
        policy_hook(context, &base_decision)
    } else {
        base_decision
    };

    if decision.allowed {
        let session_window = state
            .session_windows
            .entry(context.session_id.clone())
            .or_insert_with(|| OverloadBudgetWindow::new(now));
        session_window.roll_window_if_needed(now, overload.window);
        session_window.events = session_window.events.saturating_add(1);
        session_window.bytes = session_window.bytes.saturating_add(context.inbound_bytes);
        session_window.queue_depth_peak = session_window.queue_depth_peak.max(context.queue_depth);

        if let Some(tenant_id) = context.tenant_id.as_deref() {
            let tenant_window = state
                .tenant_windows
                .entry(tenant_id.to_string())
                .or_insert_with(|| OverloadBudgetWindow::new(now));
            tenant_window.roll_window_if_needed(now, overload.window);
            tenant_window.events = tenant_window.events.saturating_add(1);
            tenant_window.bytes = tenant_window.bytes.saturating_add(context.inbound_bytes);
            tenant_window.queue_depth_peak =
                tenant_window.queue_depth_peak.max(context.queue_depth);
        }
    }

    decision
}

async fn overload_record_cpu_usage(
    overload: &OverloadConfig,
    session_id: &str,
    tenant_id: Option<&str>,
    cpu_ms: u64,
) {
    let mut state = overload.state.lock().await;
    let now = Instant::now();

    let session_window = state
        .session_windows
        .entry(session_id.to_string())
        .or_insert_with(|| OverloadBudgetWindow::new(now));
    session_window.roll_window_if_needed(now, overload.window);
    session_window.cpu_ms = session_window.cpu_ms.saturating_add(cpu_ms);

    if let Some(tenant_id) = tenant_id {
        let tenant_window = state
            .tenant_windows
            .entry(tenant_id.to_string())
            .or_insert_with(|| OverloadBudgetWindow::new(now));
        tenant_window.roll_window_if_needed(now, overload.window);
        tenant_window.cpu_ms = tenant_window.cpu_ms.saturating_add(cpu_ms);
    }
}

fn overload_decision_to_error(decision: &OverloadDecision) -> ServerMessage {
    ServerMessage::Error {
        message: decision
            .message
            .clone()
            .unwrap_or_else(|| "server overloaded".to_string()),
        code: decision.code.clone(),
    }
}

fn overload_telemetry_event(
    correlation: &CorrelationContext,
    context: &OverloadContext,
    decision: &OverloadDecision,
) -> Option<TelemetryEvent> {
    if decision.allowed && decision.throttle_ms == 0 {
        return None;
    }
    let action = if !decision.allowed {
        "shed"
    } else if decision.throttle_ms > 0 {
        "throttle"
    } else {
        "allow"
    };
    let mut event = TelemetryEvent::new(TelemetryEventKind::Error)
        .with_session(context.session_id.clone())
        .with_route(context.route_path.clone())
        .with_ok(decision.allowed)
        .with_attribute(
            "phase".to_string(),
            JsonValue::String("overload_control".to_string()),
        )
        .with_attribute("action".to_string(), JsonValue::String(action.to_string()))
        .with_attribute(
            "priority".to_string(),
            JsonValue::String(context.priority.as_str().to_string()),
        )
        .with_attribute(
            "queue_depth".to_string(),
            JsonValue::Number(serde_json::Number::from(context.queue_depth)),
        )
        .with_attribute(
            "queue_capacity".to_string(),
            JsonValue::Number(serde_json::Number::from(context.queue_capacity)),
        )
        .with_attribute(
            "inbound_bytes".to_string(),
            JsonValue::Number(serde_json::Number::from(context.inbound_bytes)),
        );
    if decision.throttle_ms > 0 {
        event = event.with_latency_ms(decision.throttle_ms);
    }
    if let Some(event_name) = context.event_name.as_ref() {
        event = event.with_event_name(event_name.clone());
    }
    if let Some(tenant_id) = context.tenant_id.as_ref() {
        event = event.with_attribute(
            "tenant_id".to_string(),
            JsonValue::String(tenant_id.clone()),
        );
    }
    if let Some(reason) = decision.reason.as_ref() {
        event = event.with_attribute("reason".to_string(), JsonValue::String(reason.clone()));
    }
    Some(correlation.apply_to_event(event))
}

fn emit_overload_telemetry(
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    context: &OverloadContext,
    decision: &OverloadDecision,
) {
    if let Some(event) = overload_telemetry_event(correlation, context, decision) {
        let _ = telemetry.emit(event);
    }
}

async fn apply_overload_throttle(decision: &OverloadDecision) {
    if decision.allowed && decision.throttle_ms > 0 {
        sleep(Duration::from_millis(decision.throttle_ms)).await;
    }
}

#[allow(clippy::too_many_arguments)]
fn security_audit_event(
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: Option<&str>,
    tenant_id: Option<&str>,
    control: &'static str,
    ok: bool,
    code: Option<&str>,
    operation: SecurityOperation,
    message_kind: &'static str,
    event_name: Option<&str>,
    policy_reason: Option<&str>,
) -> TelemetryEvent {
    let mut event = TelemetryEvent::new(TelemetryEventKind::SecurityAudit)
        .with_route(route_path.to_string())
        .with_ok(ok)
        .with_count(1)
        .with_attribute(
            "control".to_string(),
            JsonValue::String(control.to_string()),
        )
        .with_attribute(
            "operation".to_string(),
            JsonValue::String(operation.as_str().to_string()),
        )
        .with_attribute(
            "message_kind".to_string(),
            JsonValue::String(message_kind.to_string()),
        );

    if let Some(session_id) = session_id {
        event = event.with_session(session_id.to_string());
    }
    if let Some(tenant_id) = tenant_id {
        event = event.with_attribute(
            "tenant_id".to_string(),
            JsonValue::String(tenant_id.to_string()),
        );
    }
    if let Some(code) = code {
        event = event.with_attribute("code".to_string(), JsonValue::String(code.to_string()));
    }
    if let Some(event_name) = event_name {
        event = event.with_event_name(event_name.to_string());
    }
    if let Some(policy_reason) = policy_reason {
        event = event.with_attribute(
            "policy_reason".to_string(),
            JsonValue::String(policy_reason.to_string()),
        );
    }

    correlation.apply_to_event(event)
}

#[allow(clippy::too_many_arguments)]
fn emit_security_audit(
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: Option<&str>,
    tenant_id: Option<&str>,
    control: &'static str,
    ok: bool,
    code: Option<&str>,
    operation: SecurityOperation,
    message_kind: &'static str,
    event_name: Option<&str>,
    policy_reason: Option<&str>,
) {
    let _ = telemetry.emit(security_audit_event(
        correlation,
        route_path,
        session_id,
        tenant_id,
        control,
        ok,
        code,
        operation,
        message_kind,
        event_name,
        policy_reason,
    ));
}

fn rate_limited(
    security: &SecurityConfig,
    route_path: &str,
    session_id: &str,
    message_kind: &'static str,
) -> bool {
    let Some(rate_limiter) = &security.rate_limiter else {
        return false;
    };

    !rate_limiter(&RateLimitContext {
        route_path: route_path.to_string(),
        session_id: session_id.to_string(),
        message_kind,
    })
}

fn payload_too_large_error(size: usize, max_message_size: usize) -> ServerMessage {
    ServerMessage::Error {
        message: format!("payload too large: {size} bytes exceeds {max_message_size} byte limit"),
        code: Some("payload_too_large".to_string()),
    }
}

fn unsupported_binary_error() -> ServerMessage {
    ServerMessage::Error {
        message: "binary protocol messages are not supported by Shelly v0".to_string(),
        code: Some("unsupported_message_type".to_string()),
    }
}

fn rate_limited_error() -> ServerMessage {
    ServerMessage::Error {
        message: "rate limit exceeded".to_string(),
        code: Some("rate_limited".to_string()),
    }
}

fn payload_too_large_close() -> CloseFrame {
    CloseFrame {
        code: close_code::SIZE,
        reason: "payload too large".into(),
    }
}

#[derive(Debug, Clone)]
struct OutboundCloseFrame {
    code: u16,
    reason: String,
}

#[derive(Debug, Clone)]
enum OutboundEnvelope {
    Text(String),
    Pong(Vec<u8>),
    Close(Option<OutboundCloseFrame>),
}

impl OutboundEnvelope {
    fn estimated_bytes(&self) -> usize {
        match self {
            Self::Text(encoded) => encoded.len(),
            Self::Pong(payload) => payload.len(),
            Self::Close(frame) => frame
                .as_ref()
                .map(|close| close.reason.len().saturating_add(2))
                .unwrap_or(0),
        }
    }
}

enum OutboundQueuePush {
    Queued,
    Dropped,
    Disconnect,
}

fn emit_outbound_batch_telemetry(
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: &str,
    message_count: usize,
    bytes: usize,
    flush_count: usize,
) {
    let _ = telemetry.emit(
        correlation.apply_to_event(
            TelemetryEvent::new(TelemetryEventKind::Error)
                .with_session(session_id)
                .with_route(route_path)
                .with_ok(true)
                .with_count(message_count)
                .with_bytes(bytes)
                .with_attribute(
                    "phase".to_string(),
                    JsonValue::String("ws_outbound_batch".to_string()),
                )
                .with_attribute(
                    "flush_count".to_string(),
                    JsonValue::Number(serde_json::Number::from(flush_count)),
                ),
        ),
    );
}

fn emit_outbound_overflow_telemetry(
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: &str,
    policy: OutboundOverflowPolicy,
    queue_capacity: usize,
) {
    let _ = telemetry.emit(
        correlation.apply_to_event(
            TelemetryEvent::new(TelemetryEventKind::Error)
                .with_session(session_id)
                .with_route(route_path)
                .with_ok(false)
                .with_attribute(
                    "phase".to_string(),
                    JsonValue::String("ws_outbound_overflow".to_string()),
                )
                .with_attribute(
                    "overflow_policy".to_string(),
                    JsonValue::String(
                        match policy {
                            OutboundOverflowPolicy::Disconnect => "disconnect",
                            OutboundOverflowPolicy::DropNewest => "drop_newest",
                        }
                        .to_string(),
                    ),
                )
                .with_attribute(
                    "queue_capacity".to_string(),
                    JsonValue::Number(serde_json::Number::from(queue_capacity)),
                ),
        ),
    );
}

fn queue_outbound_envelope(
    sender: &mpsc::Sender<OutboundEnvelope>,
    envelope: OutboundEnvelope,
    config: &OutboundConfig,
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: &str,
) -> OutboundQueuePush {
    match sender.try_send(envelope) {
        Ok(()) => OutboundQueuePush::Queued,
        Err(mpsc::error::TrySendError::Full(_)) => {
            emit_outbound_overflow_telemetry(
                telemetry,
                correlation,
                route_path,
                session_id,
                config.overflow_policy,
                config.queue_capacity,
            );
            match config.overflow_policy {
                OutboundOverflowPolicy::Disconnect => OutboundQueuePush::Disconnect,
                OutboundOverflowPolicy::DropNewest => OutboundQueuePush::Dropped,
            }
        }
        Err(mpsc::error::TrySendError::Closed(_)) => OutboundQueuePush::Disconnect,
    }
}

fn queue_server_message(
    sender: &mpsc::Sender<OutboundEnvelope>,
    message: &ServerMessage,
    config: &OutboundConfig,
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: &str,
) -> OutboundQueuePush {
    let encoded = serde_json::to_string(message).expect("server messages should serialize");
    queue_outbound_envelope(
        sender,
        OutboundEnvelope::Text(encoded),
        config,
        telemetry,
        correlation,
        route_path,
        session_id,
    )
}

fn queue_pong_frame(
    sender: &mpsc::Sender<OutboundEnvelope>,
    payload: Vec<u8>,
    config: &OutboundConfig,
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: &str,
) -> OutboundQueuePush {
    queue_outbound_envelope(
        sender,
        OutboundEnvelope::Pong(payload),
        config,
        telemetry,
        correlation,
        route_path,
        session_id,
    )
}

fn queue_close_frame(
    sender: &mpsc::Sender<OutboundEnvelope>,
    frame: Option<CloseFrame>,
    config: &OutboundConfig,
    telemetry: &Arc<TelemetryPipeline>,
    correlation: &CorrelationContext,
    route_path: &str,
    session_id: &str,
) -> OutboundQueuePush {
    let close = frame.map(|value| OutboundCloseFrame {
        code: value.code,
        reason: value.reason.to_string(),
    });
    queue_outbound_envelope(
        sender,
        OutboundEnvelope::Close(close),
        config,
        telemetry,
        correlation,
        route_path,
        session_id,
    )
}

async fn run_outbound_writer(
    mut sender: futures_util::stream::SplitSink<WebSocket, Message>,
    mut receiver: mpsc::Receiver<OutboundEnvelope>,
    config: OutboundConfig,
    telemetry: Arc<TelemetryPipeline>,
    correlation: CorrelationContext,
    route_path: String,
    session_id: String,
) -> Result<(), axum::Error> {
    let mut pending: Option<OutboundEnvelope> = None;
    let mut should_stop = false;

    while !should_stop {
        let first = if let Some(envelope) = pending.take() {
            Some(envelope)
        } else {
            receiver.recv().await
        };
        let Some(first) = first else {
            break;
        };

        let mut batch = vec![first];
        let mut batch_bytes = batch[0].estimated_bytes();
        let deadline = Instant::now() + config.batch_flush_interval;
        let mut channel_closed = false;

        loop {
            if batch.len() >= config.batch_max_messages || batch_bytes >= config.batch_max_bytes {
                break;
            }

            match receiver.try_recv() {
                Ok(next) => {
                    let next_bytes = next.estimated_bytes();
                    let exceeds_limits = batch.len() + 1 > config.batch_max_messages
                        || batch_bytes.saturating_add(next_bytes) > config.batch_max_bytes;
                    if exceeds_limits {
                        pending = Some(next);
                        break;
                    }
                    batch_bytes = batch_bytes.saturating_add(next_bytes);
                    batch.push(next);
                }
                Err(mpsc::error::TryRecvError::Empty) => {
                    if batch.len() == 1 {
                        break;
                    }
                    let remaining = deadline.saturating_duration_since(Instant::now());
                    if remaining.is_zero() {
                        break;
                    }
                    match timeout(remaining, receiver.recv()).await {
                        Ok(Some(next)) => {
                            let next_bytes = next.estimated_bytes();
                            let exceeds_limits = batch.len() + 1 > config.batch_max_messages
                                || batch_bytes.saturating_add(next_bytes) > config.batch_max_bytes;
                            if exceeds_limits {
                                pending = Some(next);
                                break;
                            }
                            batch_bytes = batch_bytes.saturating_add(next_bytes);
                            batch.push(next);
                        }
                        Ok(None) => {
                            channel_closed = true;
                            break;
                        }
                        Err(_) => break,
                    }
                }
                Err(mpsc::error::TryRecvError::Disconnected) => {
                    channel_closed = true;
                    break;
                }
            }
        }

        let mut message_count = 0_usize;
        let mut flush_count = 0_usize;
        let mut flushed_bytes = 0_usize;
        for envelope in batch {
            flushed_bytes = flushed_bytes.saturating_add(envelope.estimated_bytes());
            match envelope {
                OutboundEnvelope::Text(encoded) => {
                    message_count = message_count.saturating_add(1);
                    sender.feed(Message::Text(encoded.into())).await?;
                }
                OutboundEnvelope::Pong(payload) => {
                    message_count = message_count.saturating_add(1);
                    sender.feed(Message::Pong(payload.into())).await?;
                }
                OutboundEnvelope::Close(frame) => {
                    message_count = message_count.saturating_add(1);
                    let close = frame.map(|value| CloseFrame {
                        code: value.code,
                        reason: value.reason.into(),
                    });
                    sender.feed(Message::Close(close)).await?;
                    should_stop = true;
                }
            }
        }

        sender.flush().await?;
        flush_count = flush_count.saturating_add(1);
        emit_outbound_batch_telemetry(
            &telemetry,
            &correlation,
            &route_path,
            &session_id,
            message_count,
            flushed_bytes,
            flush_count,
        );

        if channel_closed {
            break;
        }
    }

    Ok(())
}

async fn send_server_message(
    sender: &mut futures_util::stream::SplitSink<WebSocket, Message>,
    message: &ServerMessage,
) -> Result<(), axum::Error> {
    let encoded = serde_json::to_string(message).expect("server messages should serialize");
    sender.send(Message::Text(encoded.into())).await
}

fn render_shell(config: ShellConfig<'_>) -> String {
    let target_id = shelly::escape_html(config.target_id);
    let path = js_string(config.path);
    let title = shelly::escape_html(config.title);
    let session_id = js_string(config.session_id);
    let session_token = js_string(config.session_token);
    let csrf_token = js_string(config.csrf_token);
    let protocol = js_string(config.protocol);
    let trace_id = js_string(config.trace_id);
    let span_id = js_string(config.span_id);
    let correlation_id = js_string(config.correlation_id.unwrap_or(""));
    let request_id = js_string(config.request_id.unwrap_or(""));
    let reconnect_base_ms = config.reconnect_base_ms;
    let reconnect_max_ms = config.reconnect_max_ms;
    let reconnect_jitter_ms = config.reconnect_jitter_ms;
    let heartbeat_interval_ms = config.heartbeat_interval_ms;
    let heartbeat_timeout_ms = config.heartbeat_timeout_ms;
    let transport_mode = js_string(config.transport_mode);
    let transport_fallbacks = config.transport_fallbacks;
    let progressive_enhancement = config.progressive_enhancement;
    let inner_html = config.inner_html;

    format!(
        r#"<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{title}</title>
    <style>
      :root {{
        color-scheme: light;
        font-family: "Inter", "Segoe UI", system-ui, -apple-system, sans-serif;
        --shelly-color-bg: #f7f9fc;
        --shelly-color-surface: #ffffff;
        --shelly-color-surface-muted: #eef3f8;
        --shelly-color-border: #d5dfeb;
        --shelly-color-border-strong: #b7c7d8;
        --shelly-color-text: #132438;
        --shelly-color-text-muted: #5a7187;
        --shelly-color-primary: #f2662b;
        --shelly-color-primary-strong: #d94f18;
        --shelly-color-on-primary: #fff9f6;
        --shelly-color-accent: #1c8ea4;
        --shelly-color-accent-strong: #14788b;
        --shelly-color-on-accent: #f3fcff;
        --shelly-color-danger: #c53c26;
        --shelly-color-success: #1f8a65;
        --shelly-shadow-soft: 0 10px 28px rgba(19, 36, 56, 0.1);
      }}
      * {{ box-sizing: border-box; }}
      body {{
        margin: 0;
        min-height: 100vh;
        padding: 1.5rem;
        background: var(--shelly-color-bg);
        color: var(--shelly-color-text);
      }}
      a {{
        color: var(--shelly-color-accent-strong);
        text-underline-offset: 2px;
      }}
      a:hover {{ color: var(--shelly-color-accent); }}
      button {{
        border: 1px solid var(--shelly-color-border-strong);
        border-radius: 0.6rem;
        padding: 0.5rem 0.8rem;
        margin-right: 0.3rem;
        background: var(--shelly-color-surface);
        color: var(--shelly-color-text);
        font: inherit;
        cursor: pointer;
        transition: background 120ms ease, border-color 120ms ease, color 120ms ease;
      }}
      button:hover {{
        border-color: var(--shelly-color-accent);
        background: var(--shelly-color-surface-muted);
      }}
      button:disabled {{
        opacity: 0.6;
        cursor: not-allowed;
      }}
      input, select, textarea {{
        border: 1px solid var(--shelly-color-border-strong);
        border-radius: 0.55rem;
        padding: 0.48rem 0.65rem;
        background: var(--shelly-color-surface);
        color: var(--shelly-color-text);
        font: inherit;
      }}
      .card {{
        max-width: 34rem;
        padding: 1rem;
        border: 1px solid var(--shelly-color-border);
        border-radius: 0.75rem;
        background: var(--shelly-color-surface);
        box-shadow: var(--shelly-shadow-soft);
      }}
      .muted {{ color: var(--shelly-color-text-muted); }}
      pre {{
        margin: 0;
        border-radius: 0.65rem;
        background: #0f2235;
        color: #f8fbff;
      }}
    </style>
  </head>
  <body>
    <div id="{target_id}">{inner_html}</div>
    <script>
      window.__SHELLY = {{
        target: "{target_id}",
        path: "{path}",
        sessionId: "{session_id}",
        sessionToken: "{session_token}",
        csrfToken: "{csrf_token}",
        protocol: "{protocol}",
        traceId: "{trace_id}",
        spanId: "{span_id}",
        correlationId: "{correlation_id}",
        requestId: "{request_id}",
        reconnectBaseMs: {reconnect_base_ms},
        reconnectMaxMs: {reconnect_max_ms},
        reconnectJitterMs: {reconnect_jitter_ms},
        heartbeatIntervalMs: {heartbeat_interval_ms},
        heartbeatTimeoutMs: {heartbeat_timeout_ms},
        transportMode: "{transport_mode}",
        transportFallbacks: {transport_fallbacks},
        progressiveEnhancement: {progressive_enhancement}
      }};
    </script>
    <script src="/__shelly/client.js"></script>
  </body>
</html>"#
    )
}

fn js_string(value: &str) -> String {
    value
        .replace('\\', "\\\\")
        .replace('"', "\\\"")
        .replace('\n', "\\n")
        .replace('\r', "\\r")
        .replace('<', "\\u003c")
        .replace('>', "\\u003e")
        .replace('&', "\\u0026")
}

#[cfg(test)]
mod tests {
    use super::{
        abort_pubsub_tasks, abort_runtime_tasks, apply_overload_throttle, authorization_denied,
        cleanup_expired_snapshots, client_js, client_message_log_fields, contains_server_error,
        correlation_from_connect, correlation_from_headers, correlation_from_query,
        durable_acquire_lease, durable_error_message, durable_message_should_journal,
        durable_release_lease, effective_tenant_id_for_message, emit_outbound_batch_telemetry,
        emit_outbound_overflow_telemetry, emit_security_audit, emit_upload_lifecycle_telemetry,
        from_hex, handle_navigate, handle_patch_url, handle_upload_chunk, handle_upload_complete,
        handle_upload_start, header_value, initial_handler, internal_path, log_http_ingress,
        log_ws_text_ingress, messages_for_text_payload, non_empty_text, normalize_hex_id,
        normalize_path, now_unix_ms, origin_allowed, outbound_queue_depth,
        overload_decision_for_dispatch, overload_decision_to_error,
        overload_priority_for_client_message, overload_telemetry_event, parse_query,
        parse_traceparent, payload_too_large_close, payload_too_large_error, percent_decode,
        process_pubsub_commands, process_runtime_commands, queue_close_frame, queue_pong_frame,
        queue_server_message, quota_denied, rate_limited, rate_limited_error, reconnect_event,
        recover_from_durable_record, render_shell, replay_durable_journal_entry, route_segments,
        sanitize_query_for_log, security_audit_event, security_operation_for_message,
        session_affinity_mismatch, tenant_id_for_client_message, transport_capabilities,
        unregister_pubsub_presence, unsupported_binary_error, upload_error, upload_lifecycle_event,
        verify_websocket_tokens, AppState, AuthorizationDecision, AuthorizationInput,
        ConnectHandshake, ConsoleLogFormat, CorrelationContext, DistributedConfig,
        DurableJournalEntry, DurableLeaseRequest, DurablePlacementDecision, DurableRuntimeConfig,
        DurableSessionSnapshot, DurableSessionStore, DurableStoreError, DurableTakeoverPolicy,
        HttpTransportConfig, InMemoryDurableSessionStore, LiveRoute, OutboundCloseFrame,
        OutboundConfig, OutboundEnvelope, OutboundOverflowPolicy, OutboundQueuePush,
        OverloadBudgets, OverloadConfig, OverloadContext, OverloadDecision, OverloadPriority,
        OverloadShedPolicy, QuotaDecision, ReconnectConfig, ResumeSnapshot, RouteSegment,
        SecurityConfig, SecurityOperation, SessionAffinityMode, SessionTelemetrySink, ShellConfig,
        ShellyRouter, SignedSession, SocketConfig, TelemetryConfig, TelemetryExporter,
        TelemetryPipeline, TenantQuotaBudgets, TenantQuotaPolicy, TokenSigner, TransportMode,
        UploadConfig, UploadStartRequest, CLIENT_JS, DEFAULT_HEARTBEAT_INTERVAL_MS,
        DEFAULT_HEARTBEAT_TIMEOUT_MS, DEFAULT_HTTP3_ALT_SVC, DEFAULT_RECONNECT_BASE_MS,
        DEFAULT_RECONNECT_JITTER_MS, DEFAULT_RECONNECT_MAX_MS, PROTOCOL_VERSION,
    };
    use axum::{
        body::to_bytes,
        extract::{ws::close_code, State},
        http::{header, HeaderMap, HeaderValue, Method, StatusCode, Uri},
        response::IntoResponse,
    };
    use futures_util::{SinkExt, StreamExt};
    use shelly::{
        ClientMessage, Context, Event, Html, LiveResult, LiveSession, LiveView, PubSub,
        PubSubCommand, ResumeStatus, RuntimeCommand, RuntimeEvent, ServerMessage,
        TelemetryEventKind, TelemetrySink,
    };
    use std::{
        collections::{HashMap, HashSet},
        path::PathBuf,
        sync::Arc,
    };
    use tokio::{
        sync::mpsc,
        task::JoinHandle,
        time::{advance, Duration, Instant},
    };
    use tokio_tungstenite::{
        connect_async,
        tungstenite::{client::IntoClientRequest, Error as WsError, Message as WsMessage},
    };
    use uuid::Uuid;

    fn test_correlation() -> CorrelationContext {
        CorrelationContext {
            trace_id: "0123456789abcdef0123456789abcdef".to_string(),
            span_id: "0123456789abcdef".to_string(),
            parent_span_id: None,
            correlation_id: Some("corr-123".to_string()),
            request_id: Some("req-123".to_string()),
        }
    }

    fn test_overload_context(
        session_id: &str,
        tenant_id: Option<&str>,
        priority: OverloadPriority,
        inbound_bytes: usize,
        queue_depth: usize,
        queue_capacity: usize,
    ) -> OverloadContext {
        OverloadContext {
            route_path: "/bench".to_string(),
            session_id: session_id.to_string(),
            tenant_id: tenant_id.map(ToString::to_string),
            message_kind: "text",
            operation: SecurityOperation::Event,
            event_name: Some("bench.event".to_string()),
            priority,
            queue_depth,
            queue_capacity,
            inbound_bytes,
        }
    }

    fn test_app_state_with(
        pattern: &str,
        security: SecurityConfig,
        distributed: DistributedConfig,
    ) -> Arc<AppState> {
        Arc::new(AppState {
            routes: Arc::new(vec![LiveRoute::new(
                pattern.to_string(),
                Arc::new(|| Box::<Counter>::default()),
            )]),
            target_id: "root".to_string(),
            max_message_size: 64 * 1024,
            pubsub: PubSub::default(),
            uploads: UploadConfig::default(),
            security,
            telemetry: Arc::new(TelemetryPipeline::disabled()),
            reconnect: ReconnectConfig::default(),
            distributed,
            durable: DurableRuntimeConfig::default(),
            outbound: OutboundConfig::default(),
            render: super::RenderConfig::default(),
            overload: OverloadConfig::default(),
            transport_http: HttpTransportConfig::default(),
        })
    }

    async fn spawn_test_router(router: ShellyRouter) -> (String, JoinHandle<()>) {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
            .await
            .expect("bind test listener");
        let addr = listener.local_addr().expect("listener addr");
        let app = router.into_router();
        let handle = tokio::spawn(async move {
            let _ = axum::serve(listener, app).await;
        });
        (format!("ws://{addr}"), handle)
    }

    fn ws_error_status(err: WsError) -> StatusCode {
        match err {
            WsError::Http(response) => response.status(),
            other => panic!("unexpected websocket error: {other:?}"),
        }
    }

    async fn await_hello(
        socket: &mut tokio_tungstenite::WebSocketStream<
            tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,
        >,
    ) {
        for _ in 0..8 {
            let frame = socket.next().await.expect("hello frame");
            if let Ok(WsMessage::Text(text)) = frame {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("hello frame should decode");
                if matches!(message, ServerMessage::Hello { .. }) {
                    return;
                }
            }
        }
        panic!("expected hello frame");
    }

    async fn await_error_code(
        socket: &mut tokio_tungstenite::WebSocketStream<
            tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,
        >,
        code: &str,
    ) {
        for _ in 0..12 {
            let Some(frame) = socket.next().await else {
                break;
            };
            if let Ok(WsMessage::Text(text)) = frame {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("error frame should decode");
                if matches!(
                    message,
                    ServerMessage::Error {
                        code: Some(ref candidate),
                        ..
                    } if candidate == code
                ) {
                    return;
                }
            }
        }
        panic!("expected server error code `{code}`");
    }

    #[test]
    fn normalize_path_adds_leading_slash() {
        assert_eq!(normalize_path("users".to_string()), "/users");
        assert_eq!(normalize_path("/users".to_string()), "/users");
        assert_eq!(normalize_path("".to_string()), "/");
    }

    #[test]
    fn durable_and_overload_helper_branches_are_exercised() {
        let durable_err = DurableStoreError::new("store_unavailable", "durable store down");
        let message = durable_error_message(&durable_err);
        assert!(matches!(
            message,
            ServerMessage::Error {
                code: Some(ref code),
                ..
            } if code == "store_unavailable"
        ));

        assert!(durable_message_should_journal(&ClientMessage::Navigate {
            to: "/x".to_string()
        }));
        assert!(!durable_message_should_journal(&ClientMessage::Ping {
            nonce: None
        }));
        assert!(!durable_message_should_journal(&ClientMessage::Event {
            event: super::INTERNAL_RENDER_FLUSH_EVENT.to_string(),
            value: serde_json::Value::Null,
            target: None,
            metadata: Default::default(),
        }));

        assert!(contains_server_error(&[
            ServerMessage::Patch {
                revision: 1,
                target: "root".to_string(),
                html: "<div/>".to_string(),
            },
            ServerMessage::Error {
                message: "boom".to_string(),
                code: Some("e".to_string()),
            },
        ]));
        assert!(!contains_server_error(&[ServerMessage::Pong {
            nonce: None
        }]));

        let interactive = ClientMessage::Event {
            event: "save".to_string(),
            value: serde_json::json!({"tenant_id": "tenant-a"}),
            target: None,
            metadata: Default::default(),
        };
        let background = ClientMessage::Event {
            event: "bg:refresh".to_string(),
            value: serde_json::Value::Null,
            target: None,
            metadata: serde_json::Map::from_iter([(
                "priority".to_string(),
                serde_json::Value::String("background".to_string()),
            )]),
        };
        assert_eq!(
            overload_priority_for_client_message(&interactive),
            OverloadPriority::Interactive
        );
        assert_eq!(
            overload_priority_for_client_message(&background),
            OverloadPriority::Background
        );
        assert_eq!(
            tenant_id_for_client_message(&interactive).as_deref(),
            Some("tenant-a")
        );
        assert_eq!(
            effective_tenant_id_for_message(Some("tenant-session"), Some("tenant-msg")).as_deref(),
            Some("tenant-msg")
        );
        assert_eq!(
            effective_tenant_id_for_message(Some("tenant-session"), None).as_deref(),
            Some("tenant-session")
        );

        let (sender, _receiver) = mpsc::channel::<OutboundEnvelope>(4);
        assert_eq!(outbound_queue_depth(&sender, 4), 0);
        let _ = sender.try_send(OutboundEnvelope::Text("x".to_string()));
        assert_eq!(outbound_queue_depth(&sender, 4), 1);

        let shed = OverloadDecision::shed("shed:queue_depth");
        let throttle = OverloadDecision::throttle(12, "throttle:session_budget");
        assert!(matches!(
            overload_decision_to_error(&shed),
            ServerMessage::Error {
                code: Some(ref code),
                ..
            } if code == "overload_shed"
        ));
        assert!(matches!(
            overload_decision_to_error(&throttle),
            ServerMessage::Error {
                code: Some(ref code),
                ..
            } if code == "overload_throttle"
        ));
    }

    #[test]
    fn durable_runtime_helpers_cover_acquire_append_release_and_replay_paths() {
        let distributed = DistributedConfig {
            node_id: "node-a".to_string(),
            ..DistributedConfig::default()
        };
        let no_store = DurableRuntimeConfig::default();
        assert!(
            super::durable_acquire_lease(&no_store, &distributed, "session-none", "/")
                .expect("no-store lease lookup should succeed")
                .is_none()
        );

        let mut session = LiveSession::new(Box::<Counter>::default(), "root");
        session.mount().expect("mount counter session");
        let dummy_lease = super::DurableLeaseHandle {
            owner_node_id: "node-a".to_string(),
            fence_token: 1,
        };
        super::durable_save_snapshot(
            &no_store,
            &dummy_lease,
            &session,
            "/",
            "root",
            "resume-none",
        );
        assert!(super::durable_append_journal_entry(
            &no_store,
            &dummy_lease,
            "session-none",
            &ClientMessage::Navigate {
                to: "/users".to_string(),
            },
        )
        .expect("append should no-op without store")
        .is_none());
        super::durable_release_lease(&no_store, "session-none", Some(&dummy_lease));

        let store = Arc::new(InMemoryDurableSessionStore::new());
        let mut durable = DurableRuntimeConfig {
            store: Some(store.clone()),
            drain_mode: true,
            ..DurableRuntimeConfig::default()
        };
        let err = super::durable_acquire_lease(&durable, &distributed, "session-draining", "/")
            .expect_err("drain mode should reject ownership");
        assert_eq!(err.code, "node_draining");

        durable.drain_mode = false;
        store.set_node_draining(&distributed.node_id, true);
        let err = super::durable_acquire_lease(&durable, &distributed, "session-draining", "/")
            .expect_err("draining node flag should reject ownership");
        assert_eq!(err.code, "node_draining");

        store.set_node_draining(&distributed.node_id, false);
        durable.placement_hook = Some(Arc::new(|_| {
            DurablePlacementDecision::deny("placement_rejected_custom", "placement rejected")
        }));
        let err = super::durable_acquire_lease(&durable, &distributed, "session-placed", "/")
            .expect_err("placement hook should reject ownership");
        assert_eq!(err.code, "placement_rejected_custom");

        durable.placement_hook = None;
        let lease = super::durable_acquire_lease(&durable, &distributed, "session-live", "/")
            .expect("acquire lease")
            .expect("store-backed durable runtime should produce lease");

        super::durable_save_snapshot(&durable, &lease, &session, "/", "root", "resume-live");
        let first = super::durable_append_journal_entry(
            &durable,
            &lease,
            "session-live",
            &ClientMessage::Navigate {
                to: "/counter".to_string(),
            },
        )
        .expect("append navigate should succeed")
        .expect("navigate should be journaled");
        assert_eq!(first.sequence, 1);
        assert!(super::durable_append_journal_entry(
            &durable,
            &lease,
            "session-live",
            &ClientMessage::Ping { nonce: None },
        )
        .expect("append ping should succeed")
        .is_none());

        super::durable_release_lease(&durable, "session-live", Some(&lease));
        let stale = super::durable_append_journal_entry(
            &durable,
            &lease,
            "session-live",
            &ClientMessage::Navigate {
                to: "/counter".to_string(),
            },
        )
        .expect_err("stale lease should not append after release");
        assert_eq!(stale.code, "lease_not_found");

        let telemetry: Arc<dyn TelemetrySink> = Arc::new(TelemetryPipeline::disabled());
        let routes = vec![LiveRoute::new(
            "/".to_string(),
            Arc::new(|| Box::<Counter>::default()),
        )];
        let mut route_pattern = "/".to_string();
        let replay_error = replay_durable_journal_entry(
            &mut session,
            &mut route_pattern,
            &routes,
            "root",
            "session-live",
            &telemetry,
            &DurableJournalEntry {
                sequence: 99,
                message: ClientMessage::PatchUrl {
                    to: "https://example.test/off-domain".to_string(),
                },
                recorded_at_unix_ms: 0,
            },
        )
        .expect_err("invalid patch_url should surface a replay error");
        assert!(replay_error.contains("durable journal replay failed"));
    }

    #[tokio::test]
    async fn abort_task_helpers_cancel_running_tasks() {
        let pubsub_task = tokio::spawn(async {
            tokio::time::sleep(Duration::from_secs(5)).await;
        });
        abort_pubsub_tasks(vec![pubsub_task]);

        let mut runtime_tasks = HashMap::new();
        runtime_tasks.insert(
            "ticker".to_string(),
            tokio::spawn(async {
                tokio::time::sleep(Duration::from_secs(5)).await;
            }),
        );
        abort_runtime_tasks(runtime_tasks);
    }

    #[test]
    fn console_log_format_parser_defaults_to_json() {
        assert_eq!(ConsoleLogFormat::parse("json"), ConsoleLogFormat::Json);
        assert_eq!(ConsoleLogFormat::parse("  JSON  "), ConsoleLogFormat::Json);
        assert_eq!(ConsoleLogFormat::parse("unknown"), ConsoleLogFormat::Json);
    }

    #[test]
    fn console_log_format_parser_supports_pretty_aliases() {
        for raw in ["pretty", "PRETTY", "text", "plain"] {
            assert_eq!(ConsoleLogFormat::parse(raw), ConsoleLogFormat::Pretty);
        }
    }

    #[test]
    fn console_log_format_as_str_outputs_expected_values() {
        assert_eq!(ConsoleLogFormat::Json.as_str(), "json");
        assert_eq!(ConsoleLogFormat::Pretty.as_str(), "pretty");
    }

    #[test]
    fn telemetry_config_builders_select_expected_exporters() {
        let tracing = TelemetryConfig::tracing("svc-a");
        assert_eq!(tracing.service_name, "svc-a");
        assert!(matches!(tracing.exporter, TelemetryExporter::Tracing));

        let otel = TelemetryConfig::otel_json("svc-b");
        assert_eq!(otel.service_name, "svc-b");
        assert!(matches!(
            otel.exporter,
            TelemetryExporter::OpenTelemetryJson
        ));

        let axiom =
            TelemetryConfig::axiom_json("svc-c", "dataset-main", Some("org-123".to_string()));
        assert_eq!(axiom.service_name, "svc-c");
        assert!(matches!(
            axiom.exporter,
            TelemetryExporter::AxiomJson { .. }
        ));
    }

    #[test]
    fn telemetry_pipeline_emit_supports_all_exporters() {
        let event = shelly::TelemetryEvent::new(TelemetryEventKind::HandleEvent)
            .with_session("session-1")
            .with_route("/demo")
            .with_event_name("save")
            .with_ok(true)
            .with_latency_ms(12)
            .with_bytes(256)
            .with_count(1)
            .with_attribute("api_key", serde_json::json!("secret-token"));

        let tracing_pipeline = TelemetryPipeline::enabled(TelemetryConfig::tracing("svc"));
        assert!(tracing_pipeline.emit(event.clone()).is_ok());

        let otel_pipeline = TelemetryPipeline::enabled(TelemetryConfig::otel_json("svc"));
        assert!(otel_pipeline.emit(event.clone()).is_ok());

        let axiom_pipeline = TelemetryPipeline::enabled(TelemetryConfig::axiom_json(
            "svc",
            "dataset-main",
            Some("org-1".to_string()),
        ));
        assert!(axiom_pipeline.emit(event).is_ok());
    }

    #[test]
    fn session_telemetry_sink_applies_correlation_context() {
        let sink = SessionTelemetrySink::new(
            Arc::new(TelemetryPipeline::disabled()),
            CorrelationContext {
                trace_id: "0123456789abcdef0123456789abcdef".to_string(),
                span_id: "0123456789abcdef".to_string(),
                parent_span_id: Some("fedcba9876543210".to_string()),
                correlation_id: Some("corr-1".to_string()),
                request_id: Some("req-1".to_string()),
            },
        );
        assert!(sink
            .emit(shelly::TelemetryEvent::new(TelemetryEventKind::Patch))
            .is_ok());
    }

    #[test]
    fn correlation_helpers_extract_and_fallback_fields() {
        let mut headers = HeaderMap::new();
        headers.insert("x-request-id", HeaderValue::from_static("req-7"));
        headers.insert("x-correlation-id", HeaderValue::from_static("corr-7"));
        headers.insert(
            "traceparent",
            HeaderValue::from_static("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"),
        );
        headers.insert(
            "x-trace-id",
            HeaderValue::from_static("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"),
        );

        assert_eq!(non_empty_text("   "), None);
        assert_eq!(
            header_value(&headers, "x-request-id").as_deref(),
            Some("req-7")
        );

        let base = correlation_from_headers(&headers);
        assert_eq!(
            base.trace_id,
            "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa".to_string()
        );
        assert_eq!(base.correlation_id.as_deref(), Some("corr-7"));
        assert_eq!(base.request_id.as_deref(), Some("req-7"));
        assert_eq!(base.parent_span_id.as_deref(), Some("00f067aa0ba902b7"));

        let mut query = HashMap::new();
        query.insert(
            "trace_id".to_string(),
            "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb".to_string(),
        );
        query.insert("request_id".to_string(), "req-9".to_string());
        let from_query = correlation_from_query(&query, &base);
        assert_eq!(
            from_query.trace_id,
            "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb".to_string()
        );
        assert_eq!(from_query.request_id.as_deref(), Some("req-9"));
        assert_eq!(from_query.correlation_id.as_deref(), Some("corr-7"));
        assert_eq!(
            from_query.parent_span_id.as_deref(),
            Some(base.span_id.as_str())
        );
    }

    #[test]
    fn http_ingress_logging_returns_correlation_context() {
        let mut headers = HeaderMap::new();
        headers.insert(header::USER_AGENT, HeaderValue::from_static("shelly-test"));
        headers.insert(header::HOST, HeaderValue::from_static("127.0.0.1:3000"));
        headers.insert("x-request-id", HeaderValue::from_static("req-42"));
        let method = Method::GET;
        let uri: Uri = "/grid?session=sensitive&custom=ok".parse().expect("uri");

        let correlation = log_http_ingress("initial", &method, &uri, &headers);
        assert_eq!(correlation.request_id.as_deref(), Some("req-42"));
        assert!(!correlation.trace_id.is_empty());
        assert!(!correlation.span_id.is_empty());
    }

    #[test]
    fn security_operation_helpers_cover_mutation_matrix() {
        assert_eq!(SecurityOperation::Connect.as_str(), "connect");
        assert_eq!(SecurityOperation::Binary.as_str(), "binary");
        assert!(!SecurityOperation::Connect.is_mutating());
        assert!(SecurityOperation::Event.is_mutating());
        assert!(SecurityOperation::UploadComplete.is_mutating());
        assert!(!SecurityOperation::Ping.is_mutating());
    }

    #[test]
    fn durable_placement_decision_helpers_toggle_allowed_state() {
        let allow = DurablePlacementDecision::allow();
        assert!(allow.allowed);
        assert!(allow.code.is_none());

        let deny = DurablePlacementDecision::deny("placement_reject", "no capacity");
        assert!(!deny.allowed);
        assert_eq!(deny.code.as_deref(), Some("placement_reject"));
        assert_eq!(deny.message.as_deref(), Some("no capacity"));
    }

    #[test]
    fn in_memory_durable_store_renew_release_and_drain_controls() {
        let store = InMemoryDurableSessionStore::new();
        assert!(!store.is_node_draining("node-a"));
        store.set_node_draining("node-a", true);
        assert!(store.is_node_draining("node-a"));
        store.set_node_draining("node-a", false);
        assert!(!store.is_node_draining("node-a"));

        let lease = store
            .acquire_lease(DurableLeaseRequest {
                session_id: "session-1".to_string(),
                node_id: "node-a".to_string(),
                ttl_ms: 10_000,
                takeover_policy: DurableTakeoverPolicy::AllowExpired,
            })
            .expect("acquire lease");
        let renewed = store
            .renew_lease("session-1", "node-a", lease.fence_token, 10_000)
            .expect("renew lease");
        assert_eq!(renewed.fence_token, lease.fence_token);

        let renew_err = store
            .renew_lease("session-1", "node-b", lease.fence_token, 10_000)
            .expect_err("non-owner renew should fail");
        assert_eq!(renew_err.code, "lease_not_owner");

        store.release_lease("session-1", "node-b", lease.fence_token);
        store
            .append_journal_entry(
                "session-1",
                "node-a",
                lease.fence_token,
                ClientMessage::Ping { nonce: None },
                2,
            )
            .expect("owner can append journal");
        store.release_lease("session-1", "node-a", lease.fence_token);
        let append_err = store
            .append_journal_entry(
                "session-1",
                "node-a",
                lease.fence_token,
                ClientMessage::Ping { nonce: None },
                2,
            )
            .expect_err("append after release should fail");
        assert_eq!(append_err.code, "lease_not_found");
        assert!(store.load_record("missing").is_none());
    }

    #[test]
    fn app_state_route_for_matches_registered_pattern() {
        let routes = Arc::new(vec![LiveRoute::new(
            "/users/:id".to_string(),
            Arc::new(|| Box::<Counter>::default()),
        )]);
        let state = AppState {
            routes,
            target_id: "root".to_string(),
            max_message_size: 64 * 1024,
            pubsub: PubSub::default(),
            uploads: UploadConfig::default(),
            security: SecurityConfig::default(),
            telemetry: Arc::new(TelemetryPipeline::disabled()),
            reconnect: ReconnectConfig::default(),
            distributed: DistributedConfig::default(),
            durable: DurableRuntimeConfig::default(),
            outbound: OutboundConfig::default(),
            render: super::RenderConfig::default(),
            overload: OverloadConfig::default(),
            transport_http: HttpTransportConfig::default(),
        };

        let matched = state.route_for("/users/42").expect("route match");
        assert_eq!(matched.pattern, "/users/:id");
        assert_eq!(matched.params.get("id").map(String::as_str), Some("42"));
        assert!(state.route_for("/posts/42").is_none());
    }

    #[test]
    fn shelly_router_builder_methods_apply_configuration() {
        let store: Arc<dyn DurableSessionStore> = Arc::new(InMemoryDurableSessionStore::new());
        let overload_budgets = OverloadBudgets {
            session_queue_depth: 12,
            session_bytes_per_sec: 2_048,
            session_cpu_ms_per_sec: 16,
            tenant_queue_depth: 24,
            tenant_bytes_per_sec: 4_096,
            tenant_cpu_ms_per_sec: 32,
        };
        let router = ShellyRouter::new()
            .with_target_id("root-test")
            .with_max_message_size(32 * 1024)
            .with_max_upload_size(2048)
            .with_allowed_upload_content_type("application/json")
            .with_upload_temp_dir(PathBuf::from("/tmp/shelly-upload-tests"))
            .with_secret(b"top-secret".to_vec())
            .with_allowed_origin("https://example.com")
            .with_rate_limiter(|_| true)
            .with_authorization_hook(|_| AuthorizationDecision::allow())
            .with_quota_policy(|_| QuotaDecision::allow())
            .with_telemetry(TelemetryConfig::tracing("svc-router"))
            .with_reconnect_backoff(10, 20, 30)
            .with_heartbeat(100, 200)
            .with_resume_ttl_ms(100)
            .with_connect_handshake_timeout_ms(100)
            .with_http3_default_alt_svc()
            .with_transport_diagnostics_header(true)
            .with_http3_alt_svc("h3=\":8443\"; ma=300")
            .with_node_id("node-test")
            .with_session_affinity_mode(SessionAffinityMode::Required)
            .with_durable_session_store(store.clone())
            .with_durable_lease_ttl_ms(10)
            .with_durable_journal_limit(0)
            .with_durable_takeover_policy(DurableTakeoverPolicy::Force)
            .with_durable_drain_mode(true)
            .with_durable_placement_hook(|_| DurablePlacementDecision::allow())
            .with_outbound_queue_capacity(0)
            .with_outbound_batching(0, 128, 0)
            .with_outbound_overflow_policy(OutboundOverflowPolicy::DropNewest)
            .with_default_render_cadence_ms(22)
            .with_overload_budgets(overload_budgets.clone())
            .with_overload_shed_policy(OverloadShedPolicy::Strict)
            .with_overload_policy_hook(|_ctx, decision| decision.clone())
            .live("/", Counter::default);

        assert_eq!(router.target_id, "root-test");
        assert_eq!(router.max_message_size, 32 * 1024);
        assert_eq!(router.uploads.max_file_size, 2048);
        assert_eq!(
            router.uploads.allowed_content_types.as_ref(),
            &vec!["application/json".to_string()]
        );
        assert_eq!(router.distributed.node_id, "node-test");
        assert_eq!(
            router.distributed.session_affinity,
            SessionAffinityMode::Required
        );
        assert_eq!(router.reconnect.client.reconnect_base_ms, 100);
        assert_eq!(router.reconnect.client.reconnect_max_ms, 100);
        assert_eq!(router.reconnect.client.heartbeat_interval_ms, 1_000);
        assert_eq!(router.reconnect.client.heartbeat_timeout_ms, 1_000);
        assert_eq!(
            router.transport_http.http3_alt_svc.as_deref(),
            Some("h3=\":8443\"; ma=300")
        );
        assert!(router.transport_http.emit_diagnostics_header);
        assert_eq!(router.durable.journal_limit, 1);
        assert_eq!(router.durable.takeover_policy, DurableTakeoverPolicy::Force);
        assert_eq!(router.outbound.queue_capacity, 1);
        assert_eq!(router.outbound.batch_max_messages, 1);
        assert_eq!(router.outbound.batch_max_bytes, 256);
        assert_eq!(
            router.outbound.batch_flush_interval,
            Duration::from_millis(1)
        );
        assert_eq!(
            router.outbound.overflow_policy,
            OutboundOverflowPolicy::DropNewest
        );
        assert_eq!(router.render.default_cadence_ms, 22);
        assert_eq!(router.overload.budgets, overload_budgets);
        assert_eq!(router.overload.shed_policy, OverloadShedPolicy::Strict);
        assert!(router.overload.policy_hook.is_some());
        assert!(router.durable.drain_mode);
        assert!(router.security.rate_limiter.is_some());
        assert!(router.security.authorization.is_some());
        assert!(router.security.quota_policy.is_some());
        assert!(router.durable.placement_hook.is_some());
        assert_eq!(router.routes.len(), 1);

        let node_id = router.distributed.node_id.clone();
        let durable_store = router
            .durable
            .store
            .as_ref()
            .expect("durable store should exist")
            .clone();
        let _axum_router = router.into_router();
        assert!(durable_store.is_node_draining(&node_id));
    }

    #[test]
    fn route_patterns_capture_params() {
        assert_eq!(
            route_segments("/users/:id"),
            vec![
                RouteSegment::Static("users".to_string()),
                RouteSegment::Param("id".to_string())
            ]
        );

        let route = LiveRoute::new(
            "/users/:id".to_string(),
            std::sync::Arc::new(|| Box::<Counter>::default()),
        );
        let matched = route.match_path("/users/42").unwrap();
        assert_eq!(matched.pattern, "/users/:id");
        assert_eq!(matched.params.get("id").map(String::as_str), Some("42"));
        assert!(route.match_path("/users/42/edit").is_none());
    }

    #[test]
    fn internal_navigation_rejects_external_urls() {
        assert_eq!(
            internal_path("/pages/intro?tab=a#top").as_deref(),
            Some("/pages/intro")
        );
        assert_eq!(internal_path("https://example.test/pages"), None);
        assert_eq!(internal_path("//example.test/pages"), None);
    }

    #[test]
    fn shell_contains_target_and_client_asset() {
        let html = render_shell(ShellConfig {
            target_id: "root",
            inner_html: "<p>hi</p>",
            path: "/",
            title: "Test",
            session_id: "sid",
            session_token: "session",
            csrf_token: "csrf",
            protocol: "shelly/1",
            trace_id: "0123456789abcdef0123456789abcdef",
            span_id: "0123456789abcdef",
            correlation_id: Some("corr-1"),
            request_id: Some("req-1"),
            reconnect_base_ms: DEFAULT_RECONNECT_BASE_MS,
            reconnect_max_ms: DEFAULT_RECONNECT_MAX_MS,
            reconnect_jitter_ms: DEFAULT_RECONNECT_JITTER_MS,
            heartbeat_interval_ms: DEFAULT_HEARTBEAT_INTERVAL_MS,
            heartbeat_timeout_ms: DEFAULT_HEARTBEAT_TIMEOUT_MS,
            transport_mode: "websocket",
            transport_fallbacks: r#"["sse","long_poll"]"#,
            progressive_enhancement: true,
        });
        assert!(html.contains("<div id=\"root\"><p>hi</p></div>"));
        assert!(html.contains("/__shelly/client.js"));
        assert!(html.contains("window.__SHELLY"));
        assert!(html.contains(r#"sessionId: "sid""#));
        assert!(html.contains(r#"sessionToken: "session""#));
        assert!(html.contains(r#"csrfToken: "csrf""#));
        assert!(html.contains(r#"protocol: "shelly/1""#));
        assert!(html.contains(r#"traceId: "0123456789abcdef0123456789abcdef""#));
        assert!(html.contains(r#"spanId: "0123456789abcdef""#));
        assert!(html.contains(r#"correlationId: "corr-1""#));
        assert!(html.contains(r#"requestId: "req-1""#));
        assert!(html.contains("reconnectBaseMs: 750"));
        assert!(html.contains("reconnectMaxMs: 30000"));
        assert!(html.contains("heartbeatIntervalMs: 15000"));
        assert!(html.contains("heartbeatTimeoutMs: 10000"));
        assert!(html.contains(r#"transportMode: "websocket""#));
        assert!(html.contains(r#"transportFallbacks: ["sse","long_poll"]"#));
        assert!(html.contains("progressiveEnhancement: true"));
    }

    #[test]
    fn shell_escapes_security_config_values() {
        let html = render_shell(ShellConfig {
            target_id: r#"ro"ot"#,
            inner_html: "<p>trusted</p>",
            path: r#"/"><script>"#,
            title: r#"<Title>"#,
            session_id: "sid",
            session_token: "session",
            csrf_token: "csrf",
            protocol: "shelly/1",
            trace_id: "0123456789abcdef0123456789abcdef",
            span_id: "0123456789abcdef",
            correlation_id: Some("corr-1"),
            request_id: Some("req-1"),
            reconnect_base_ms: DEFAULT_RECONNECT_BASE_MS,
            reconnect_max_ms: DEFAULT_RECONNECT_MAX_MS,
            reconnect_jitter_ms: DEFAULT_RECONNECT_JITTER_MS,
            heartbeat_interval_ms: DEFAULT_HEARTBEAT_INTERVAL_MS,
            heartbeat_timeout_ms: DEFAULT_HEARTBEAT_TIMEOUT_MS,
            transport_mode: "websocket",
            transport_fallbacks: "[]",
            progressive_enhancement: true,
        });

        assert!(html.contains("<title>&lt;Title&gt;</title>"));
        assert!(html.contains(r#"<div id="ro&quot;ot">"#));
        assert!(html.contains("\\u003cscript\\u003e"));
        assert!(!html.contains(r#"path: "/"><script>""#));
    }

    #[derive(Default)]
    struct Counter {
        count: i64,
    }

    async fn recv_runtime_event_with_virtual_time(
        receiver: &mut mpsc::UnboundedReceiver<RuntimeEvent>,
        delay: Duration,
    ) -> RuntimeEvent {
        advance(delay).await;
        tokio::task::yield_now().await;
        receiver
            .recv()
            .await
            .expect("runtime event should be available after virtual-time advance")
    }

    impl LiveView for Counter {
        fn handle_event(&mut self, event: Event, _ctx: &mut Context) -> LiveResult {
            match event.name.as_str() {
                "inc" => self.count += 1,
                "dec" => self.count -= 1,
                _ => {}
            }

            Ok(())
        }

        fn render(&self) -> Html {
            Html::new(format!("<p>{}</p>", self.count))
        }
    }

    #[test]
    fn text_payload_dispatches_client_events() {
        let mut session = LiveSession::new(Box::<Counter>::default(), "root");
        session.mount().unwrap();

        let messages = messages_for_text_payload(
            &mut session,
            r#"{"type":"event","event":"inc","target":"inc","value":null}"#,
        );

        assert_eq!(
            messages,
            vec![ServerMessage::Patch {
                target: "root".to_string(),
                html: "<p>1</p>".to_string(),
                revision: 1,
            }]
        );
    }

    #[test]
    fn text_payload_accepts_protocol_connect() {
        let mut session = LiveSession::new(Box::<Counter>::default(), "root");
        session.mount().unwrap();

        assert_eq!(
            messages_for_text_payload(&mut session, r#"{"type":"connect","protocol":"shelly/1"}"#),
            Vec::<ServerMessage>::new()
        );
    }

    #[test]
    fn text_payload_rejects_unsupported_protocol_connect() {
        let mut session = LiveSession::new(Box::<Counter>::default(), "root");
        session.mount().unwrap();

        assert_eq!(
            messages_for_text_payload(&mut session, r#"{"type":"connect","protocol":"shelly/9"}"#),
            vec![ServerMessage::Error {
                message: "unsupported protocol in connect: expected shelly/1, got shelly/9"
                    .to_string(),
                code: Some("unsupported_protocol".to_string()),
            }]
        );
    }

    #[derive(Default)]
    struct Page {
        slug: String,
    }

    impl LiveView for Page {
        fn handle_params(&mut self, ctx: &mut Context) -> LiveResult {
            self.slug = ctx.route_param("slug").unwrap_or("home").to_string();
            Ok(())
        }

        fn render(&self) -> Html {
            Html::new(format!("<p>Page {}</p>", self.slug))
        }
    }

    #[derive(Default)]
    struct User {
        id: String,
    }

    impl LiveView for User {
        fn handle_params(&mut self, ctx: &mut Context) -> LiveResult {
            self.id = ctx.route_param("id").unwrap_or_default().to_string();
            Ok(())
        }

        fn render(&self) -> Html {
            Html::new(format!("<p>User {}</p>", self.id))
        }
    }

    #[test]
    fn patch_url_updates_route_params_and_patches_without_remounting() {
        let routes = vec![LiveRoute::new(
            "/pages/:slug".to_string(),
            std::sync::Arc::new(|| Box::<Page>::default()),
        )];
        let mut session = LiveSession::new_with_route(
            Box::<Page>::default(),
            "root",
            "/pages/home",
            [("slug".to_string(), "home".to_string())].into(),
        );
        session.mount().unwrap();
        session.render_patch();
        let mut current = "/pages/:slug".to_string();

        let messages = handle_patch_url(&mut session, &mut current, &routes, "/pages/docs");

        assert_eq!(
            messages,
            vec![
                ServerMessage::PatchUrl {
                    to: "/pages/docs".to_string()
                },
                ServerMessage::Patch {
                    target: "root".to_string(),
                    html: "<p>Page docs</p>".to_string(),
                    revision: 2,
                },
            ]
        );
    }

    #[test]
    fn navigate_switches_liveview_route_and_renders_target() {
        let routes = vec![
            LiveRoute::new(
                "/pages/:slug".to_string(),
                std::sync::Arc::new(|| Box::<Page>::default()),
            ),
            LiveRoute::new(
                "/users/:id".to_string(),
                std::sync::Arc::new(|| Box::<User>::default()),
            ),
        ];
        let mut session = LiveSession::new_with_route(
            Box::<Page>::default(),
            "root",
            "/pages/home",
            [("slug".to_string(), "home".to_string())].into(),
        );
        session.mount().unwrap();
        let mut current = "/pages/:slug".to_string();
        let telemetry: Arc<dyn TelemetrySink> = Arc::new(TelemetryPipeline::disabled());

        let messages = handle_navigate(
            &mut session,
            &mut current,
            &routes,
            "root",
            "sid",
            &telemetry,
            "/users/42",
        );

        assert_eq!(current, "/users/:id");
        assert_eq!(messages.len(), 3);
        assert_eq!(
            messages[0],
            ServerMessage::Navigate {
                to: "/users/42".to_string()
            }
        );
        assert!(matches!(messages[1], ServerMessage::Hello { .. }));
        assert_eq!(
            messages[2],
            ServerMessage::Patch {
                target: "root".to_string(),
                html: "<p>User 42</p>".to_string(),
                revision: 1,
            }
        );
    }

    #[test]
    fn query_parser_decodes_protocol_version() {
        let query = parse_query("protocol=shelly%2F1&session=abc&csrf=def");

        assert_eq!(query.get("protocol").map(String::as_str), Some("shelly/1"));
    }

    #[test]
    fn query_log_sanitizer_redacts_sensitive_keys() {
        let sanitized = sanitize_query_for_log(Some(
            "protocol=shelly%2F1&session=abc&csrf=def&trace_id=abcd&custom=ok",
        ));
        assert!(sanitized.contains("protocol=shelly%2F1"));
        assert!(sanitized.contains("trace_id=abcd"));
        assert!(sanitized.contains("custom=ok"));
        assert!(sanitized.contains("session=<redacted>"));
        assert!(sanitized.contains("csrf=<redacted>"));
    }

    #[test]
    fn traceparent_parser_extracts_trace_and_span() {
        let parsed = parse_traceparent("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
            .expect("parse traceparent");
        assert_eq!(parsed.0, "4bf92f3577b34da6a3ce929d0e0e4736");
        assert_eq!(parsed.1, "00f067aa0ba902b7");
    }

    #[test]
    fn normalize_hex_id_rejects_invalid_lengths() {
        assert_eq!(
            normalize_hex_id("4bf92f3577b34da6a3ce929d0e0e4736", 32).as_deref(),
            Some("4bf92f3577b34da6a3ce929d0e0e4736")
        );
        assert!(normalize_hex_id("xyz", 32).is_none());
        assert!(normalize_hex_id("1234", 16).is_none());
    }

    #[test]
    fn malformed_protocol_messages_return_structured_errors() {
        let mut session = LiveSession::new(Box::<Counter>::default(), "root");
        session.mount().unwrap();

        let messages = messages_for_text_payload(&mut session, r#"{"type":"event""#);

        assert_eq!(messages.len(), 1);
        match &messages[0] {
            ServerMessage::Error { message, code } => {
                assert!(message.starts_with("invalid protocol message:"));
                assert_eq!(code.as_deref(), Some("invalid_protocol"));
            }
            other => panic!("unexpected message: {other:?}"),
        }
    }

    #[test]
    fn payload_size_errors_are_structured_and_close_with_size_code() {
        assert_eq!(
            payload_too_large_error(12, 8),
            ServerMessage::Error {
                message: "payload too large: 12 bytes exceeds 8 byte limit".to_string(),
                code: Some("payload_too_large".to_string()),
            }
        );

        let close = payload_too_large_close();
        assert_eq!(close.code, close_code::SIZE);
        assert_eq!(close.reason.as_str(), "payload too large");
    }

    #[test]
    fn binary_protocol_messages_return_structured_errors() {
        assert_eq!(
            unsupported_binary_error(),
            ServerMessage::Error {
                message: "binary protocol messages are not supported by Shelly v0".to_string(),
                code: Some("unsupported_message_type".to_string()),
            }
        );
    }

    #[test]
    fn signed_session_and_csrf_tokens_round_trip_for_websocket_auth() {
        let signer = TokenSigner::new(b"test secret".to_vec());
        let session = signer.sign_session("session-1", "/", "node-a");
        let csrf = signer.sign_csrf("session-1", "/");
        let resume = signer.sign_resume("session-1", "/");
        let query = parse_query(&format!("session={session}&csrf={csrf}"));

        let signed_session = verify_websocket_tokens(&signer, &query, "/").unwrap();
        assert_eq!(signed_session.session_id, "session-1");
        assert_eq!(signed_session.node_id.as_deref(), Some("node-a"));
        assert!(verify_websocket_tokens(&signer, &query, "/other").is_none());

        let mut tampered = query;
        tampered.insert("session".to_string(), "bad".to_string());
        assert!(verify_websocket_tokens(&signer, &tampered, "/").is_none());

        let bad_csrf = parse_query(&format!(
            "session={session}&csrf={}",
            signer.sign_csrf("session-1", "/different")
        ));
        assert!(verify_websocket_tokens(&signer, &bad_csrf, "/").is_none());

        let signed_resume = signer.verify_resume(&resume).unwrap();
        assert_eq!(signed_resume.session_id, "session-1");
        assert_eq!(signed_resume.path, "/");
        assert!(!signed_resume.nonce.is_empty());
    }

    #[test]
    fn token_signer_rejects_wrong_token_kinds() {
        let signer = TokenSigner::new(b"test secret".to_vec());
        let session = signer.sign_session("session-1", "/", "node-a");
        let csrf = signer.sign_csrf("session-1", "/");
        let resume = signer.sign_resume("session-1", "/");

        assert!(signer.verify_session(&csrf).is_none());
        assert!(signer.verify_resume(&session).is_none());
        assert!(!signer.verify_csrf("bad-token", "session-1", "/"));
        assert!(signer.verify_session(&resume).is_none());
    }

    #[test]
    fn correlation_and_reconnect_helpers_cover_resume_variants() {
        let base = test_correlation();
        let fallback = correlation_from_connect(
            &base,
            &ConnectHandshake {
                client_session_id: None,
                client_revision: 0,
                resume_token: None,
                tenant_id: None,
                trace_id: Some("not-hex".to_string()),
                span_id: Some("bad-span".to_string()),
                parent_span_id: Some("also-bad".to_string()),
                correlation_id: Some(String::new()),
                request_id: Some(String::new()),
            },
        );
        assert_eq!(fallback.trace_id, base.trace_id);
        assert_eq!(
            fallback.parent_span_id.as_deref(),
            Some(base.span_id.as_str())
        );
        assert_eq!(fallback.correlation_id, base.correlation_id);
        assert_eq!(fallback.request_id, base.request_id);
        assert_eq!(fallback.span_id.len(), 16);

        let connected = correlation_from_connect(
            &base,
            &ConnectHandshake {
                client_session_id: Some("session-1".to_string()),
                client_revision: 2,
                resume_token: Some("resume-1".to_string()),
                tenant_id: Some("tenant-a".to_string()),
                trace_id: Some("4bf92f3577b34da6a3ce929d0e0e4736".to_string()),
                span_id: Some("00f067aa0ba902b7".to_string()),
                parent_span_id: None,
                correlation_id: Some("corr-next".to_string()),
                request_id: Some("req-next".to_string()),
            },
        );
        assert_eq!(connected.trace_id, "4bf92f3577b34da6a3ce929d0e0e4736");
        assert_eq!(
            connected.parent_span_id.as_deref(),
            Some("00f067aa0ba902b7")
        );
        assert_eq!(connected.correlation_id.as_deref(), Some("corr-next"));
        assert_eq!(connected.request_id.as_deref(), Some("req-next"));
        assert_eq!(connected.span_id.len(), 16);

        let resumed = reconnect_event(
            "session-1",
            "/",
            &connected,
            true,
            ResumeStatus::Resumed,
            Some("token_match"),
        );
        assert_eq!(resumed.kind, TelemetryEventKind::Connect);
        assert_eq!(
            resumed.attributes.get("resume_status"),
            Some(&serde_json::json!("resumed"))
        );
        assert_eq!(
            resumed.attributes.get("resume_reason"),
            Some(&serde_json::json!("token_match"))
        );

        let fallback_event = reconnect_event(
            "session-1",
            "/",
            &connected,
            false,
            ResumeStatus::Fallback,
            None,
        );
        assert_eq!(
            fallback_event.attributes.get("resume_status"),
            Some(&serde_json::json!("fallback"))
        );
        assert!(!fallback_event.attributes.contains_key("resume_reason"));
    }

    #[test]
    fn cleanup_expired_snapshots_removes_stale_entries() {
        let mut snapshots = HashMap::new();
        snapshots.insert(
            "fresh".to_string(),
            ResumeSnapshot {
                session: LiveSession::new(Box::<Counter>::default(), "root"),
                route_pattern: "/".to_string(),
                resume_token: "resume-fresh".to_string(),
                expires_at: Instant::now() + Duration::from_secs(5),
            },
        );
        snapshots.insert(
            "stale".to_string(),
            ResumeSnapshot {
                session: LiveSession::new(Box::<Counter>::default(), "root"),
                route_pattern: "/".to_string(),
                resume_token: "resume-stale".to_string(),
                expires_at: Instant::now() - Duration::from_millis(1),
            },
        );

        cleanup_expired_snapshots(&mut snapshots);

        assert!(snapshots.contains_key("fresh"));
        assert!(!snapshots.contains_key("stale"));
    }

    #[tokio::test]
    async fn http_handlers_serve_client_js_and_initial_shell() {
        let state =
            test_app_state_with("/", SecurityConfig::default(), DistributedConfig::default());
        let js = client_js(
            State(state.clone()),
            Method::GET,
            HeaderMap::new(),
            Uri::from_static("/__shelly/client.js"),
        )
        .await
        .into_response();
        assert_eq!(js.status(), StatusCode::OK);
        assert_eq!(
            js.headers().get(header::CONTENT_TYPE),
            Some(&HeaderValue::from_static("text/javascript; charset=utf-8"))
        );
        assert!(js.headers().get("alt-svc").is_none());
        assert!(js.headers().get("x-shelly-transport").is_none());
        let js_body = to_bytes(js.into_body(), usize::MAX).await.expect("js body");
        assert_eq!(js_body.as_ref(), CLIENT_JS.as_bytes());
        let not_found = initial_handler(
            State(state.clone()),
            Method::GET,
            HeaderMap::new(),
            Uri::from_static("/missing"),
        )
        .await;
        assert_eq!(not_found.status(), StatusCode::NOT_FOUND);
        let not_found_body = to_bytes(not_found.into_body(), usize::MAX)
            .await
            .expect("not found body");
        assert!(String::from_utf8_lossy(&not_found_body).contains("/missing"));

        let ok = initial_handler(
            State(state),
            Method::GET,
            HeaderMap::new(),
            Uri::from_static("/"),
        )
        .await;
        assert_eq!(ok.status(), StatusCode::OK);
        assert!(ok.headers().get("alt-svc").is_none());
        assert!(ok.headers().get("x-shelly-transport").is_none());
        let body = to_bytes(ok.into_body(), usize::MAX)
            .await
            .expect("shell body");
        let html = String::from_utf8_lossy(&body);
        assert!(html.contains("window.__SHELLY"));
        assert!(html.contains("<div id=\"root\"><p>0</p></div>"));
        assert!(html.contains("sessionToken"));
        assert!(html.contains("csrfToken"));
    }

    #[tokio::test]
    async fn http_handlers_emit_http3_headers_when_configured() {
        let mut state =
            test_app_state_with("/", SecurityConfig::default(), DistributedConfig::default());
        Arc::make_mut(&mut state).transport_http = HttpTransportConfig {
            http3_alt_svc: Some(DEFAULT_HTTP3_ALT_SVC.to_string()),
            emit_diagnostics_header: true,
            primary_mode: TransportMode::WebSocket,
            fallback_modes: vec![TransportMode::ServerSentEvents, TransportMode::LongPoll],
            progressive_enhancement: true,
        };

        let js = client_js(
            State(state.clone()),
            Method::GET,
            HeaderMap::new(),
            Uri::from_static("/__shelly/client.js"),
        )
        .await
        .into_response();
        assert_eq!(
            js.headers().get("alt-svc"),
            Some(&HeaderValue::from_static(DEFAULT_HTTP3_ALT_SVC))
        );
        assert_eq!(
            js.headers().get("x-shelly-transport"),
            Some(&HeaderValue::from_static(
                "websocket; fallback=sse,long_poll; progressive=enabled; h3=advertised"
            ))
        );
        assert_eq!(
            js.headers().get("x-shelly-progressive-enhancement"),
            Some(&HeaderValue::from_static("enabled"))
        );

        let shell = initial_handler(
            State(state),
            Method::GET,
            HeaderMap::new(),
            Uri::from_static("/"),
        )
        .await;
        assert_eq!(
            shell.headers().get("alt-svc"),
            Some(&HeaderValue::from_static(DEFAULT_HTTP3_ALT_SVC))
        );
        assert_eq!(
            shell.headers().get("x-shelly-transport"),
            Some(&HeaderValue::from_static(
                "websocket; fallback=sse,long_poll; progressive=enabled; h3=advertised"
            ))
        );
    }

    #[tokio::test]
    async fn transport_capabilities_describe_degraded_profiles() {
        let mut state =
            test_app_state_with("/", SecurityConfig::default(), DistributedConfig::default());
        Arc::make_mut(&mut state).transport_http = HttpTransportConfig {
            http3_alt_svc: None,
            emit_diagnostics_header: true,
            primary_mode: TransportMode::WebSocket,
            fallback_modes: vec![TransportMode::ServerSentEvents, TransportMode::LongPoll],
            progressive_enhancement: true,
        };

        let response = transport_capabilities(
            State(state),
            Method::GET,
            HeaderMap::new(),
            Uri::from_static("/__shelly/transport"),
        )
        .await;

        assert_eq!(response.status(), StatusCode::OK);
        assert_eq!(
            response.headers().get("x-shelly-transport"),
            Some(&HeaderValue::from_static(
                "websocket; fallback=sse,long_poll; progressive=enabled; h3=disabled"
            ))
        );
        let body = to_bytes(response.into_body(), usize::MAX)
            .await
            .expect("transport capabilities body");
        let json: serde_json::Value =
            serde_json::from_slice(&body).expect("transport capabilities json");
        assert_eq!(json["protocol"], PROTOCOL_VERSION);
        assert_eq!(json["primary"], "websocket");
        assert_eq!(json["fallbacks"], serde_json::json!(["sse", "long_poll"]));
        assert_eq!(json["progressive_enhancement"], true);
        assert_eq!(json["http3_advertised"], false);
    }

    #[tokio::test]
    async fn ws_handler_enforces_guardrails_and_accepts_valid_upgrade() {
        let secret = b"test secret".to_vec();

        let (origin_base, origin_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .live("/", Counter::default),
        )
        .await;
        let mut origin_request = format!("{origin_base}/__shelly/ws/__root__?protocol=shelly/1")
            .into_client_request()
            .expect("origin request");
        origin_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://evil.example"));
        let origin_err = connect_async(origin_request)
            .await
            .expect_err("cross origin upgrade should fail");
        assert_eq!(ws_error_status(origin_err), StatusCode::FORBIDDEN);
        origin_server.abort();

        let (protocol_base, protocol_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .live("/", Counter::default),
        )
        .await;
        let mut protocol_request =
            format!("{protocol_base}/__shelly/ws/__root__?protocol=shelly/9")
                .into_client_request()
                .expect("protocol request");
        protocol_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let protocol_err = connect_async(protocol_request)
            .await
            .expect_err("unsupported protocol should fail");
        assert_eq!(ws_error_status(protocol_err), StatusCode::BAD_REQUEST);
        protocol_server.abort();

        let (unsigned_base, unsigned_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .live("/", Counter::default),
        )
        .await;
        let mut unsigned_request =
            format!("{unsigned_base}/__shelly/ws/__root__?protocol=shelly/1")
                .into_client_request()
                .expect("unsigned request");
        unsigned_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let unsigned_err = connect_async(unsigned_request)
            .await
            .expect_err("missing signed session should fail");
        assert_eq!(ws_error_status(unsigned_err), StatusCode::UNAUTHORIZED);
        unsigned_server.abort();

        let signer = TokenSigner::new(secret.clone());
        let mismatch_session = signer.sign_session("session-1", "/", "node-a");
        let mismatch_csrf = signer.sign_csrf("session-1", "/");
        let (affinity_base, affinity_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .with_node_id("node-b")
                .with_session_affinity_mode(SessionAffinityMode::Required)
                .live("/", Counter::default),
        )
        .await;
        let mut mismatch_request = format!(
            "{affinity_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={mismatch_session}&csrf={mismatch_csrf}"
        )
        .into_client_request()
        .expect("mismatch request");
        mismatch_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let mismatch_err = connect_async(mismatch_request)
            .await
            .expect_err("session-affinity mismatch should fail");
        assert_eq!(ws_error_status(mismatch_err), StatusCode::CONFLICT);
        affinity_server.abort();

        let valid_session = signer.sign_session("session-2", "/", "node-b");
        let valid_csrf = signer.sign_csrf("session-2", "/");
        let (ok_base, ok_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .with_node_id("node-b")
                .with_session_affinity_mode(SessionAffinityMode::Required)
                .live("/", Counter::default),
        )
        .await;
        let mut accepted_request = format!(
            "{ok_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={valid_session}&csrf={valid_csrf}"
        )
        .into_client_request()
        .expect("accepted request");
        accepted_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut socket, response) = connect_async(accepted_request)
            .await
            .expect("valid websocket upgrade should succeed");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-2",
            "last_revision": 0,
            "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
            "span_id": "00f067aa0ba902b7",
            "correlation_id": "corr-ws-test",
            "request_id": "req-ws-test"
        });
        socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send connect frame");
        let first = socket.next().await.expect("first server frame");
        assert!(matches!(first, Ok(WsMessage::Text(_))));
        let _ = socket.close(None).await;
        ok_server.abort();
    }

    #[tokio::test]
    async fn ws_connect_handshake_rejects_non_connect_and_protocol_mismatch_frames() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());

        let session_token = signer.sign_session("session-connect-reject", "/", "node-a");
        let csrf_token = signer.sign_csrf("session-connect-reject", "/");
        let (base, server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .live("/", Counter::default),
        )
        .await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("connect-required request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut socket, response) = connect_async(request)
            .await
            .expect("websocket connect should succeed");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let event_first = serde_json::json!({
            "type": "event",
            "event": "inc",
            "target": null,
            "value": null,
            "metadata": {}
        });
        socket
            .send(WsMessage::Text(event_first.to_string().into()))
            .await
            .expect("send non-connect first frame");
        let first = socket.next().await.expect("first rejection frame");
        match first {
            Ok(WsMessage::Text(text)) => {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("error frame should decode");
                assert!(matches!(
                    message,
                    ServerMessage::Error { code: Some(code), .. } if code == "connect_required"
                ));
            }
            other => panic!("unexpected first rejection frame: {other:?}"),
        }
        let _ = socket.close(None).await;
        server.abort();

        let session_token = signer.sign_session("session-connect-proto", "/", "node-a");
        let csrf_token = signer.sign_csrf("session-connect-proto", "/");
        let (base, server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .live("/", Counter::default),
        )
        .await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("protocol mismatch request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut socket, response) = connect_async(request)
            .await
            .expect("websocket connect should succeed");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let unsupported_connect = serde_json::json!({
            "type": "connect",
            "protocol": "shelly/9",
            "session_id": "session-connect-proto",
            "last_revision": 0
        });
        socket
            .send(WsMessage::Text(unsupported_connect.to_string().into()))
            .await
            .expect("send unsupported connect frame");
        let first = socket.next().await.expect("first rejection frame");
        match first {
            Ok(WsMessage::Text(text)) => {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("error frame should decode");
                assert!(matches!(
                    message,
                    ServerMessage::Error { code: Some(code), .. } if code == "unsupported_protocol"
                ));
            }
            other => panic!("unexpected unsupported protocol frame: {other:?}"),
        }
        let _ = socket.close(None).await;
        server.abort();
    }

    #[tokio::test]
    async fn ws_resume_reconcile_and_fallback_paths_are_exercised() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());
        let session_id = "session-resume-flow";
        let session_token = signer.sign_session(session_id, "/", "node-a");
        let csrf_token = signer.sign_csrf(session_id, "/");

        let (base, server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .with_resume_ttl_ms(5_000)
                .live("/", Counter::default),
        )
        .await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("fresh connect request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut socket, response) = connect_async(request)
            .await
            .expect("fresh websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect_fresh = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": session_id,
            "last_revision": 0
        });
        socket
            .send(WsMessage::Text(connect_fresh.to_string().into()))
            .await
            .expect("send fresh connect");

        let mut resume_token = None::<String>;
        let mut hello_seen = false;
        for _ in 0..4 {
            let frame = socket.next().await.expect("fresh server frame");
            if let Ok(WsMessage::Text(text)) = frame {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("fresh frame should decode");
                if let ServerMessage::Hello {
                    resume_status,
                    resume_token: token,
                    ..
                } = message
                {
                    hello_seen = true;
                    assert_eq!(resume_status, Some(ResumeStatus::Fresh));
                    resume_token = token;
                    break;
                }
            }
        }
        assert!(hello_seen, "expected hello frame in fresh connect flow");
        let resume_token = resume_token.expect("fresh hello must include resume token");

        let increment = serde_json::json!({
            "type": "event",
            "event": "inc",
            "target": null,
            "value": null,
            "metadata": {}
        });
        socket
            .send(WsMessage::Text(increment.to_string().into()))
            .await
            .expect("send increment event");
        let mut patch_seen = false;
        for _ in 0..6 {
            let frame = socket.next().await.expect("event response frame");
            if let Ok(WsMessage::Text(text)) = frame {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("event response should decode");
                if let ServerMessage::Patch { html, revision, .. } = message {
                    assert!(html.contains("<p>1</p>") || html.contains("<p>0</p>"));
                    assert!(revision >= 1);
                    patch_seen = true;
                    break;
                }
            }
        }
        assert!(patch_seen, "expected at least one patch after increment");
        let _ = socket.close(None).await;
        tokio::time::sleep(Duration::from_millis(25)).await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("resume request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut resumed_socket, response) = connect_async(request)
            .await
            .expect("resume websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let resume_connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": session_id,
            "last_revision": 0,
            "resume_token": resume_token
        });
        resumed_socket
            .send(WsMessage::Text(resume_connect.to_string().into()))
            .await
            .expect("send resume connect");

        let mut resumed_hello = false;
        let mut reconciled_patch = false;
        for _ in 0..8 {
            let frame = resumed_socket.next().await.expect("resume response frame");
            if let Ok(WsMessage::Text(text)) = frame {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("resume frame should decode");
                match message {
                    ServerMessage::Hello {
                        resume_status,
                        server_revision,
                        ..
                    } => {
                        assert_eq!(resume_status, Some(ResumeStatus::Resumed));
                        assert!(server_revision.is_some());
                        resumed_hello = true;
                    }
                    ServerMessage::Patch { .. } => {
                        reconciled_patch = true;
                    }
                    _ => {}
                }
                if resumed_hello && reconciled_patch {
                    break;
                }
            }
        }
        assert!(resumed_hello, "expected resumed hello");
        assert!(reconciled_patch, "expected reconciliation patch");
        let _ = resumed_socket.close(None).await;
        tokio::time::sleep(Duration::from_millis(25)).await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("fallback request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut fallback_socket, response) = connect_async(request)
            .await
            .expect("fallback websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let fallback_connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": session_id,
            "last_revision": 3,
            "resume_token": "invalid-token"
        });
        fallback_socket
            .send(WsMessage::Text(fallback_connect.to_string().into()))
            .await
            .expect("send fallback connect");

        let mut fallback_seen = false;
        for _ in 0..6 {
            let frame = fallback_socket.next().await.expect("fallback frame");
            if let Ok(WsMessage::Text(text)) = frame {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("fallback frame should decode");
                if let ServerMessage::Hello {
                    resume_status,
                    resume_reason,
                    ..
                } = message
                {
                    assert_eq!(resume_status, Some(ResumeStatus::Fallback));
                    assert_eq!(resume_reason.as_deref(), Some("resume_token_invalid"));
                    fallback_seen = true;
                    break;
                }
            }
        }
        assert!(fallback_seen, "expected fallback hello");
        let _ = fallback_socket.close(None).await;
        server.abort();
    }

    #[tokio::test]
    async fn ws_connect_handshake_enforces_signed_session_id_match() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());
        let session_token = signer.sign_session("session-a", "/", "node-a");
        let csrf_token = signer.sign_csrf("session-a", "/");
        let (base, server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .live("/", Counter::default),
        )
        .await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("session mismatch request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut socket, response) = connect_async(request)
            .await
            .expect("websocket connect should succeed");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-b",
            "last_revision": 0
        });
        socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send connect");
        let frame = socket.next().await.expect("session mismatch frame");
        match frame {
            Ok(WsMessage::Text(text)) => {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("frame should decode");
                assert!(matches!(
                    message,
                    ServerMessage::Error { code: Some(code), .. } if code == "session_mismatch"
                ));
            }
            other => panic!("unexpected session mismatch frame: {other:?}"),
        }
        let _ = socket.close(None).await;
        server.abort();
    }

    #[tokio::test]
    async fn ws_connect_handshake_can_be_rejected_by_quota_and_authorization_hooks() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());

        let quota_session = signer.sign_session("session-quota", "/", "node-a");
        let quota_csrf = signer.sign_csrf("session-quota", "/");
        let (quota_base, quota_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .with_quota_policy(|ctx| {
                    if ctx.operation == SecurityOperation::Connect {
                        QuotaDecision::deny("quota_exceeded", "connect quota exceeded")
                    } else {
                        QuotaDecision::allow()
                    }
                })
                .live("/", Counter::default),
        )
        .await;

        let mut quota_request = format!(
            "{quota_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={quota_session}&csrf={quota_csrf}"
        )
        .into_client_request()
        .expect("quota request");
        quota_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut quota_socket, response) = connect_async(quota_request)
            .await
            .expect("quota websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-quota",
            "last_revision": 0
        });
        quota_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send quota connect");
        let frame = quota_socket.next().await.expect("quota rejection frame");
        match frame {
            Ok(WsMessage::Text(text)) => {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("quota frame should decode");
                assert!(matches!(
                    message,
                    ServerMessage::Error { code: Some(code), .. } if code == "quota_exceeded"
                ));
            }
            other => panic!("unexpected quota frame: {other:?}"),
        }
        let _ = quota_socket.close(None).await;
        quota_server.abort();

        let auth_session = signer.sign_session("session-auth", "/", "node-a");
        let auth_csrf = signer.sign_csrf("session-auth", "/");
        let (auth_base, auth_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .with_authorization_hook(|ctx| {
                    if ctx.operation == SecurityOperation::Connect {
                        AuthorizationDecision::deny("unauthorized", "connect denied")
                    } else {
                        AuthorizationDecision::allow()
                    }
                })
                .live("/", Counter::default),
        )
        .await;

        let mut auth_request = format!(
            "{auth_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={auth_session}&csrf={auth_csrf}"
        )
        .into_client_request()
        .expect("authorization request");
        auth_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut auth_socket, response) = connect_async(auth_request)
            .await
            .expect("authorization websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-auth",
            "last_revision": 0
        });
        auth_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send authorization connect");
        let frame = auth_socket
            .next()
            .await
            .expect("authorization rejection frame");
        match frame {
            Ok(WsMessage::Text(text)) => {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("authorization frame should decode");
                assert!(matches!(
                    message,
                    ServerMessage::Error { code: Some(code), .. } if code == "unauthorized"
                ));
            }
            other => panic!("unexpected authorization frame: {other:?}"),
        }
        let _ = auth_socket.close(None).await;
        auth_server.abort();
    }

    #[tokio::test]
    async fn ws_resume_rejects_tenant_context_mismatch() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());
        let session_id = "session-tenant-resume";
        let session_token = signer.sign_session(session_id, "/", "node-a");
        let csrf_token = signer.sign_csrf(session_id, "/");
        let (base, server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .with_resume_ttl_ms(5_000)
                .live("/", Counter::default),
        )
        .await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("first tenant connect request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut socket, response) = connect_async(request)
            .await
            .expect("first tenant websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": session_id,
            "last_revision": 0,
            "tenant_id": "tenant-a"
        });
        socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send first tenant connect");

        let mut resume_token = None::<String>;
        for _ in 0..4 {
            let frame = socket.next().await.expect("first tenant frame");
            if let Ok(WsMessage::Text(text)) = frame {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("first tenant frame decode");
                if let ServerMessage::Hello {
                    resume_token: token,
                    ..
                } = message
                {
                    resume_token = token;
                    break;
                }
            }
        }
        let resume_token = resume_token.expect("tenant hello should include resume token");
        let _ = socket.close(None).await;
        tokio::time::sleep(Duration::from_millis(25)).await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("tenant mismatch reconnect request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut reconnect_socket, response) = connect_async(request)
            .await
            .expect("tenant mismatch websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": session_id,
            "last_revision": 0,
            "tenant_id": "tenant-b",
            "resume_token": resume_token
        });
        reconnect_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send tenant mismatch reconnect");
        let frame = reconnect_socket
            .next()
            .await
            .expect("tenant mismatch error frame");
        match frame {
            Ok(WsMessage::Text(text)) => {
                let message: ServerMessage =
                    serde_json::from_str(text.as_str()).expect("tenant mismatch frame decode");
                assert!(matches!(
                    message,
                    ServerMessage::Error { code: Some(code), .. } if code == "tenant_mismatch"
                ));
            }
            other => panic!("unexpected tenant mismatch frame: {other:?}"),
        }
        let _ = reconnect_socket.close(None).await;
        server.abort();
    }

    #[tokio::test]
    async fn ws_text_event_rejections_cover_tenant_quota_and_authorization_paths() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());

        let session_id = "session-tenant-text";
        let session_token = signer.sign_session(session_id, "/", "node-a");
        let csrf_token = signer.sign_csrf(session_id, "/");
        let (base, server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .live("/", Counter::default),
        )
        .await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("text tenant request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut socket, response) = connect_async(request)
            .await
            .expect("text tenant websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": session_id,
            "last_revision": 0,
            "tenant_id": "tenant-a"
        });
        socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send tenant connect");
        await_hello(&mut socket).await;

        let tenant_conflict_event = serde_json::json!({
            "type": "event",
            "event": "inc",
            "target": null,
            "value": { "tenant_id": "tenant-b" },
            "metadata": { "tenant_id": "tenant-b" }
        });
        socket
            .send(WsMessage::Text(tenant_conflict_event.to_string().into()))
            .await
            .expect("send tenant conflict event");
        await_error_code(&mut socket, "tenant_mismatch").await;
        let _ = socket.close(None).await;
        server.abort();

        let quota_session = signer.sign_session("session-quota-text", "/", "node-a");
        let quota_csrf = signer.sign_csrf("session-quota-text", "/");
        let (quota_base, quota_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .with_quota_policy(|ctx| {
                    if ctx.operation == SecurityOperation::Event {
                        QuotaDecision::deny("quota_exceeded", "event quota exceeded")
                    } else {
                        QuotaDecision::allow()
                    }
                })
                .live("/", Counter::default),
        )
        .await;

        let mut quota_request = format!(
            "{quota_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={quota_session}&csrf={quota_csrf}"
        )
        .into_client_request()
        .expect("quota text request");
        quota_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut quota_socket, response) = connect_async(quota_request)
            .await
            .expect("quota text websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-quota-text",
            "last_revision": 0,
            "tenant_id": "tenant-a"
        });
        quota_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send quota text connect");
        await_hello(&mut quota_socket).await;
        let event = serde_json::json!({
            "type": "event",
            "event": "inc",
            "target": null,
            "value": { "tenant_id": "tenant-a" },
            "metadata": { "tenant_id": "tenant-a" }
        });
        quota_socket
            .send(WsMessage::Text(event.to_string().into()))
            .await
            .expect("send quota text event");
        await_error_code(&mut quota_socket, "quota_exceeded").await;
        let _ = quota_socket.close(None).await;
        quota_server.abort();

        let auth_session = signer.sign_session("session-auth-text", "/", "node-a");
        let auth_csrf = signer.sign_csrf("session-auth-text", "/");
        let (auth_base, auth_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .with_authorization_hook(|ctx| {
                    if ctx.operation == SecurityOperation::Event {
                        AuthorizationDecision::deny("unauthorized", "event denied")
                    } else {
                        AuthorizationDecision::allow()
                    }
                })
                .live("/", Counter::default),
        )
        .await;
        let mut auth_request = format!(
            "{auth_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={auth_session}&csrf={auth_csrf}"
        )
        .into_client_request()
        .expect("auth text request");
        auth_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut auth_socket, response) = connect_async(auth_request)
            .await
            .expect("auth text websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-auth-text",
            "last_revision": 0,
            "tenant_id": "tenant-a"
        });
        auth_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send auth text connect");
        await_hello(&mut auth_socket).await;
        let event = serde_json::json!({
            "type": "event",
            "event": "inc",
            "target": null,
            "value": { "tenant_id": "tenant-a" },
            "metadata": { "tenant_id": "tenant-a" }
        });
        auth_socket
            .send(WsMessage::Text(event.to_string().into()))
            .await
            .expect("send auth text event");
        await_error_code(&mut auth_socket, "unauthorized").await;
        let _ = auth_socket.close(None).await;
        auth_server.abort();
    }

    #[tokio::test]
    async fn ws_overload_and_binary_branches_emit_expected_errors() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());

        let shed_session = signer.sign_session("session-overload", "/", "node-a");
        let shed_csrf = signer.sign_csrf("session-overload", "/");
        let (shed_base, shed_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .with_overload_budgets(OverloadBudgets {
                    session_queue_depth: usize::MAX,
                    session_bytes_per_sec: 1,
                    session_cpu_ms_per_sec: u64::MAX,
                    tenant_queue_depth: usize::MAX,
                    tenant_bytes_per_sec: usize::MAX,
                    tenant_cpu_ms_per_sec: u64::MAX,
                })
                .with_overload_shed_policy(OverloadShedPolicy::Strict)
                .live("/", Counter::default),
        )
        .await;

        let mut shed_request = format!(
            "{shed_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={shed_session}&csrf={shed_csrf}"
        )
        .into_client_request()
        .expect("overload request");
        shed_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut shed_socket, response) = connect_async(shed_request)
            .await
            .expect("overload websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-overload",
            "last_revision": 0
        });
        shed_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send overload connect");
        await_hello(&mut shed_socket).await;
        let event = serde_json::json!({
            "type": "event",
            "event": "inc",
            "target": null,
            "value": { "payload": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
            "metadata": {}
        });
        shed_socket
            .send(WsMessage::Text(event.to_string().into()))
            .await
            .expect("send overload event");
        await_error_code(&mut shed_socket, "overload_shed").await;
        let _ = shed_socket.close(None).await;
        shed_server.abort();

        let binary_large_session = signer.sign_session("session-binary-large", "/", "node-a");
        let binary_large_csrf = signer.sign_csrf("session-binary-large", "/");
        let (binary_large_base, binary_large_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .with_max_message_size(8)
                .live("/", Counter::default),
        )
        .await;
        let mut binary_large_request = format!(
            "{binary_large_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={binary_large_session}&csrf={binary_large_csrf}"
        )
        .into_client_request()
        .expect("binary large request");
        binary_large_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut binary_large_socket, response) = connect_async(binary_large_request)
            .await
            .expect("binary large websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-binary-large",
            "last_revision": 0
        });
        binary_large_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send binary large connect");
        await_hello(&mut binary_large_socket).await;
        binary_large_socket
            .send(WsMessage::Binary(vec![0_u8; 64].into()))
            .await
            .expect("send oversized binary");
        let mut saw_terminal_frame = false;
        for _ in 0..10 {
            let Some(frame) = binary_large_socket.next().await else {
                saw_terminal_frame = true;
                break;
            };
            match frame {
                Ok(WsMessage::Text(text)) => {
                    let message: ServerMessage =
                        serde_json::from_str(text.as_str()).expect("payload frame decode");
                    if matches!(
                        message,
                        ServerMessage::Error {
                            code: Some(ref code),
                            ..
                        } if code == "payload_too_large"
                    ) {
                        saw_terminal_frame = true;
                        break;
                    }
                }
                Ok(WsMessage::Close(_)) => {
                    saw_terminal_frame = true;
                    break;
                }
                _ => {}
            }
        }
        assert!(
            saw_terminal_frame,
            "expected oversized binary path to terminate with error/close/no-frame"
        );
        let _ = binary_large_socket.close(None).await;
        binary_large_server.abort();

        let binary_rate_session = signer.sign_session("session-binary-rate", "/", "node-a");
        let binary_rate_csrf = signer.sign_csrf("session-binary-rate", "/");
        let (binary_rate_base, binary_rate_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .with_rate_limiter(|ctx| ctx.message_kind != "binary")
                .live("/", Counter::default),
        )
        .await;
        let mut binary_rate_request = format!(
            "{binary_rate_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={binary_rate_session}&csrf={binary_rate_csrf}"
        )
        .into_client_request()
        .expect("binary rate request");
        binary_rate_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut binary_rate_socket, response) = connect_async(binary_rate_request)
            .await
            .expect("binary rate websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-binary-rate",
            "last_revision": 0
        });
        binary_rate_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send binary rate connect");
        await_hello(&mut binary_rate_socket).await;
        binary_rate_socket
            .send(WsMessage::Binary(vec![1_u8; 4].into()))
            .await
            .expect("send binary for rate limiter");
        await_error_code(&mut binary_rate_socket, "rate_limited").await;
        let _ = binary_rate_socket.close(None).await;
        binary_rate_server.abort();

        let binary_quota_session = signer.sign_session("session-binary-quota", "/", "node-a");
        let binary_quota_csrf = signer.sign_csrf("session-binary-quota", "/");
        let (binary_quota_base, binary_quota_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret.clone())
                .with_allowed_origin("https://example.test")
                .with_quota_policy(|ctx| {
                    if ctx.operation == SecurityOperation::Binary {
                        QuotaDecision::deny("quota_exceeded", "binary quota exceeded")
                    } else {
                        QuotaDecision::allow()
                    }
                })
                .live("/", Counter::default),
        )
        .await;
        let mut binary_quota_request = format!(
            "{binary_quota_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={binary_quota_session}&csrf={binary_quota_csrf}"
        )
        .into_client_request()
        .expect("binary quota request");
        binary_quota_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut binary_quota_socket, response) = connect_async(binary_quota_request)
            .await
            .expect("binary quota websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-binary-quota",
            "last_revision": 0
        });
        binary_quota_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send binary quota connect");
        await_hello(&mut binary_quota_socket).await;
        binary_quota_socket
            .send(WsMessage::Binary(vec![2_u8; 4].into()))
            .await
            .expect("send binary for quota");
        await_error_code(&mut binary_quota_socket, "quota_exceeded").await;
        let _ = binary_quota_socket.close(None).await;
        binary_quota_server.abort();

        let binary_auth_session = signer.sign_session("session-binary-auth", "/", "node-a");
        let binary_auth_csrf = signer.sign_csrf("session-binary-auth", "/");
        let (binary_auth_base, binary_auth_server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .with_authorization_hook(|ctx| {
                    if ctx.operation == SecurityOperation::Binary {
                        AuthorizationDecision::deny("unauthorized", "binary denied")
                    } else {
                        AuthorizationDecision::allow()
                    }
                })
                .live("/", Counter::default),
        )
        .await;
        let mut binary_auth_request = format!(
            "{binary_auth_base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={binary_auth_session}&csrf={binary_auth_csrf}"
        )
        .into_client_request()
        .expect("binary auth request");
        binary_auth_request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));
        let (mut binary_auth_socket, response) = connect_async(binary_auth_request)
            .await
            .expect("binary auth websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-binary-auth",
            "last_revision": 0
        });
        binary_auth_socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send binary auth connect");
        await_hello(&mut binary_auth_socket).await;
        binary_auth_socket
            .send(WsMessage::Binary(vec![3_u8; 4].into()))
            .await
            .expect("send binary for auth");
        await_error_code(&mut binary_auth_socket, "unauthorized").await;
        let _ = binary_auth_socket.close(None).await;
        binary_auth_server.abort();
    }

    #[tokio::test]
    async fn outbound_frame_helpers_enqueue_pong_and_close_messages() {
        let (sender, mut receiver) = mpsc::channel(4);
        let config = OutboundConfig::default();
        let telemetry = Arc::new(TelemetryPipeline::disabled());
        let correlation = test_correlation();

        assert!(matches!(
            queue_pong_frame(
                &sender,
                vec![1, 2, 3],
                &config,
                &telemetry,
                &correlation,
                "/",
                "session-1",
            ),
            OutboundQueuePush::Queued
        ));
        match receiver.recv().await {
            Some(OutboundEnvelope::Pong(payload)) => assert_eq!(payload, vec![1, 2, 3]),
            other => panic!("unexpected envelope: {other:?}"),
        }

        let close = axum::extract::ws::CloseFrame {
            code: close_code::NORMAL,
            reason: "closing".into(),
        };
        assert!(matches!(
            queue_close_frame(
                &sender,
                Some(close),
                &config,
                &telemetry,
                &correlation,
                "/",
                "session-1",
            ),
            OutboundQueuePush::Queued
        ));
        match receiver.recv().await {
            Some(OutboundEnvelope::Close(Some(frame))) => {
                assert_eq!(frame.code, close_code::NORMAL);
                assert_eq!(frame.reason, "closing");
            }
            other => panic!("unexpected envelope: {other:?}"),
        }
    }

    #[test]
    fn cross_origin_websocket_requests_are_rejected_by_default() {
        let security = SecurityConfig {
            signer: TokenSigner::new(b"test secret".to_vec()),
            ..SecurityConfig::default()
        };
        let mut headers = HeaderMap::new();
        headers.insert(header::HOST, HeaderValue::from_static("example.test"));
        headers.insert(
            header::ORIGIN,
            HeaderValue::from_static("https://evil.example"),
        );

        assert!(!origin_allowed(&headers, &security));

        headers.insert(
            header::ORIGIN,
            HeaderValue::from_static("https://example.test"),
        );
        assert!(origin_allowed(&headers, &security));
    }

    #[test]
    fn explicitly_allowed_origins_are_accepted() {
        let security = SecurityConfig {
            signer: TokenSigner::new(b"test secret".to_vec()),
            allowed_origins: std::sync::Arc::new(vec!["https://app.example".to_string()]),
            rate_limiter: None,
            authorization: None,
            quota_policy: None,
        };
        let mut headers = HeaderMap::new();
        headers.insert(header::HOST, HeaderValue::from_static("api.example"));
        headers.insert(
            header::ORIGIN,
            HeaderValue::from_static("https://app.example"),
        );

        assert!(origin_allowed(&headers, &security));
    }

    #[test]
    fn session_affinity_policy_is_explicit_and_testable() {
        let distributed = DistributedConfig {
            node_id: "node-b".to_string(),
            session_affinity: SessionAffinityMode::Required,
        };
        let signed_session = SignedSession {
            session_id: "session-1".to_string(),
            path: "/".to_string(),
            node_id: Some("node-a".to_string()),
        };
        let mismatch = session_affinity_mismatch(&distributed, &signed_session, "/").unwrap();
        assert_eq!(mismatch.session_id, "session-1");
        assert_eq!(mismatch.current_node_id, "node-b");
        assert_eq!(mismatch.token_node_id.as_deref(), Some("node-a"));

        let matched = SignedSession {
            node_id: Some("node-b".to_string()),
            ..signed_session
        };
        assert!(session_affinity_mismatch(&distributed, &matched, "/").is_none());
    }

    #[test]
    fn session_affinity_optional_mode_and_id_generators_cover_additional_paths() {
        let distributed = DistributedConfig {
            node_id: "node-b".to_string(),
            session_affinity: SessionAffinityMode::Disabled,
        };
        let signed_session = SignedSession {
            session_id: "session-1".to_string(),
            path: "/".to_string(),
            node_id: Some("node-a".to_string()),
        };
        assert!(session_affinity_mismatch(&distributed, &signed_session, "/").is_none());

        let trace_id = super::generate_trace_id();
        let span_id = super::generate_span_id();
        assert_eq!(trace_id.len(), 32);
        assert_eq!(span_id.len(), 16);
        assert!(trace_id.chars().all(|ch| ch.is_ascii_hexdigit()));
        assert!(span_id.chars().all(|ch| ch.is_ascii_hexdigit()));

        let now_ms = now_unix_ms();
        assert!(now_ms > 0);

        let chrono_ms = super::chrono_like_timestamp();
        assert!(chrono_ms.chars().all(|ch| ch.is_ascii_digit()));
    }

    #[test]
    fn durable_release_and_acquire_no_store_paths_are_explicit() {
        let durable = DurableRuntimeConfig::default();
        // Explicitly exercise no-op release branch when durable store / lease are absent.
        durable_release_lease(&durable, "session-none", None);
        durable_release_lease(
            &durable,
            "session-none",
            Some(&super::DurableLeaseHandle {
                owner_node_id: "node-a".to_string(),
                fence_token: 1,
            }),
        );

        let distributed = DistributedConfig::default();
        let acquired = durable_acquire_lease(&durable, &distributed, "session-none", "/")
            .expect("no-store acquire should not fail");
        assert!(acquired.is_none());
    }

    #[tokio::test]
    async fn ws_connect_handshake_rejects_session_id_mismatch() {
        let secret = b"test secret".to_vec();
        let signer = TokenSigner::new(secret.clone());
        let session_token = signer.sign_session("session-match", "/", "node-a");
        let csrf_token = signer.sign_csrf("session-match", "/");

        let (base, server) = spawn_test_router(
            ShellyRouter::new()
                .with_secret(secret)
                .with_allowed_origin("https://example.test")
                .live("/", Counter::default),
        )
        .await;

        let mut request = format!(
            "{base}/__shelly/ws/__root__?protocol={PROTOCOL_VERSION}&session={session_token}&csrf={csrf_token}"
        )
        .into_client_request()
        .expect("session mismatch request");
        request
            .headers_mut()
            .insert("origin", HeaderValue::from_static("https://example.test"));

        let (mut socket, response) = connect_async(request)
            .await
            .expect("session mismatch websocket should connect");
        assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);

        let connect = serde_json::json!({
            "type": "connect",
            "protocol": PROTOCOL_VERSION,
            "session_id": "session-other",
            "last_revision": 0
        });
        socket
            .send(WsMessage::Text(connect.to_string().into()))
            .await
            .expect("send mismatched connect handshake");

        await_error_code(&mut socket, "session_mismatch").await;
        let _ = socket.close(None).await;
        server.abort();
    }

    #[test]
    fn durable_store_enforces_lease_conflicts_and_force_takeover() {
        let store = InMemoryDurableSessionStore::new();
        let first = store
            .acquire_lease(DurableLeaseRequest {
                session_id: "session-1".to_string(),
                node_id: "node-a".to_string(),
                ttl_ms: 60_000,
                takeover_policy: DurableTakeoverPolicy::AllowExpired,
            })
            .expect("node-a acquires first lease");
        assert_eq!(first.owner_node_id, "node-a");
        assert_eq!(first.fence_token, 1);

        let conflict = store
            .acquire_lease(DurableLeaseRequest {
                session_id: "session-1".to_string(),
                node_id: "node-b".to_string(),
                ttl_ms: 60_000,
                takeover_policy: DurableTakeoverPolicy::Deny,
            })
            .expect_err("node-b should be rejected while node-a owns lease");
        assert_eq!(conflict.code, "lease_conflict");

        let takeover = store
            .acquire_lease(DurableLeaseRequest {
                session_id: "session-1".to_string(),
                node_id: "node-b".to_string(),
                ttl_ms: 60_000,
                takeover_policy: DurableTakeoverPolicy::Force,
            })
            .expect("force takeover should transfer ownership");
        assert_eq!(takeover.owner_node_id, "node-b");
        assert_eq!(takeover.transferred_from.as_deref(), Some("node-a"));
        assert_eq!(takeover.fence_token, 2);
    }

    #[test]
    fn durable_force_takeover_invalidates_stale_owner_fence() {
        let store = InMemoryDurableSessionStore::new();
        let first = store
            .acquire_lease(DurableLeaseRequest {
                session_id: "session-2".to_string(),
                node_id: "node-a".to_string(),
                ttl_ms: 60_000,
                takeover_policy: DurableTakeoverPolicy::AllowExpired,
            })
            .expect("node-a acquires first lease");

        let takeover = store
            .acquire_lease(DurableLeaseRequest {
                session_id: "session-2".to_string(),
                node_id: "node-b".to_string(),
                ttl_ms: 60_000,
                takeover_policy: DurableTakeoverPolicy::Force,
            })
            .expect("node-b force takes ownership");

        let stale_renew = store
            .renew_lease("session-2", "node-a", first.fence_token, 60_000)
            .expect_err("stale owner should not renew after takeover");
        assert_eq!(stale_renew.code, "lease_not_owner");

        let stale_append = store
            .append_journal_entry(
                "session-2",
                "node-a",
                first.fence_token,
                ClientMessage::Event {
                    event: "inc".to_string(),
                    target: None,
                    value: serde_json::Value::Null,
                    metadata: serde_json::Map::new(),
                },
                64,
            )
            .expect_err("stale owner should not append journal after takeover");
        assert_eq!(stale_append.code, "lease_not_owner");

        store.release_lease("session-2", "node-a", first.fence_token);

        let renewed_owner = store
            .renew_lease("session-2", "node-b", takeover.fence_token, 60_000)
            .expect("current owner keeps lease after stale release");
        assert_eq!(renewed_owner.owner_node_id, "node-b");
        assert_eq!(renewed_owner.fence_token, takeover.fence_token);
    }

    #[test]
    fn durable_recovery_replays_journal_entries_after_owner_failover() {
        let store = Arc::new(InMemoryDurableSessionStore::new());
        let lease = store
            .acquire_lease(DurableLeaseRequest {
                session_id: "session-1".to_string(),
                node_id: "node-a".to_string(),
                ttl_ms: 60_000,
                takeover_policy: DurableTakeoverPolicy::AllowExpired,
            })
            .expect("node-a acquires lease");
        store.save_snapshot(
            "session-1",
            DurableSessionSnapshot {
                route_path: "/".to_string(),
                route_pattern: "/".to_string(),
                target_id: "root".to_string(),
                revision: 0,
                resume_token: "resume-1".to_string(),
                owner_node_id: "node-a".to_string(),
                updated_at_unix_ms: 0,
            },
        );
        store
            .append_journal_entry(
                "session-1",
                "node-a",
                lease.fence_token,
                ClientMessage::Event {
                    event: "inc".to_string(),
                    target: None,
                    value: serde_json::Value::Null,
                    metadata: serde_json::Map::new(),
                },
                128,
            )
            .expect("append first durable event");
        store
            .append_journal_entry(
                "session-1",
                "node-a",
                lease.fence_token,
                ClientMessage::Event {
                    event: "inc".to_string(),
                    target: None,
                    value: serde_json::Value::Null,
                    metadata: serde_json::Map::new(),
                },
                128,
            )
            .expect("append second durable event");
        store.release_lease("session-1", "node-a", lease.fence_token);

        let routes = Arc::new(vec![LiveRoute::new(
            "/".to_string(),
            Arc::new(|| Box::<Counter>::default()),
        )]);
        let telemetry: Arc<dyn TelemetrySink> = Arc::new(TelemetryPipeline::disabled());
        let config = SocketConfig {
            routes,
            target_id: "root".to_string(),
            route_path: "/".to_string(),
            signed_session_id: "session-1".to_string(),
            max_message_size: 64 * 1024,
            pubsub: PubSub::default(),
            uploads: UploadConfig::default(),
            security: SecurityConfig::default(),
            telemetry: Arc::new(TelemetryPipeline::disabled()),
            correlation: test_correlation(),
            reconnect: ReconnectConfig::default(),
            distributed: DistributedConfig::default(),
            durable: DurableRuntimeConfig {
                store: Some(store),
                ..DurableRuntimeConfig::default()
            },
            outbound: OutboundConfig::default(),
            render: super::RenderConfig::default(),
            overload: OverloadConfig::default(),
        };

        let recovered = recover_from_durable_record(&config, "session-1", &telemetry)
            .expect("durable recovery should rebuild session");
        assert_eq!(recovered.replayed_entries, 2);
        assert_eq!(recovered.source_owner_node_id, "node-a");
        assert_eq!(recovered.snapshot.session.revision(), 2);
        assert_eq!(recovered.snapshot.route_pattern, "/");
        assert_eq!(recovered.snapshot.session.route_path(), "/");
    }

    #[test]
    fn rate_limiter_hook_can_reject_messages() {
        let mut security = SecurityConfig {
            signer: TokenSigner::new(b"test secret".to_vec()),
            ..SecurityConfig::default()
        };
        security.rate_limiter = Some(std::sync::Arc::new(|ctx| {
            ctx.route_path == "/" && ctx.message_kind == "text" && ctx.session_id == "allowed"
        }));

        assert!(!rate_limited(&security, "/", "allowed", "text"));
        assert!(rate_limited(&security, "/", "blocked", "text"));
        assert_eq!(
            rate_limited_error(),
            ServerMessage::Error {
                message: "rate limit exceeded".to_string(),
                code: Some("rate_limited".to_string()),
            }
        );
    }

    #[test]
    fn rate_limited_defaults_to_false_without_hook() {
        let security = SecurityConfig::default();
        assert!(!rate_limited(&security, "/", "session-1", "text"));
    }

    #[test]
    fn security_operation_mapping_covers_navigation_and_upload_variants() {
        let upload_start = ClientMessage::UploadStart {
            upload_id: "up-1".to_string(),
            event: "uploaded".to_string(),
            target: Some("profile".to_string()),
            name: "avatar.png".to_string(),
            size: 1,
            content_type: None,
        };
        let (operation, event_name, event_target) = security_operation_for_message(&upload_start);
        assert_eq!(operation, SecurityOperation::UploadStart);
        assert_eq!(event_name, Some("uploaded"));
        assert_eq!(event_target, Some("profile"));
        assert_eq!(
            security_operation_for_message(&ClientMessage::PatchUrl {
                to: "/users".to_string()
            })
            .0,
            SecurityOperation::PatchUrl
        );
        assert_eq!(
            security_operation_for_message(&ClientMessage::Navigate {
                to: "/users/1".to_string()
            })
            .0,
            SecurityOperation::Navigate
        );
        assert_eq!(
            security_operation_for_message(&ClientMessage::UploadChunk {
                upload_id: "up-1".to_string(),
                offset: 0,
                data: "AA==".to_string(),
            })
            .0,
            SecurityOperation::UploadChunk
        );
        assert_eq!(
            security_operation_for_message(&ClientMessage::UploadComplete {
                upload_id: "up-1".to_string()
            })
            .0,
            SecurityOperation::UploadComplete
        );
    }

    #[test]
    fn client_message_log_fields_cover_all_client_variants() {
        let connect = client_message_log_fields(&ClientMessage::Connect {
            protocol: "shelly/1".to_string(),
            session_id: Some("sid-1".to_string()),
            last_revision: Some(7),
            resume_token: Some("resume".to_string()),
            tenant_id: None,
            trace_id: None,
            span_id: None,
            parent_span_id: None,
            correlation_id: None,
            request_id: None,
        });
        assert_eq!(connect.message_type, "connect");
        assert_eq!(connect.connect_session_id.as_deref(), Some("sid-1"));
        assert_eq!(connect.connect_last_revision, Some(7));
        assert_eq!(connect.has_resume_token, Some(true));

        let event = client_message_log_fields(&ClientMessage::Event {
            event: "save".to_string(),
            target: Some("profile".to_string()),
            value: serde_json::json!({}),
            metadata: serde_json::Map::new(),
        });
        assert_eq!(event.message_type, "event");
        assert_eq!(event.event_name.as_deref(), Some("save"));
        assert_eq!(event.event_target.as_deref(), Some("profile"));

        let ping = client_message_log_fields(&ClientMessage::Ping { nonce: None });
        assert_eq!(ping.message_type, "ping");

        let patch_url = client_message_log_fields(&ClientMessage::PatchUrl {
            to: "/users".to_string(),
        });
        assert_eq!(patch_url.message_type, "patch_url");
        assert_eq!(patch_url.navigation_to.as_deref(), Some("/users"));

        let navigate = client_message_log_fields(&ClientMessage::Navigate {
            to: "/users/1".to_string(),
        });
        assert_eq!(navigate.message_type, "navigate");
        assert_eq!(navigate.navigation_to.as_deref(), Some("/users/1"));

        let upload_start = client_message_log_fields(&ClientMessage::UploadStart {
            upload_id: "up-1".to_string(),
            event: "uploaded".to_string(),
            target: Some("profile".to_string()),
            name: "avatar.png".to_string(),
            size: 1,
            content_type: None,
        });
        assert_eq!(upload_start.message_type, "upload_start");
        assert_eq!(upload_start.event_target.as_deref(), Some("profile"));
        assert_eq!(upload_start.upload_id.as_deref(), Some("up-1"));
        assert_eq!(upload_start.upload_event.as_deref(), Some("uploaded"));

        let upload_chunk = client_message_log_fields(&ClientMessage::UploadChunk {
            upload_id: "up-1".to_string(),
            offset: 0,
            data: "AA==".to_string(),
        });
        assert_eq!(upload_chunk.message_type, "upload_chunk");
        assert_eq!(upload_chunk.upload_id.as_deref(), Some("up-1"));

        let upload_complete = client_message_log_fields(&ClientMessage::UploadComplete {
            upload_id: "up-1".to_string(),
        });
        assert_eq!(upload_complete.message_type, "upload_complete");
        assert_eq!(upload_complete.upload_id.as_deref(), Some("up-1"));
    }

    #[test]
    fn log_helpers_and_decoders_cover_error_paths() {
        let correlation = test_correlation();
        let message = ClientMessage::Event {
            event: "save".to_string(),
            target: Some("profile".to_string()),
            value: serde_json::json!({}),
            metadata: serde_json::Map::new(),
        };
        log_ws_text_ingress("/users", "sid-1", 32, Ok(&message), &correlation);
        let parse_err = serde_json::from_str::<ClientMessage>("{").expect_err("invalid JSON");
        log_ws_text_ingress("/users", "sid-1", 1, Err(&parse_err), &correlation);

        assert_eq!(
            percent_decode("hello+world").as_deref(),
            Some("hello world")
        );
        assert_eq!(percent_decode("a%2Fb").as_deref(), Some("a/b"));
        assert!(percent_decode("%").is_none());
        assert!(percent_decode("%GG").is_none());
        assert_eq!(from_hex(b'F'), Some(15));
        assert_eq!(from_hex(b'z'), None);
        assert!(parse_query("broken=%GG").is_empty());
    }

    #[test]
    fn outbound_envelope_size_and_telemetry_helpers_are_safe() {
        assert_eq!(
            OutboundEnvelope::Text("abc".to_string()).estimated_bytes(),
            3
        );
        assert_eq!(
            OutboundEnvelope::Pong(vec![1, 2, 3, 4]).estimated_bytes(),
            4
        );
        assert_eq!(
            OutboundEnvelope::Close(Some(OutboundCloseFrame {
                code: 1000,
                reason: "bye".to_string(),
            }))
            .estimated_bytes(),
            5
        );
        assert_eq!(OutboundEnvelope::Close(None).estimated_bytes(), 0);

        let telemetry = Arc::new(TelemetryPipeline::disabled());
        let correlation = test_correlation();
        emit_outbound_batch_telemetry(&telemetry, &correlation, "/users", "sid-1", 3, 120, 2);
        emit_outbound_overflow_telemetry(
            &telemetry,
            &correlation,
            "/users",
            "sid-1",
            OutboundOverflowPolicy::Disconnect,
            64,
        );
        emit_outbound_overflow_telemetry(
            &telemetry,
            &correlation,
            "/users",
            "sid-1",
            OutboundOverflowPolicy::DropNewest,
            64,
        );
    }

    #[test]
    fn security_audit_emitter_handles_optional_context_fields() {
        let telemetry = Arc::new(TelemetryPipeline::disabled());
        let correlation = test_correlation();
        emit_security_audit(
            &telemetry,
            &correlation,
            "/users",
            Some("sid-1"),
            Some("tenant-a"),
            "authorization",
            false,
            Some("forbidden"),
            SecurityOperation::Event,
            "text",
            Some("save"),
            Some("policy-deny"),
        );
        emit_security_audit(
            &telemetry,
            &correlation,
            "/users",
            None,
            None,
            "authorization",
            true,
            None,
            SecurityOperation::Ping,
            "text",
            None,
            None,
        );
    }

    #[test]
    fn outbound_queue_overflow_disconnect_policy_requests_disconnect() {
        let (sender, mut receiver) = mpsc::channel(1);
        let outbound = OutboundConfig {
            queue_capacity: 1,
            overflow_policy: OutboundOverflowPolicy::Disconnect,
            ..OutboundConfig::default()
        };
        let telemetry = Arc::new(TelemetryPipeline::disabled());
        let correlation = test_correlation();

        let first = queue_server_message(
            &sender,
            &ServerMessage::Pong { nonce: None },
            &outbound,
            &telemetry,
            &correlation,
            "/",
            "session-1",
        );
        assert!(matches!(first, super::OutboundQueuePush::Queued));

        let second = queue_server_message(
            &sender,
            &ServerMessage::Pong {
                nonce: Some("2".to_string()),
            },
            &outbound,
            &telemetry,
            &correlation,
            "/",
            "session-1",
        );
        assert!(matches!(second, super::OutboundQueuePush::Disconnect));

        let _ = receiver.try_recv().expect("first outbound message queued");
    }

    #[test]
    fn outbound_queue_overflow_drop_policy_drops_newest() {
        let (sender, mut receiver) = mpsc::channel(1);
        let outbound = OutboundConfig {
            queue_capacity: 1,
            overflow_policy: OutboundOverflowPolicy::DropNewest,
            ..OutboundConfig::default()
        };
        let telemetry = Arc::new(TelemetryPipeline::disabled());
        let correlation = test_correlation();

        let first = queue_server_message(
            &sender,
            &ServerMessage::Pong { nonce: None },
            &outbound,
            &telemetry,
            &correlation,
            "/",
            "session-1",
        );
        assert!(matches!(first, super::OutboundQueuePush::Queued));

        let second = queue_server_message(
            &sender,
            &ServerMessage::Pong {
                nonce: Some("2".to_string()),
            },
            &outbound,
            &telemetry,
            &correlation,
            "/",
            "session-1",
        );
        assert!(matches!(second, super::OutboundQueuePush::Dropped));

        let _ = receiver.try_recv().expect("first outbound message queued");
    }

    #[test]
    fn security_operation_mapping_tracks_event_metadata() {
        let event = ClientMessage::Event {
            event: "save".to_string(),
            target: Some("form".to_string()),
            value: serde_json::Value::Null,
            metadata: serde_json::Map::new(),
        };
        let upload_start = ClientMessage::UploadStart {
            upload_id: "u1".to_string(),
            event: "upload".to_string(),
            target: Some("avatar".to_string()),
            name: "a.png".to_string(),
            size: 10,
            content_type: Some("image/png".to_string()),
        };

        let (event_operation, event_name, event_target) = security_operation_for_message(&event);
        assert_eq!(event_operation, SecurityOperation::Event);
        assert_eq!(event_name, Some("save"));
        assert_eq!(event_target, Some("form"));

        let (upload_operation, upload_event_name, upload_target) =
            security_operation_for_message(&upload_start);
        assert_eq!(upload_operation, SecurityOperation::UploadStart);
        assert_eq!(upload_event_name, Some("upload"));
        assert_eq!(upload_target, Some("avatar"));
    }

    #[test]
    fn authorization_hook_can_reject_sensitive_event_names() {
        let mut security = SecurityConfig {
            signer: TokenSigner::new(b"test secret".to_vec()),
            ..SecurityConfig::default()
        };
        security.authorization = Some(Arc::new(|ctx| {
            if ctx.event_name.as_deref() == Some("admin.delete_user") {
                AuthorizationDecision::deny(
                    "authz_denied",
                    "authorization policy rejected admin.delete_user",
                )
            } else {
                AuthorizationDecision::allow()
            }
        }));

        assert_eq!(
            authorization_denied(
                &security,
                AuthorizationInput {
                    route_path: "/admin",
                    session_id: "session-1",
                    tenant_id: None,
                    message_kind: "text",
                    operation: SecurityOperation::Event,
                    event_name: Some("admin.delete_user"),
                    event_target: Some("delete"),
                },
            ),
            Some(ServerMessage::Error {
                message: "authorization policy rejected admin.delete_user".to_string(),
                code: Some("authz_denied".to_string()),
            })
        );
        assert!(authorization_denied(
            &security,
            AuthorizationInput {
                route_path: "/admin",
                session_id: "session-1",
                tenant_id: None,
                message_kind: "text",
                operation: SecurityOperation::Event,
                event_name: Some("profile.save"),
                event_target: Some("save"),
            },
        )
        .is_none());
    }

    #[test]
    fn quota_policy_can_apply_session_route_and_event_scopes() {
        let mut security = SecurityConfig {
            signer: TokenSigner::new(b"test secret".to_vec()),
            ..SecurityConfig::default()
        };
        security.quota_policy = Some(Arc::new(|ctx| {
            if ctx.session_id == "blocked-session" {
                return QuotaDecision::deny("session_quota_exceeded", "session quota exceeded");
            }
            if ctx.route_path == "/admin" && ctx.event_name.as_deref() == Some("bulk.export") {
                return QuotaDecision::deny("event_quota_exceeded", "event quota exceeded");
            }
            QuotaDecision::allow()
        }));

        assert_eq!(
            quota_denied(
                &security,
                "/feed",
                "blocked-session",
                None,
                "text",
                SecurityOperation::Event,
                Some("scroll"),
            ),
            Some(ServerMessage::Error {
                message: "session quota exceeded".to_string(),
                code: Some("session_quota_exceeded".to_string()),
            })
        );
        assert_eq!(
            quota_denied(
                &security,
                "/admin",
                "session-1",
                None,
                "text",
                SecurityOperation::Event,
                Some("bulk.export"),
            ),
            Some(ServerMessage::Error {
                message: "event quota exceeded".to_string(),
                code: Some("event_quota_exceeded".to_string()),
            })
        );
        assert!(quota_denied(
            &security,
            "/admin",
            "session-1",
            None,
            "text",
            SecurityOperation::Event,
            Some("profile.save"),
        )
        .is_none());
    }

    #[test]
    fn tenant_quota_policy_requires_tenant_context_by_default() {
        let policy = TenantQuotaPolicy::new();
        let decision = policy.evaluate(&super::QuotaContext {
            route_path: "/tenant".to_string(),
            session_id: "session-1".to_string(),
            tenant_id: None,
            message_kind: "text",
            operation: SecurityOperation::Connect,
            event_name: None,
        });
        assert!(!decision.allowed);
        assert_eq!(decision.code.as_deref(), Some("tenant_context_required"));
    }

    #[test]
    fn tenant_quota_policy_enforces_per_tenant_session_and_event_limits() {
        let policy = TenantQuotaPolicy::new()
            .with_window_ms(u64::MAX)
            .with_budgets(TenantQuotaBudgets {
                max_sessions_per_window: 1,
                max_events_per_window: 2,
                require_tenant_id: true,
            });

        let connect_for = |session_id: &str, tenant_id: &str| super::QuotaContext {
            route_path: "/tenant".to_string(),
            session_id: session_id.to_string(),
            tenant_id: Some(tenant_id.to_string()),
            message_kind: "text",
            operation: SecurityOperation::Connect,
            event_name: None,
        };
        let event_for = |session_id: &str, tenant_id: &str, name: &str| super::QuotaContext {
            route_path: "/tenant".to_string(),
            session_id: session_id.to_string(),
            tenant_id: Some(tenant_id.to_string()),
            message_kind: "text",
            operation: SecurityOperation::Event,
            event_name: Some(name.to_string()),
        };

        assert!(
            policy
                .evaluate(&connect_for("session-a1", "tenant-a"))
                .allowed
        );
        let tenant_a_second_session = policy.evaluate(&connect_for("session-a2", "tenant-a"));
        assert!(!tenant_a_second_session.allowed);
        assert_eq!(
            tenant_a_second_session.code.as_deref(),
            Some("tenant_session_quota_exceeded")
        );
        assert!(
            policy
                .evaluate(&connect_for("session-b1", "tenant-b"))
                .allowed,
            "tenant-b must keep an isolated session quota window"
        );

        assert!(
            policy
                .evaluate(&event_for("session-b1", "tenant-b", "save"))
                .allowed
        );
        assert!(
            policy
                .evaluate(&event_for("session-b1", "tenant-b", "save"))
                .allowed
        );
        let tenant_b_third_event = policy.evaluate(&event_for("session-b1", "tenant-b", "save"));
        assert!(!tenant_b_third_event.allowed);
        assert_eq!(
            tenant_b_third_event.code.as_deref(),
            Some("tenant_event_quota_exceeded")
        );
        assert!(
            policy
                .evaluate(&event_for("session-a1", "tenant-a", "save"))
                .allowed,
            "tenant-a event budget must remain independent from tenant-b"
        );
    }

    #[test]
    fn security_audit_event_schema_is_structured_and_correlated() {
        let event = security_audit_event(
            &test_correlation(),
            "/admin",
            Some("session-1"),
            Some("tenant-a"),
            "authorization_policy",
            false,
            Some("authz_denied"),
            SecurityOperation::Event,
            "text",
            Some("admin.delete_user"),
            Some("authorization policy rejected admin.delete_user"),
        );

        assert_eq!(event.kind, TelemetryEventKind::SecurityAudit);
        assert_eq!(event.route_path.as_deref(), Some("/admin"));
        assert_eq!(event.session_id.as_deref(), Some("session-1"));
        assert_eq!(
            event.attributes.get("tenant_id"),
            Some(&serde_json::Value::String("tenant-a".to_string()))
        );
        assert_eq!(event.event_name.as_deref(), Some("admin.delete_user"));
        assert!(!event.ok);
        assert_eq!(
            event.attributes.get("control"),
            Some(&serde_json::Value::String(
                "authorization_policy".to_string()
            ))
        );
        assert_eq!(
            event.attributes.get("operation"),
            Some(&serde_json::Value::String("event".to_string()))
        );
        assert_eq!(
            event.attributes.get("code"),
            Some(&serde_json::Value::String("authz_denied".to_string()))
        );
        assert_eq!(
            event.attributes.get("policy_reason"),
            Some(&serde_json::Value::String(
                "authorization policy rejected admin.delete_user".to_string()
            ))
        );
        assert_eq!(
            event.trace_id.as_deref(),
            Some("0123456789abcdef0123456789abcdef")
        );
    }

    #[tokio::test]
    async fn overload_decision_sheds_background_when_tenant_budget_is_saturated() {
        let mut overload = OverloadConfig::default();
        overload.budgets.session_queue_depth = usize::MAX;
        overload.budgets.session_bytes_per_sec = usize::MAX;
        overload.budgets.session_cpu_ms_per_sec = u64::MAX;
        overload.budgets.tenant_queue_depth = usize::MAX;
        overload.budgets.tenant_bytes_per_sec = 32;
        overload.budgets.tenant_cpu_ms_per_sec = u64::MAX;

        let first = test_overload_context(
            "session-1",
            Some("tenant-a"),
            OverloadPriority::Interactive,
            24,
            1,
            256,
        );
        assert!(
            overload_decision_for_dispatch(&overload, &first)
                .await
                .allowed
        );

        let second = test_overload_context(
            "session-2",
            Some("tenant-a"),
            OverloadPriority::Background,
            24,
            1,
            256,
        );
        let decision = overload_decision_for_dispatch(&overload, &second).await;
        assert!(!decision.allowed);
        assert_eq!(decision.code.as_deref(), Some("overload_shed"));
        assert!(decision
            .reason
            .as_deref()
            .unwrap_or_default()
            .contains("tenant_budget"));
    }

    #[tokio::test]
    async fn overload_decision_throttles_interactive_when_session_budget_is_saturated() {
        let mut overload = OverloadConfig::default();
        overload.budgets.session_queue_depth = usize::MAX;
        overload.budgets.session_bytes_per_sec = 32;
        overload.budgets.session_cpu_ms_per_sec = u64::MAX;
        overload.budgets.tenant_queue_depth = usize::MAX;
        overload.budgets.tenant_bytes_per_sec = usize::MAX;
        overload.budgets.tenant_cpu_ms_per_sec = u64::MAX;

        let first =
            test_overload_context("session-1", None, OverloadPriority::Interactive, 24, 1, 256);
        assert!(
            overload_decision_for_dispatch(&overload, &first)
                .await
                .allowed
        );

        let second =
            test_overload_context("session-1", None, OverloadPriority::Interactive, 24, 1, 256);
        let decision = overload_decision_for_dispatch(&overload, &second).await;
        assert!(decision.allowed);
        assert_eq!(decision.code.as_deref(), Some("overload_throttle"));
        assert_eq!(decision.throttle_ms, 10);
        assert!(decision
            .reason
            .as_deref()
            .unwrap_or_default()
            .contains("session_budget"));
    }

    #[tokio::test]
    async fn overload_policy_hook_can_override_shed_decision() {
        let mut overload = OverloadConfig::default();
        overload.budgets.session_bytes_per_sec = 1;
        overload.policy_hook = Some(Arc::new(|_ctx, _decision| OverloadDecision::allow()));

        let context =
            test_overload_context("session-1", None, OverloadPriority::Background, 8, 1, 128);
        let decision = overload_decision_for_dispatch(&overload, &context).await;
        assert!(decision.allowed);
        assert_eq!(decision.code, None);
        assert_eq!(decision.reason, None);
    }

    #[test]
    fn overload_telemetry_event_has_expected_schema() {
        let context = test_overload_context(
            "session-5",
            Some("tenant-z"),
            OverloadPriority::Background,
            512,
            12,
            16,
        );
        let decision = OverloadDecision::shed("shed:queue_depth+tenant_budget");
        let event = overload_telemetry_event(&test_correlation(), &context, &decision)
            .expect("shed decisions must emit telemetry");
        assert_eq!(event.kind, TelemetryEventKind::Error);
        assert!(!event.ok);
        assert_eq!(event.route_path.as_deref(), Some("/bench"));
        assert_eq!(event.session_id.as_deref(), Some("session-5"));
        assert_eq!(event.event_name.as_deref(), Some("bench.event"));
        assert_eq!(
            event.attributes.get("phase"),
            Some(&serde_json::json!("overload_control"))
        );
        assert_eq!(
            event.attributes.get("action"),
            Some(&serde_json::json!("shed"))
        );
        assert_eq!(
            event.attributes.get("priority"),
            Some(&serde_json::json!("background"))
        );
        assert_eq!(
            event.attributes.get("queue_depth"),
            Some(&serde_json::json!(12))
        );
        assert_eq!(
            event.attributes.get("queue_capacity"),
            Some(&serde_json::json!(16))
        );
        assert_eq!(
            event.attributes.get("inbound_bytes"),
            Some(&serde_json::json!(512))
        );
        assert_eq!(
            event.attributes.get("tenant_id"),
            Some(&serde_json::json!("tenant-z"))
        );
        assert_eq!(
            event.attributes.get("reason"),
            Some(&serde_json::json!("shed:queue_depth+tenant_budget"))
        );
    }

    #[tokio::test(start_paused = true)]
    async fn overload_throttle_respects_configured_delay() {
        let decision = OverloadDecision::throttle(25, "throttle:session_budget");
        let handle = tokio::spawn(async move {
            apply_overload_throttle(&decision).await;
        });

        tokio::task::yield_now().await;
        advance(Duration::from_millis(24)).await;
        tokio::task::yield_now().await;
        assert!(!handle.is_finished());

        advance(Duration::from_millis(1)).await;
        handle.await.expect("throttle task should complete");
    }

    #[tokio::test]
    async fn pubsub_commands_forward_broadcasts_to_socket_channel() {
        let pubsub = PubSub::default();
        let (sender, mut receiver) = mpsc::unbounded_channel();
        let mut tasks: Vec<JoinHandle<()>> = Vec::new();
        let mut subscribed_topics = HashSet::new();
        let correlation = test_correlation();

        process_pubsub_commands(
            vec![PubSubCommand::Subscribe {
                topic: "chat:lobby".to_string(),
            }],
            &pubsub,
            &sender,
            &mut tasks,
            &mut subscribed_topics,
            "session-1",
            "node-test",
            &Arc::new(TelemetryPipeline::disabled()),
            &correlation,
        );
        process_pubsub_commands(
            vec![PubSubCommand::Broadcast {
                topic: "chat:lobby".to_string(),
                messages: vec![ServerMessage::Pong {
                    nonce: Some("n1".to_string()),
                }],
            }],
            &pubsub,
            &sender,
            &mut tasks,
            &mut subscribed_topics,
            "session-1",
            "node-test",
            &Arc::new(TelemetryPipeline::disabled()),
            &correlation,
        );

        tokio::task::yield_now().await;
        let message = receiver.recv().await.unwrap();
        assert_eq!(message.topic, "chat:lobby");
        assert_eq!(
            message.messages,
            vec![ServerMessage::Pong {
                nonce: Some("n1".to_string())
            }]
        );

        for task in tasks {
            task.abort();
        }
    }

    #[tokio::test]
    async fn pubsub_commands_register_presence_for_subscribed_topics() {
        let pubsub = PubSub::default();
        let (sender, _receiver) = mpsc::unbounded_channel();
        let mut tasks: Vec<JoinHandle<()>> = Vec::new();
        let mut subscribed_topics = HashSet::new();
        let correlation = test_correlation();

        process_pubsub_commands(
            vec![PubSubCommand::Subscribe {
                topic: "chat:lobby".to_string(),
            }],
            &pubsub,
            &sender,
            &mut tasks,
            &mut subscribed_topics,
            "session-42",
            "node-alpha",
            &Arc::new(TelemetryPipeline::disabled()),
            &correlation,
        );
        let snapshot = pubsub.presence_snapshot("chat:lobby");
        assert_eq!(snapshot.total_sessions, 1);
        assert_eq!(snapshot.by_node.get("node-alpha"), Some(&1));

        unregister_pubsub_presence(&pubsub, &subscribed_topics, "session-42", "node-alpha");
        let cleared = pubsub.presence_snapshot("chat:lobby");
        assert_eq!(cleared.total_sessions, 0);

        for task in tasks {
            task.abort();
        }
    }

    #[tokio::test(start_paused = true)]
    async fn runtime_commands_dispatch_scheduled_events_to_socket_channel() {
        let (sender, mut receiver) = mpsc::unbounded_channel();
        let mut tasks: HashMap<String, JoinHandle<()>> = HashMap::new();
        process_runtime_commands(
            vec![RuntimeCommand::ScheduleOnce {
                id: "once".to_string(),
                delay_ms: 0,
                dispatch: RuntimeEvent::new("tick", serde_json::json!({"n": 1})),
            }],
            &sender,
            &mut tasks,
        );

        let event =
            recv_runtime_event_with_virtual_time(&mut receiver, Duration::from_millis(1)).await;
        assert_eq!(event.event, "tick");
        assert_eq!(event.value, serde_json::json!({"n": 1}));

        for task in tasks.into_values() {
            task.abort();
        }
    }

    #[tokio::test(start_paused = true)]
    async fn runtime_commands_replace_existing_task_for_same_id() {
        let (sender, mut receiver) = mpsc::unbounded_channel();
        let mut tasks: HashMap<String, JoinHandle<()>> = HashMap::new();

        process_runtime_commands(
            vec![
                RuntimeCommand::ScheduleOnce {
                    id: "tick".to_string(),
                    delay_ms: 100,
                    dispatch: RuntimeEvent::new("tick_first", serde_json::json!({"n": 1})),
                },
                RuntimeCommand::ScheduleOnce {
                    id: "tick".to_string(),
                    delay_ms: 200,
                    dispatch: RuntimeEvent::new("tick_second", serde_json::json!({"n": 2})),
                },
            ],
            &sender,
            &mut tasks,
        );

        assert_eq!(tasks.len(), 1);
        let event =
            recv_runtime_event_with_virtual_time(&mut receiver, Duration::from_millis(250)).await;
        assert_eq!(event.event, "tick_second");
        assert_eq!(event.value, serde_json::json!({"n": 2}));

        for task in tasks.into_values() {
            task.abort();
        }
    }

    #[tokio::test]
    async fn runtime_commands_cancel_active_interval_task() {
        let (sender, _receiver) = mpsc::unbounded_channel();
        let mut tasks: HashMap<String, JoinHandle<()>> = HashMap::new();
        process_runtime_commands(
            vec![RuntimeCommand::ScheduleInterval {
                id: "pulse".to_string(),
                every_ms: 1000,
                dispatch: RuntimeEvent::new("pulse", serde_json::Value::Null),
            }],
            &sender,
            &mut tasks,
        );
        assert!(tasks.contains_key("pulse"));

        process_runtime_commands(
            vec![RuntimeCommand::Cancel {
                id: "pulse".to_string(),
            }],
            &sender,
            &mut tasks,
        );
        assert!(!tasks.contains_key("pulse"));
    }

    #[tokio::test]
    async fn upload_lifecycle_writes_temp_file_and_dispatches_event() {
        #[derive(Default)]
        struct UploadRecorder {
            name: String,
        }

        impl LiveView for UploadRecorder {
            fn handle_event(&mut self, event: Event, _ctx: &mut Context) -> LiveResult {
                if event.name == "uploaded" {
                    self.name = event
                        .value
                        .get("name")
                        .and_then(serde_json::Value::as_str)
                        .unwrap_or_default()
                        .to_string();
                }
                Ok(())
            }

            fn render(&self) -> Html {
                Html::new(format!("<p>{}</p>", self.name))
            }
        }

        let temp_dir = std::env::temp_dir().join(format!("shelly-upload-test-{}", Uuid::new_v4()));
        let config = UploadConfig {
            max_file_size: 16,
            allowed_content_types: Arc::new(vec!["text/plain".to_string()]),
            temp_dir: Arc::new(temp_dir.clone()),
        };
        let mut uploads = HashMap::new();
        let mut session = LiveSession::new(Box::<UploadRecorder>::default(), "root");
        session.mount().unwrap();
        session.render_patch();

        assert_eq!(
            handle_upload_start(
                &mut uploads,
                &config,
                UploadStartRequest {
                    upload_id: "up-1".to_string(),
                    event: "uploaded".to_string(),
                    target: Some("file".to_string()),
                    name: "notes.txt".to_string(),
                    size: 5,
                    content_type: Some("text/plain".to_string()),
                },
            )
            .await,
            vec![ServerMessage::UploadProgress {
                upload_id: "up-1".to_string(),
                received: 0,
                total: 5,
            }]
        );
        assert_eq!(
            handle_upload_chunk(&mut uploads, "up-1", 0, "aGVsbG8=").await,
            vec![ServerMessage::UploadProgress {
                upload_id: "up-1".to_string(),
                received: 5,
                total: 5,
            }]
        );

        let messages = handle_upload_complete(&mut session, &mut uploads, "up-1").await;
        assert!(matches!(
            &messages[0],
            ServerMessage::UploadComplete {
                upload_id,
                name,
                size: 5,
                content_type: Some(content_type),
            } if upload_id == "up-1" && name == "notes.txt" && content_type == "text/plain"
        ));
        assert!(
            matches!(&messages[1], ServerMessage::Patch { html, .. } if html.contains("notes.txt"))
        );

        let stored = tokio::fs::read_to_string(temp_dir.join("up-1.upload"))
            .await
            .unwrap();
        assert_eq!(stored, "hello");
        let _ = tokio::fs::remove_dir_all(temp_dir).await;
    }

    #[tokio::test]
    async fn upload_start_validates_size_and_content_type() {
        let config = UploadConfig {
            max_file_size: 4,
            allowed_content_types: Arc::new(vec!["text/plain".to_string()]),
            temp_dir: Arc::new(PathBuf::from("/tmp/shelly-unused")),
        };
        let mut uploads = HashMap::new();

        assert_eq!(
            handle_upload_start(
                &mut uploads,
                &config,
                UploadStartRequest {
                    upload_id: "up-large".to_string(),
                    event: "uploaded".to_string(),
                    target: None,
                    name: "big.txt".to_string(),
                    size: 5,
                    content_type: Some("text/plain".to_string()),
                },
            )
            .await,
            vec![upload_error(
                "up-large",
                "upload exceeds configured size limit",
                "upload_too_large",
            )]
        );
        assert_eq!(
            handle_upload_start(
                &mut uploads,
                &config,
                UploadStartRequest {
                    upload_id: "up-type".to_string(),
                    event: "uploaded".to_string(),
                    target: None,
                    name: "image.png".to_string(),
                    size: 4,
                    content_type: Some("image/png".to_string()),
                },
            )
            .await,
            vec![upload_error(
                "up-type",
                "upload content type is not allowed",
                "upload_type_not_allowed",
            )]
        );
    }

    #[test]
    fn upload_lifecycle_event_maps_progress_complete_and_error() {
        let session_id = "sid-1";
        let route_path = "/upload";
        let correlation = test_correlation();

        let start = upload_lifecycle_event(
            session_id,
            route_path,
            &ServerMessage::UploadProgress {
                upload_id: "up-1".to_string(),
                received: 0,
                total: 5,
            },
            &correlation,
        )
        .unwrap();
        assert_eq!(start.kind, TelemetryEventKind::UploadLifecycle);
        assert!(start.ok);
        assert_eq!(
            start.attributes.get("phase"),
            Some(&serde_json::Value::String("start".to_string()))
        );

        let complete = upload_lifecycle_event(
            session_id,
            route_path,
            &ServerMessage::UploadComplete {
                upload_id: "up-1".to_string(),
                name: "notes.txt".to_string(),
                size: 5,
                content_type: Some("text/plain".to_string()),
            },
            &correlation,
        )
        .unwrap();
        assert_eq!(complete.kind, TelemetryEventKind::UploadLifecycle);
        assert!(complete.ok);
        assert_eq!(
            complete.attributes.get("phase"),
            Some(&serde_json::Value::String("complete".to_string()))
        );

        let error = upload_lifecycle_event(
            session_id,
            route_path,
            &ServerMessage::UploadError {
                upload_id: "up-1".to_string(),
                message: "upload failed".to_string(),
                code: Some("upload_write_failed".to_string()),
            },
            &correlation,
        )
        .unwrap();
        assert_eq!(error.kind, TelemetryEventKind::UploadLifecycle);
        assert!(!error.ok);
        assert_eq!(
            error.attributes.get("phase"),
            Some(&serde_json::Value::String("error".to_string()))
        );
    }

    #[test]
    fn upload_lifecycle_telemetry_ignores_non_upload_messages() {
        let correlation = test_correlation();
        assert!(upload_lifecycle_event(
            "sid-1",
            "/upload",
            &ServerMessage::Pong { nonce: None },
            &correlation,
        )
        .is_none());

        let telemetry = Arc::new(TelemetryPipeline::disabled());
        emit_upload_lifecycle_telemetry(
            &telemetry,
            "sid-1",
            "/upload",
            &ServerMessage::Pong { nonce: None },
            &correlation,
        );
    }

    #[test]
    fn client_runtime_has_production_reconnect_behavior() {
        assert!(CLIENT_JS.contains("reconnectBaseMs"));
        assert!(CLIENT_JS.contains("reconnectMaxMs"));
        assert!(CLIENT_JS.contains("reconnectJitterMs"));
        assert!(CLIENT_JS.contains("heartbeatIntervalMs"));
        assert!(CLIENT_JS.contains("heartbeatTimeoutMs"));
        assert!(CLIENT_JS.contains("scheduleReconnect("));
        assert!(CLIENT_JS.contains("window.addEventListener(\"online\""));
        assert!(CLIENT_JS.contains("document.addEventListener(\"visibilitychange\""));
        assert!(CLIENT_JS.contains("window.addEventListener(\"beforeunload\""));
        assert!(CLIENT_JS.contains("socket.addEventListener(\"close\""));
        assert!(CLIENT_JS.contains("nextReconnectDelayMs()"));
    }

    #[test]
    fn client_runtime_sends_session_and_csrf_tokens_on_websocket_connect() {
        assert!(CLIENT_JS.contains("new URLSearchParams"));
        assert!(CLIENT_JS.contains("protocol: protocol"));
        assert!(CLIENT_JS.contains("session: cfg.sessionToken"));
        assert!(CLIENT_JS.contains("csrf: cfg.csrfToken"));
        assert!(CLIENT_JS.contains("trace_id: traceId"));
        assert!(CLIENT_JS.contains("parent_span_id: spanId"));
        assert!(CLIENT_JS.contains("correlation_id: correlationId || \"\""));
        assert!(CLIENT_JS.contains("request_id: requestId || \"\""));
        assert!(CLIENT_JS.contains("/__shelly/ws/${wsPath}?${wsQuery}"));
        assert!(CLIENT_JS.contains("type: \"connect\""));
        assert!(CLIENT_JS.contains("session_id: window.__SHELLY.sessionId || null"));
        assert!(CLIENT_JS.contains("last_revision: currentRevision()"));
        assert!(CLIENT_JS.contains("resume_token: window.__SHELLY.resumeToken || null"));
        assert!(CLIENT_JS.contains("trace_id: traceId"));
        assert!(CLIENT_JS.contains("span_id: spanId"));
        assert!(CLIENT_JS.contains("correlation_id: correlationId"));
        assert!(CLIENT_JS.contains("request_id: requestId"));
    }

    #[test]
    fn client_runtime_handles_resume_handshake_metadata() {
        assert!(CLIENT_JS.contains("case \"hello\":"));
        assert!(CLIENT_JS.contains("message.resume_status"));
        assert!(CLIENT_JS.contains("message.resume_reason"));
        assert!(CLIENT_JS.contains("message.server_revision"));
        assert!(CLIENT_JS.contains("window.__SHELLY.resumeToken = message.resume_token"));
        assert!(CLIENT_JS.contains("recordDebug(\"resume_handshake\""));
    }

    #[test]
    fn client_runtime_detects_diff_revision_gaps_and_requests_resync() {
        assert!(CLIENT_JS.contains("diff revision gap detected"));
        assert!(CLIENT_JS.contains("requestResync(\"diff_revision_gap\")"));
        assert!(CLIENT_JS.contains("socket.close(1012, \"resync\")"));
    }

    #[test]
    fn client_runtime_patches_dynamic_slots() {
        assert!(CLIENT_JS.contains("case \"diff\":"));
        assert!(CLIENT_JS.contains("patchDynamicSlots(message.target, message.slots || [])"));
        assert!(CLIENT_JS.contains("data-shelly-slot"));
        assert!(CLIENT_JS.contains("node.innerHTML = slot.html || \"\""));
    }

    #[test]
    fn client_runtime_handles_stream_operations() {
        assert!(CLIENT_JS.contains("case \"stream_insert\":"));
        assert!(CLIENT_JS.contains("case \"stream_delete\":"));
        assert!(CLIENT_JS.contains("case \"stream_batch\":"));
        assert!(CLIENT_JS.contains("streamBatch(message.target, message.operations || [])"));
        assert!(CLIENT_JS.contains("stream.prepend(item)"));
        assert!(CLIENT_JS.contains("stream.append(item)"));
        assert!(CLIENT_JS.contains("item.remove()"));
    }

    #[test]
    fn client_runtime_handles_uploads() {
        assert!(CLIENT_JS.contains("shelly-upload"));
        assert!(CLIENT_JS.contains("type: \"upload_start\""));
        assert!(CLIENT_JS.contains("type: \"upload_chunk\""));
        assert!(CLIENT_JS.contains("type: \"upload_complete\""));
        assert!(CLIENT_JS.contains("case \"upload_progress\":"));
        assert!(CLIENT_JS.contains("shelly:upload-progress"));
    }

    #[test]
    fn client_runtime_has_debug_inspector() {
        assert!(CLIENT_JS.contains("shelly_debug"));
        assert!(CLIENT_JS.contains("shelly-debug-inspector"));
        assert!(CLIENT_JS.contains("shelly-debug-summary"));
        assert!(CLIENT_JS.contains("shelly:debug"));
        assert!(CLIENT_JS.contains("recordDebug(\"client_message\""));
        assert!(CLIENT_JS.contains("recordDebug(\"server_message\""));
        assert!(CLIENT_JS.contains("Session tree"));
        assert!(CLIENT_JS.contains("Transport diagnostics"));
        assert!(CLIENT_JS.contains("Patch stream"));
        assert!(CLIENT_JS.contains("Profiler hotspots"));
        assert!(CLIENT_JS.contains("Event timeline"));
        assert!(CLIENT_JS.contains("trackDebugRuntimeStats(message)"));
    }

    #[test]
    fn client_runtime_updates_clicks_by_patching_without_reload() {
        assert!(CLIENT_JS.contains("document.addEventListener(\"click\""));
        assert!(CLIENT_JS.contains("send(eventPayload(name, element, null))"));
        assert!(CLIENT_JS.contains("case \"patch\":"));
        assert!(CLIENT_JS.contains("root.innerHTML = html"));
        assert!(CLIENT_JS.contains("root.replaceWith(replacement)"));
        assert!(!CLIENT_JS.contains("window.location.reload"));
    }

    #[test]
    fn client_runtime_supports_explicit_component_targets() {
        assert!(CLIENT_JS.contains("shelly-target"));
        assert!(CLIENT_JS.contains("elementFromHtml(html)"));
        assert!(CLIENT_JS.contains("replacement.getAttribute(\"id\") === target"));
    }

    #[test]
    fn client_runtime_sends_submit_payloads_as_json_objects() {
        assert!(CLIENT_JS.contains("document.addEventListener(\"submit\""));
        assert!(CLIENT_JS.contains("event.preventDefault()"));
        assert!(CLIENT_JS.contains("const data = new FormData(form)"));
        assert!(CLIENT_JS.contains("send(eventPayload(name, form, serializeForm(form)))"));
    }

    #[test]
    fn client_runtime_sends_input_and_change_values() {
        assert!(CLIENT_JS.contains("document.addEventListener(\"input\""));
        assert!(CLIENT_JS.contains("nearestActionTarget(event.target, \"shelly-input\")"));
        assert!(CLIENT_JS.contains("document.addEventListener(\"change\""));
        assert!(CLIENT_JS.contains("nearestActionTarget(event.target, \"shelly-change\")"));
        assert!(CLIENT_JS.contains("send(eventPayload(name, element, element.value))"));
    }

    #[test]
    fn client_runtime_supports_headless_accessibility_primitives() {
        assert!(CLIENT_JS.contains("shelly-focus-trap"));
        assert!(CLIENT_JS.contains("focusTrapState"));
        assert!(CLIENT_JS.contains("handleFocusTrapTab(event)"));
        assert!(CLIENT_JS.contains("shelly-dismiss-outside"));
        assert!(CLIENT_JS.contains("handleRovingKeydown(event)"));
        assert!(CLIENT_JS.contains("handleRovingProxyKeydown(event)"));
        assert!(CLIENT_JS.contains("handleTypeahead(event)"));
        assert!(CLIENT_JS.contains("resolveRovingRoot(event.target)"));
        assert!(CLIENT_JS.contains("shelly-keydown"));
        assert!(CLIENT_JS.contains("keyMetadata(event)"));
        assert!(CLIENT_JS.contains("shelly-command-hotkey"));
        assert!(CLIENT_JS.contains("handleCommandHotkey(event)"));
        assert!(CLIENT_JS.contains("shelly-focus"));
    }

    #[test]
    fn client_runtime_supports_native_charting() {
        assert!(CLIENT_JS.contains("shelly-chart-line"));
        assert!(CLIENT_JS.contains("case \"chart_series_append\":"));
        assert!(CLIENT_JS.contains("case \"chart_series_append_many\":"));
        assert!(CLIENT_JS.contains("case \"chart_series_replace\":"));
        assert!(CLIENT_JS.contains("case \"chart_reset\":"));
        assert!(CLIENT_JS.contains("case \"chart_annotation_upsert\":"));
        assert!(CLIENT_JS.contains("case \"chart_annotation_delete\":"));
        assert!(
            CLIENT_JS.contains("chartSeriesAppend(message.chart, message.series, message.point)")
        );
        assert!(CLIENT_JS
            .contains("chartSeriesAppendMany(message.chart, message.series, message.points)"));
        assert!(
            CLIENT_JS.contains("chartSeriesReplace(message.chart, message.series, message.points)")
        );
        assert!(CLIENT_JS.contains("chartReset(message.chart)"));
        assert!(CLIENT_JS.contains("chartAnnotationUpsert(message.chart, message.annotation)"));
        assert!(CLIENT_JS.contains("chartAnnotationDelete(message.chart, message.id)"));
        assert!(CLIENT_JS.contains("data-shelly-chart-series"));
        assert!(CLIENT_JS.contains("data-shelly-chart-annotations"));
        assert!(CLIENT_JS.contains("shelly-chart-hover"));
        assert!(CLIENT_JS.contains("shelly-chart-zoom"));
        assert!(CLIENT_JS.contains("handleChartPointerMove(event)"));
        assert!(CLIENT_JS.contains("handleChartWheel(event)"));
        assert!(CLIENT_JS.contains("handleChartPointerDown(event)"));
        assert!(CLIENT_JS.contains("handleChartPointerUp(event)"));
    }

    #[test]
    fn client_runtime_supports_native_notifications() {
        assert!(CLIENT_JS.contains("case \"toast_push\":"));
        assert!(CLIENT_JS.contains("case \"toast_dismiss\":"));
        assert!(CLIENT_JS.contains("case \"inbox_upsert\":"));
        assert!(CLIENT_JS.contains("case \"inbox_delete\":"));
        assert!(CLIENT_JS.contains("toastPush(message.toast)"));
        assert!(CLIENT_JS.contains("toastDismiss(message.id)"));
        assert!(CLIENT_JS.contains("inboxUpsert(message.item)"));
        assert!(CLIENT_JS.contains("inboxDelete(message.id)"));
        assert!(CLIENT_JS.contains("shelly-notifications-host"));
        assert!(CLIENT_JS.contains("data-shelly-inbox-toggle"));
        assert!(CLIENT_JS.contains("data-shelly-toast-region"));
    }

    #[test]
    fn client_runtime_supports_native_dragdrop_primitives() {
        assert!(CLIENT_JS.contains("data-shelly-sortable"));
        assert!(CLIENT_JS.contains("data-shelly-sort-item"));
        assert!(CLIENT_JS.contains("data-shelly-sort-keyboard"));
        assert!(CLIENT_JS.contains("shelly_drag_start"));
        assert!(CLIENT_JS.contains("shelly_drag_over"));
        assert!(CLIENT_JS.contains("shelly_sort"));
        assert!(CLIENT_JS.contains("handleSortableKeyboard(event)"));
        assert!(CLIENT_JS.contains("handleSortableDragStart(event)"));
        assert!(CLIENT_JS.contains("handleSortableDragOver(event)"));
        assert!(CLIENT_JS.contains("handleSortableDrop(event)"));
        assert!(CLIENT_JS.contains("\"dragstart\","));
        assert!(CLIENT_JS.contains("\"dragover\","));
        assert!(CLIENT_JS.contains("\"drop\","));
        assert!(CLIENT_JS.contains("\"dragend\","));
    }

    #[test]
    fn client_runtime_supports_native_markdown_editor_primitives() {
        assert!(CLIENT_JS.contains("shelly-editor-input"));
        assert!(CLIENT_JS.contains("shelly-editor-select"));
        assert!(CLIENT_JS.contains("shelly-editor-command"));
        assert!(CLIENT_JS.contains("shelly-editor-command-event"));
        assert!(CLIENT_JS.contains("handleEditorCommandClick(event.target)"));
        assert!(CLIENT_JS.contains("editorSelectionState"));
        assert!(CLIENT_JS.contains("editorSnapshot(element)"));
        assert!(CLIENT_JS.contains("resolveEditorTarget(actionElement)"));
        assert!(CLIENT_JS.contains("\"selectionchange\""));
    }

    #[test]
    fn client_runtime_supports_nested_form_serialization() {
        assert!(CLIENT_JS.contains("parseFieldPath(key)"));
        assert!(CLIENT_JS.contains("setNestedValue(out, path, value)"));
        assert!(CLIENT_JS.contains("isNumericPathToken(token)"));
        assert!(CLIENT_JS.contains("serializeForm(form)"));
    }

    #[test]
    fn client_runtime_supports_js_interop_dispatch_and_bindings() {
        assert!(CLIENT_JS.contains("case \"interop_dispatch\":"));
        assert!(CLIENT_JS.contains("interopDispatch(message.dispatch)"));
        assert!(CLIENT_JS.contains("function interopDispatch(dispatch)"));
        assert!(CLIENT_JS.contains("shelly:interop-dispatch"));
        assert!(CLIENT_JS.contains("[shelly-js-interop]"));
        assert!(CLIENT_JS.contains("function ensureJsInteropBindings(root)"));
        assert!(CLIENT_JS.contains("shelly-js-push"));
        assert!(CLIENT_JS.contains("\"js_interop\""));
    }

    #[test]
    fn client_runtime_supports_webrtc_signal_compatibility() {
        assert!(CLIENT_JS.contains("dispatch.event"));
        assert!(CLIENT_JS.contains("new CustomEvent(eventName"));
        assert!(CLIENT_JS.contains("detail: detail"));
        assert!(CLIENT_JS.contains("dispatch.bubbles !== false"));
        assert!(CLIENT_JS.contains("composed: true"));
    }

    #[test]
    fn client_runtime_supports_enterprise_grid_primitives() {
        assert!(CLIENT_JS.contains("case \"grid_replace\":"));
        assert!(CLIENT_JS.contains("case \"grid_rows_replace\":"));
        assert!(CLIENT_JS.contains("gridReplace(message.grid, message.state)"));
        assert!(CLIENT_JS.contains("gridRowsReplace(message.grid, message.window)"));
        assert!(CLIENT_JS.contains("function renderGrid(root)"));
        assert!(CLIENT_JS.contains("data-shelly-grid-viewport"));
        assert!(CLIENT_JS.contains("data-shelly-grid-resize"));
        assert!(CLIENT_JS.contains("handleGridResizePointerDown(event)"));
        assert!(CLIENT_JS.contains("handleGridResizePointerMove(event)"));
        assert!(CLIENT_JS.contains("handleGridResizePointerUp(event)"));
        assert!(CLIENT_JS.contains("handleGridKeydown(event)"));
        assert!(CLIENT_JS.contains("shelly-grid-edit"));
        assert!(CLIENT_JS.contains("shelly-grid-filter"));
        assert!(CLIENT_JS.contains("window_start"));
        assert!(CLIENT_JS.contains("window_end"));
        assert!(CLIENT_JS.contains("shelly:grid-csv-download"));
        assert!(CLIENT_JS.contains("downloadGridCsv(event.detail)"));
    }
}