Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

515 KB
Raw Blame
use base64::Engine;
use dbx_driver_support::db::{connection_timeout, json_value_for_js, safe_i64_to_json, CONNECTION_TIMEOUT_SECS};
use dbx_types::models::connection::{ConnectionConfig, DatabaseConnectionInfo};
use redis::{
    aio::ConnectionLike, cluster::ClusterClient, cluster_async::ClusterConnection, Cmd, ConnectionAddr, ConnectionInfo,
    FromRedisValue, IntoConnectionInfo, Pipeline, ProtocolVersion, RedisConnectionInfo, RedisFuture,
    Value as RedisRawValue,
};
use serde::{Deserialize, Serialize};
use std::{
    collections::{HashMap, HashSet},
    fs,
    future::Future,
    sync::{Arc, OnceLock},
    time::Duration,
    time::Instant,
};
use tokio::sync::{Mutex, MutexGuard};

const STREAM_ENTRY_PAGE_SIZE: usize = 50;
const STREAM_PENDING_PAGE_SIZE: usize = 100;
const COLLECTION_PAGE_SIZE: usize = 200;
pub const STRING_PREVIEW_MAX_BYTES: usize = 64 * 1024;
pub const VALUE_PREVIEW_MAX_BYTES: usize = 64 * 1024 * 1024;

pub fn validate_value_preview_limit(limit: usize) -> Result<(), String> {
    if !(1024..=VALUE_PREVIEW_MAX_BYTES).contains(&limit) {
        return Err("Redis value preview limit must be between 1024 and 67108864 bytes".to_string());
    }
    Ok(())
}
/// A collection page is capped by payload size as well as item count.
///
/// `COLLECTION_PAGE_SIZE` alone bounds a page only when the members are small. A hash, list, set
/// or sorted set whose members are serialized blobs turns 200 members into hundreds of megabytes,
/// which then has to cross the IPC boundary and be parsed and rendered, so opening the key looks
/// like it does nothing. Strings already avoid this through `STRING_PREVIEW_MAX_BYTES`; this is
/// the same guard for collections, except that no member is ever truncated — the page simply ends
/// early and the remainder is fetched by the existing "load more" cursor.
const COLLECTION_PAGE_MAX_BYTES: usize = 4 * 1024 * 1024;
const COLLECTION_FILTER_SCAN_MAX_ITERATIONS: usize = 10;
const DEFAULT_REDIS_DATABASES: u32 = 16;
const MAX_CLUSTER_DATABASE_LIST_ENTRIES: u32 = 10_000;
const JS_MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
const CLUSTER_CURSOR_NODE_BITS: u64 = 16;
const CLUSTER_CURSOR_NODE_MASK: u64 = (1 << CLUSTER_CURSOR_NODE_BITS) - 1;
const CLUSTER_CURSOR_SCAN_MASK: u64 = (1 << (64 - CLUSTER_CURSOR_NODE_BITS)) - 1;
const CLUSTER_SCAN_SESSION_LIMIT: usize = 128;
const CLUSTER_SCAN_SESSION_TTL: Duration = Duration::from_secs(5 * 60);
const COLLECTION_OVERFLOW_SESSION_LIMIT: usize = 128;
const COLLECTION_OVERFLOW_SESSION_TTL: Duration = Duration::from_secs(5 * 60);
const COLLECTION_OVERFLOW_CURSOR_START: u64 = 1 << 52;
const INVALID_CLUSTER_SCAN_CURSOR_ERROR: &str = "Redis cluster scan cursor is invalid or expired";
const MAX_SAFE_INTEGER_CURSOR: u64 = (1 << 53) - 1;
/// Keys per packed round trip when a batch also asks for TYPE and TTL.
///
/// The scan itself may return tens of thousands of keys in one batch, but the
/// metadata pipeline is split into chunks of this size: each chunk is one
/// round trip that carries at most `2 * SCAN_METADATA_PIPELINE_CHUNK`
/// commands (one TYPE and one TTL per key, interleaved), which keeps the
/// single-threaded server responsive for the other clients of the instance.
const SCAN_METADATA_PIPELINE_CHUNK: usize = 1000;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RedisDatabaseInfo {
    pub db: u32,
    /// 该库的键数量。`None` 表示服务端无法给出可信数量:kvrocks 的 DBSIZE / INFO keyspace
    /// 键数是异步统计的(要先执行 `DBSIZE SCAN`),未统计前一律返回 0,这里不把 0 当作事实。
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub keys: Option<u64>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RedisKeyInfo {
    pub key_display: String,
    pub key_raw: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub key_type: String,
    #[serde(default = "default_missing_ttl", skip_serializing_if = "is_missing_ttl")]
    pub ttl: i64,
    #[serde(default, skip_serializing_if = "is_zero_u64")]
    pub size: u64,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub value_preview: String,
}

fn default_missing_ttl() -> i64 {
    -2
}

fn is_missing_ttl(ttl: &i64) -> bool {
    *ttl == -2
}

fn is_zero_u64(value: &u64) -> bool {
    *value == 0
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RedisScanResult {
    pub cursor: u64,
    pub keys: Vec<RedisKeyInfo>,
    pub total_keys: u64,
}

/// Per-key metadata (type + TTL) resolved for an explicit list of keys.
///
/// The "fetch all" path scans key names without TYPE/TTL so a million-key
/// database is not hit with two extra commands per key. When the UI needs
/// those badges afterwards it asks for exactly the keys it shows, so the cost
/// stays proportional to the visible rows instead of the keyspace.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RedisKeyMetadata {
    pub key_raw: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub key_type: String,
    pub ttl: i64,
}

/// The expiration shapes the Key Browser may apply to a batch of selected keys.
///
/// The variants mirror [`set_ttl`] and [`set_expire_at`] exactly, so a batch edit
/// and a single-key edit send the same Redis command for the same user choice.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RedisKeysExpiry {
    Persist,
    Ttl(i64),
    At(i64),
}

impl RedisKeysExpiry {
    /// Keeps the single-key convention where a non-positive TTL means PERSIST.
    pub fn from_ttl(ttl: i64) -> Self {
        if ttl > 0 {
            Self::Ttl(ttl)
        } else {
            Self::Persist
        }
    }

    fn command(self) -> &'static str {
        match self {
            Self::Persist => "PERSIST",
            Self::Ttl(_) => "EXPIRE",
            Self::At(_) => "EXPIREAT",
        }
    }
}

/// Per-key outcome of a batch expiration so a partial failure stays reportable.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisKeysExpiryResult {
    /// Keys the server confirmed as updated.
    pub applied: u64,
    /// Selected keys that no longer exist, so the caller can offer a retry.
    pub missing_key_raws: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RedisValue {
    pub key_display: String,
    pub key_raw: String,
    pub ttl: i64,
    pub redis_type: String,
    pub data: RedisValueData,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RedisBlobEncoding {
    Utf8,
    Binary,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisBlob {
    pub raw_base64: String,
    pub encoding: RedisBlobEncoding,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisListItem {
    pub index: u64,
    pub value: RedisBlob,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisSetItem {
    pub member: RedisBlob,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisHashItem {
    pub field: RedisBlob,
    pub value: RedisBlob,
    /// Remaining field TTL in seconds. `-1` means the field is persistent;
    /// `None` means the Redis server does not expose hash-field expiration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub field_ttl: Option<i64>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisZsetItem {
    pub score: String,
    pub member: RedisBlob,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisStreamField {
    pub field: String,
    pub value: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisStreamEntry {
    pub id: String,
    pub fields: Vec<RedisStreamField>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisStreamPage {
    pub entries: Vec<RedisStreamEntry>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisStreamGroup {
    pub name: RedisBlob,
    #[serde(serialize_with = "serialize_redis_u64_for_js")]
    pub consumers: u64,
    #[serde(serialize_with = "serialize_redis_u64_for_js")]
    pub pending: u64,
    pub last_delivered_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none", serialize_with = "serialize_optional_redis_u64_for_js")]
    pub entries_read: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none", serialize_with = "serialize_optional_redis_u64_for_js")]
    pub lag: Option<u64>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisStreamConsumer {
    pub name: RedisBlob,
    #[serde(serialize_with = "serialize_redis_u64_for_js")]
    pub pending: u64,
    #[serde(serialize_with = "serialize_redis_u64_for_js")]
    pub idle_ms: u64,
    #[serde(default, skip_serializing_if = "Option::is_none", serialize_with = "serialize_optional_redis_u64_for_js")]
    pub inactive_ms: Option<u64>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisStreamPendingEntry {
    pub id: String,
    pub consumer: RedisBlob,
    #[serde(serialize_with = "serialize_redis_u64_for_js")]
    pub idle_ms: u64,
    #[serde(serialize_with = "serialize_redis_u64_for_js")]
    pub deliveries: u64,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RedisStreamPendingPage {
    pub entries: Vec<RedisStreamPendingEntry>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub next_cursor: Option<String>,
}

// JSON and Tauri IPC both deliver numbers to JavaScript, so preserve large Redis counters as text.
fn serialize_redis_u64_for_js<S>(value: &u64, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    if *value > JS_MAX_SAFE_INTEGER {
        serializer.serialize_str(&value.to_string())
    } else {
        serializer.serialize_u64(*value)
    }
}

fn serialize_optional_redis_u64_for_js<S>(value: &Option<u64>, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    match value {
        Some(value) => serialize_redis_u64_for_js(value, serializer),
        None => serializer.serialize_none(),
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum RedisValueData {
    String {
        content: RedisBlob,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        total_bytes: Option<u64>,
        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
        truncated: bool,
    },
    Json {
        /// Original JSON.GET payload used throughout the RedisJSON UI.
        value: String,
    },
    List {
        items: Vec<RedisListItem>,
        total: u64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
    Set {
        items: Vec<RedisSetItem>,
        total: u64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
    Hash {
        items: Vec<RedisHashItem>,
        total: u64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
    Zset {
        items: Vec<RedisZsetItem>,
        total: u64,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
    Stream {
        entries: Vec<RedisStreamEntry>,
        #[serde(
            default,
            skip_serializing_if = "Option::is_none",
            serialize_with = "serialize_optional_redis_u64_for_js"
        )]
        total: Option<u64>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        next_cursor: Option<String>,
    },
    /// kvrocks 把位图实现成独立类型(`TYPE` 返回 `bitmap`),而 Redis 里 SETBIT 写入的
    /// 就是普通字符串,所以这个分支只会在 kvrocks 一类兼容服务上出现。kvrocks 上
    /// `GETRANGE`/`STRLEN` 对该类型会报 WRONGTYPE,只有 `GET` 能读到与 Redis 位序一致的
    /// 原始字节,因此这里用 GET 取内容、用 BITCOUNT 取置位数量。
    Bitmap {
        content: RedisBlob,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        total_bytes: Option<u64>,
        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
        truncated: bool,
        /// `BITCOUNT` 得到的置位数量;命令不可用时为 None。
        #[serde(default, skip_serializing_if = "Option::is_none")]
        set_bits: Option<u64>,
    },
    /// kvrocks 的 HyperLogLog 独立类型(`TYPE` 返回 `hyperloglog`):原始字节不可读,
    /// 只能通过 `PFCOUNT` 展示基数估计。
    #[serde(rename = "hyperloglog")]
    HyperLogLog {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        count: Option<u64>,
    },
    /// 服务端返回了 DBX 尚未支持的类型(如 kvrocks 的 `timeseries`/`TDIS-TYPE`)。
    /// 带上原始类型名,前端据此给出明确提示,而不是渲染成空值。
    Unknown { redis_type: String },
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum RedisCollectionPage {
    List {
        items: Vec<RedisListItem>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
    Set {
        items: Vec<RedisSetItem>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
    Hash {
        items: Vec<RedisHashItem>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
    Zset {
        items: Vec<RedisZsetItem>,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        scan_cursor: Option<u64>,
    },
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RedisCommandSafety {
    Allowed,
    Write,
    Confirm,
    Blocked,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RedisCommandResult {
    pub command: String,
    pub safety: RedisCommandSafety,
    pub value: serde_json::Value,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PubSubMessage {
    pub channel: String,
    pub pattern: Option<String>,
    pub payload: String,
}

pub enum RedisConnection {
    Direct(Mutex<redis::aio::MultiplexedConnection>),
    Cluster(RedisClusterPool),
}

#[cfg(any(test, feature = "test-support"))]
pub fn redis_connection_test_stub() -> RedisConnection {
    RedisConnection::Cluster(RedisClusterPool {
        connection: None,
        database_connections: Box::new(tokio::sync::Mutex::new(HashMap::new())),
        database_capability: Box::new(tokio::sync::Mutex::new(None)),
        seed_nodes: Vec::new(),
        seed_routes: Vec::new(),
        slot_ranges: Vec::new(),
        node_routes: Vec::new(),
        tls: false,
        tls_insecure: false,
        tls_certificates: None,
        username: String::new(),
        password: String::new(),
        scan_sessions: Box::new(Mutex::new(RedisClusterScanSessions::default())),
    })
}

type RedisClusterDatabaseConnections = HashMap<u32, Arc<Mutex<Option<ClusterConnection>>>>;

pub struct RedisClusterPool {
    pub connection: Option<Mutex<ClusterConnection>>,
    database_connections: Box<Mutex<RedisClusterDatabaseConnections>>,
    database_capability: Box<Mutex<Option<ClusterDatabaseCapability>>>,
    pub seed_nodes: Vec<RedisNodeEndpoint>,
    pub seed_routes: Vec<RedisNodeRoute>,
    pub slot_ranges: Vec<RedisClusterSlotRange>,
    pub node_routes: Vec<RedisNodeRoute>,
    pub tls: bool,
    pub tls_insecure: bool,
    pub tls_certificates: Option<Box<redis::TlsCertificates>>,
    pub username: String,
    pub password: String,
    scan_sessions: Box<Mutex<RedisClusterScanSessions>>,
}

#[derive(Debug, Clone)]
struct RedisClusterKeyScanSession {
    db: u32,
    value_filter: Option<(String, bool)>,
    total_keys: u64,
    master_nodes: Vec<RedisNodeEndpoint>,
    node_cursors: Vec<u64>,
    node_complete: Vec<bool>,
    next_node_index: usize,
    pattern: String,
    last_used: Instant,
}

impl RedisClusterKeyScanSession {
    fn new(master_nodes: Vec<RedisNodeEndpoint>, pattern: &str) -> Self {
        let node_count = master_nodes.len();
        Self {
            db: 0,
            value_filter: None,
            total_keys: 0,
            master_nodes,
            node_cursors: vec![0; node_count],
            node_complete: vec![false; node_count],
            next_node_index: 0,
            pattern: pattern.to_string(),
            last_used: Instant::now(),
        }
    }

    fn next_unfinished_node_index(&self) -> Option<usize> {
        let node_count = self.master_nodes.len();
        (0..node_count)
            .map(|offset| (self.next_node_index + offset) % node_count)
            .find(|index| !self.node_complete[*index])
    }

    fn advance_after(&mut self, node_index: usize) {
        self.next_node_index = (node_index + 1) % self.master_nodes.len();
    }

    fn is_complete(&self) -> bool {
        self.node_complete.iter().all(|complete| *complete)
    }
}

#[derive(Debug, Default)]
struct RedisClusterScanSessions {
    entries: HashMap<u64, RedisClusterKeyScanSession>,
}

impl RedisClusterScanSessions {
    fn take(&mut self, cursor: u64) -> Option<RedisClusterKeyScanSession> {
        self.remove_expired();
        self.entries.remove(&cursor)
    }

    fn insert(&mut self, cursor: Option<u64>, mut session: RedisClusterKeyScanSession) -> u64 {
        self.remove_expired();
        while self.entries.len() >= CLUSTER_SCAN_SESSION_LIMIT {
            let Some(oldest) = self.entries.iter().min_by_key(|(_, entry)| entry.last_used).map(|(id, _)| *id) else {
                break;
            };
            self.entries.remove(&oldest);
        }

        let cursor = cursor.filter(|value| *value > 0).unwrap_or_else(|| self.next_available_cursor());
        session.last_used = Instant::now();
        self.entries.insert(cursor, session);
        cursor
    }

    fn remove_expired(&mut self) {
        self.entries.retain(|_, entry| entry.last_used.elapsed() < CLUSTER_SCAN_SESSION_TTL);
    }

    fn next_available_cursor(&mut self) -> u64 {
        // Pool-local counters could accept a token from another connection when
        // both pools happen to allocate the same cursor. Allocate process-wide.
        static NEXT_CURSOR: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
        loop {
            let cursor = NEXT_CURSOR.fetch_add(1, std::sync::atomic::Ordering::Relaxed) % MAX_SAFE_INTEGER_CURSOR + 1;
            if cursor != 0 && !self.entries.contains_key(&cursor) {
                return cursor;
            }
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum RedisCollectionOverflowKind {
    Hash,
    Set,
}

#[derive(Debug, Clone)]
enum RedisCollectionOverflowItems {
    Hash(Vec<RedisHashItem>),
    Set(Vec<RedisSetItem>),
}

#[derive(Debug, Clone)]
struct RedisCollectionOverflowSession {
    scope: RedisOperationScope,
    key: Vec<u8>,
    kind: RedisCollectionOverflowKind,
    filter: Option<String>,
    sort_direction: Option<String>,
    followup_cursor: u64,
    items: RedisCollectionOverflowItems,
    last_used: Instant,
}

#[derive(Debug)]
struct RedisCollectionOverflowSessions {
    next_cursor: u64,
    entries: HashMap<u64, RedisCollectionOverflowSession>,
}

impl Default for RedisCollectionOverflowSessions {
    fn default() -> Self {
        Self { next_cursor: COLLECTION_OVERFLOW_CURSOR_START, entries: HashMap::new() }
    }
}

impl RedisCollectionOverflowSessions {
    fn take_matching(
        &mut self,
        cursor: u64,
        scope: &RedisOperationScope,
        key: &[u8],
        kind: RedisCollectionOverflowKind,
        filter: Option<&str>,
        sort_direction: Option<&str>,
    ) -> Option<RedisCollectionOverflowSession> {
        self.remove_expired();
        let matches = self.entries.get(&cursor).is_some_and(|session| {
            session.scope == *scope
                && session.key == key
                && session.kind == kind
                && session.filter.as_deref() == filter
                && session.sort_direction.as_deref() == sort_direction
        });
        matches.then(|| self.entries.remove(&cursor)).flatten()
    }

    fn insert(&mut self, mut session: RedisCollectionOverflowSession) -> u64 {
        self.remove_expired();
        while self.entries.len() >= COLLECTION_OVERFLOW_SESSION_LIMIT {
            let Some(oldest) = self.entries.iter().min_by_key(|(_, entry)| entry.last_used).map(|(id, _)| *id) else {
                break;
            };
            self.entries.remove(&oldest);
        }

        let cursor = self.next_available_cursor();
        session.last_used = Instant::now();
        self.entries.insert(cursor, session);
        cursor
    }

    fn reinsert(&mut self, cursor: u64, mut session: RedisCollectionOverflowSession) {
        self.remove_expired();
        while self.entries.len() >= COLLECTION_OVERFLOW_SESSION_LIMIT && !self.entries.contains_key(&cursor) {
            let Some(oldest) = self.entries.iter().min_by_key(|(_, entry)| entry.last_used).map(|(id, _)| *id) else {
                break;
            };
            self.entries.remove(&oldest);
        }
        session.last_used = Instant::now();
        self.entries.insert(cursor, session);
    }

    fn remove_expired(&mut self) {
        self.entries.retain(|_, entry| entry.last_used.elapsed() < COLLECTION_OVERFLOW_SESSION_TTL);
    }

    fn next_available_cursor(&mut self) -> u64 {
        loop {
            let cursor = self.next_cursor;
            self.next_cursor =
                if cursor >= MAX_SAFE_INTEGER_CURSOR { COLLECTION_OVERFLOW_CURSOR_START } else { cursor + 1 };
            if cursor != 0 && !self.entries.contains_key(&cursor) {
                return cursor;
            }
        }
    }
}

/// Stable request identity, independent of mutable SELECT state on a connection.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct RedisOperationScope {
    pub connection_id: String,
    pub db: u32,
}

fn collection_overflow_sessions() -> &'static Mutex<RedisCollectionOverflowSessions> {
    static SESSIONS: OnceLock<Mutex<RedisCollectionOverflowSessions>> = OnceLock::new();
    SESSIONS.get_or_init(|| Mutex::new(RedisCollectionOverflowSessions::default()))
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RedisClusterAuth {
    pub username: String,
    pub password: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RedisSlowlogEntry {
    pub id: u64,
    pub timestamp: i64,
    pub duration_micros: u64,
    pub command: String,
    pub client_addr: Option<String>,
    pub client_name: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RedisNodeRoute {
    pub advertised: RedisNodeEndpoint,
    pub connect: RedisNodeEndpoint,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RedisClusterSlotRange {
    pub start: u16,
    pub end: u16,
    pub master: RedisNodeEndpoint,
}

pub enum RedisClusterConnectionGuard<'a> {
    Native(MutexGuard<'a, ClusterConnection>),
    Database(ClusterConnection),
    Direct(redis::aio::MultiplexedConnection),
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct RedisAuthCandidate {
    username: String,
    password: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct RedisNodeEndpoint {
    pub host: String,
    pub port: u16,
}

impl ConnectionLike for RedisClusterConnectionGuard<'_> {
    fn req_packed_command<'a>(&'a mut self, cmd: &'a Cmd) -> RedisFuture<'a, RedisRawValue> {
        match self {
            RedisClusterConnectionGuard::Native(con) => con.req_packed_command(cmd),
            RedisClusterConnectionGuard::Database(con) => con.req_packed_command(cmd),
            RedisClusterConnectionGuard::Direct(con) => con.req_packed_command(cmd),
        }
    }

    fn req_packed_commands<'a>(
        &'a mut self,
        cmd: &'a Pipeline,
        offset: usize,
        count: usize,
    ) -> RedisFuture<'a, Vec<RedisRawValue>> {
        match self {
            RedisClusterConnectionGuard::Native(con) => con.req_packed_commands(cmd, offset, count),
            RedisClusterConnectionGuard::Database(con) => con.req_packed_commands(cmd, offset, count),
            RedisClusterConnectionGuard::Direct(con) => con.req_packed_commands(cmd, offset, count),
        }
    }

    fn get_db(&self) -> i64 {
        match self {
            RedisClusterConnectionGuard::Native(con) => con.get_db(),
            RedisClusterConnectionGuard::Database(con) => con.get_db(),
            RedisClusterConnectionGuard::Direct(con) => con.get_db(),
        }
    }
}

pub async fn connect(url: &str, timeout: std::time::Duration) -> Result<redis::aio::MultiplexedConnection, String> {
    let client = redis::Client::open(url).map_err(|e| format!("Redis connection failed: {e}"))?;
    connect_client_with_timeout(client, timeout, "Redis").await
}

pub async fn connect_standalone(
    config: &ConnectionConfig,
    host: &str,
    port: u16,
    timeout: std::time::Duration,
) -> Result<redis::aio::MultiplexedConnection, String> {
    let certificates = load_redis_tls_certificates(config)?;
    let mut last_error = None;
    for info in standalone_connection_infos(config, host, port)? {
        let client = build_redis_client(info, certificates.as_ref())?;
        match connect_client_with_timeout(client, timeout, "Redis").await {
            Ok(con) => return Ok(con),
            Err(err) if last_error.is_none() || is_redis_auth_error(&err) => {
                let should_retry = is_redis_auth_error(&err);
                last_error = Some(err);
                if !should_retry {
                    break;
                }
            }
            Err(err) => return Err(err),
        }
    }
    Err(last_error.unwrap_or_else(|| "Redis connection failed".to_string()))
}

fn standalone_connection_infos(
    config: &ConnectionConfig,
    host: &str,
    port: u16,
) -> Result<Vec<ConnectionInfo>, String> {
    redis_auth_candidates(&config.username, &config.password)
        .into_iter()
        .map(|auth| {
            connection_info(
                host,
                port,
                config.ssl,
                config.redis_tls_insecure(),
                &auth.username,
                &auth.password,
                redis_database_index(config),
            )
        })
        .collect()
}

async fn connect_client_with_timeout(
    client: redis::Client,
    timeout: std::time::Duration,
    label: &str,
) -> Result<redis::aio::MultiplexedConnection, String> {
    let options = redis_async_connection_config();
    // Type-erase the transport future here: otherwise downstream core operations
    // expand the entire redis-rs TCP/TLS future when proving Send, exceeding the
    // default recursion limit of their integration-test crates. This is not a
    // spawned task; dropping the caller still cancels connection establishment.
    let connect: RedisFuture<'_, redis::aio::MultiplexedConnection> =
        Box::pin(client.get_multiplexed_async_connection_with_config(&options));
    let mut con = tokio::time::timeout(timeout, connect)
        .await
        .map_err(|_| format!("{label} connection timed out ({}s)", timeout.as_secs()))?
        .map_err(|e| format!("{label} connection failed: {e}"))?;

    // Credentials are applied while the connection is being established, so reaching this point
    // already proves AUTH succeeded. The PING below is only a liveness probe: an account that may
    // not run PING (for example a managed Redis behind a restrictive ACL) is still a usable
    // connection, so a denied PING must not fail it (issue #9394).
    redis_ping(&mut con, label, timeout).await?;

    Ok(con)
}

pub async fn connect_sentinel(config: &ConnectionConfig) -> Result<redis::aio::MultiplexedConnection, String> {
    connect_sentinel_with_timeout(config, connection_timeout()).await
}

async fn connect_sentinel_with_timeout(
    config: &ConnectionConfig,
    lookup_timeout: Duration,
) -> Result<redis::aio::MultiplexedConnection, String> {
    let service_name = config.redis_sentinel_master.trim();
    if service_name.is_empty() {
        return Err("Redis Sentinel master name is required".to_string());
    }

    let nodes = redis_sentinel_nodes(config)?;
    let client = tokio::time::timeout(lookup_timeout, sentinel_master_client(config, &nodes, service_name))
        .await
        .map_err(|_| format!("Redis Sentinel lookup timed out ({}s)", lookup_timeout.as_secs()))?
        .map_err(|e| format!("Redis Sentinel master lookup failed: {e}"))?;

    connect_client(client).await
}

// redis-rs 1.x does not expose timeout configuration for Sentinel's private
// discovery/ROLE connections. Keep the 0.32 discovery contract here so the
// existing outer DBX lookup deadline, not new 500-ms/1-second defaults, applies.
// This is one-shot discovery, not a failover manager.
async fn sentinel_master_client(
    config: &ConnectionConfig,
    nodes: &[ConnectionInfo],
    service_name: &str,
) -> Result<redis::Client, String> {
    let certificates = load_redis_tls_certificates(config)?;
    let masters = sentinel_masters(nodes, certificates.as_ref()).await.map_err(|error| error.to_string())?;
    for master in masters {
        let Some(endpoint) = sentinel_eligible_master(&master, service_name) else { continue };
        let client = build_redis_client(
            connection_info(
                &endpoint.host,
                endpoint.port,
                config.ssl,
                config.redis_tls_insecure(),
                &config.username,
                &config.password,
                0,
            )?,
            certificates.as_ref(),
        )
        .map_err(|error| error.to_string())?;
        let mut con = client
            .get_multiplexed_async_connection_with_config(&redis_async_connection_config())
            .await
            .map_err(|error| error.to_string())?;
        if sentinel_is_master(&mut con).await.map_err(|error| error.to_string())? {
            return Ok(client);
        }
    }
    Err(format!("Master '{service_name}' not found among healthy Sentinel masters"))
}

async fn sentinel_masters(
    nodes: &[ConnectionInfo],
    certificates: Option<&redis::TlsCertificates>,
) -> Result<Vec<HashMap<String, String>>, String> {
    let mut last_error = None;
    for info in nodes {
        let result = async {
            let client = build_redis_client(info.clone(), certificates)?;
            let mut con = client
                .get_multiplexed_async_connection_with_config(&redis_async_connection_config())
                .await
                .map_err(|error| error.to_string())?;
            let result = redis::cmd("SENTINEL").arg("MASTERS").query_async(&mut con).await;
            match result {
                // Match the old Sentinel client's single reconnect on an I/O
                // query failure, followed by trying the next configured node.
                Err(error) if error.is_io_error() || error.is_unrecoverable_error() => {
                    let mut con = client
                        .get_multiplexed_async_connection_with_config(&redis_async_connection_config())
                        .await
                        .map_err(|error| error.to_string())?;
                    redis::cmd("SENTINEL").arg("MASTERS").query_async(&mut con).await.map_err(|error| error.to_string())
                }
                result => result.map_err(|error| error.to_string()),
            }
        }
        .await;
        match result {
            Ok(masters) => return Ok(masters),
            Err(error) => last_error = Some(error),
        }
    }
    Err(last_error.unwrap_or_else(|| "At least one Sentinel is required".to_string()))
}

fn sentinel_eligible_master(metadata: &HashMap<String, String>, service_name: &str) -> Option<RedisNodeEndpoint> {
    if metadata.get("name").map(String::as_str) != Some(service_name) {
        return None;
    }
    let flags = metadata.get("flags")?;
    if !flags.contains("master") || flags.contains("s_down") || flags.contains("o_down") {
        return None;
    }
    Some(RedisNodeEndpoint { host: metadata.get("ip")?.clone(), port: metadata.get("port")?.parse().ok()? })
}

async fn sentinel_is_master<C>(con: &mut C) -> redis::RedisResult<bool>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let role_error = match redis::cmd("ROLE").query_async::<redis::Role>(con).await {
        Ok(role) => return Ok(matches!(role, redis::Role::Primary { .. })),
        Err(error) => error,
    };
    let fallback = redis::cmd("INFO").arg("REPLICATION").query_async::<String>(con).await.and_then(|info| {
        let roles: HashMap<_, _> = info
            .split("\r\n")
            .filter(|line| !line.trim_start().starts_with('#'))
            .filter_map(|line| line.split_once(':'))
            .collect();
        roles.get("role").map(|role| *role == "master").ok_or_else(|| {
            redis::RedisError::from((redis::ErrorKind::UnexpectedReturnType, "Missing role in INFO REPLICATION"))
        })
    });
    match fallback {
        Ok(is_master) => Ok(is_master),
        // Preserve the original error when ROLE failed for more than an
        // unavailable command; otherwise expose the INFO fallback failure.
        Err(_) if role_error.kind() != redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError) => {
            Err(role_error)
        }
        Err(error) => Err(error),
    }
}

pub async fn discover_sentinel_master(
    config: &ConnectionConfig,
    host: &str,
    port: u16,
) -> Result<RedisNodeEndpoint, String> {
    let service_name = config.redis_sentinel_master.trim();
    if service_name.is_empty() {
        return Err("Redis Sentinel master name is required".to_string());
    }

    let certificates = load_redis_tls_certificates(config)?;
    let client = build_redis_client(
        connection_info(
            host,
            port,
            config.redis_sentinel_tls,
            config.redis_tls_insecure(),
            &config.redis_sentinel_username,
            &config.redis_sentinel_password,
            0,
        )?,
        certificates.as_ref(),
    )
    .map_err(|e| format!("Redis Sentinel connect failed: {e}"))?;
    let mut con = connect_client_with_timeout(client, connection_timeout(), "Redis Sentinel").await?;
    let raw = tokio::time::timeout(
        connection_timeout(),
        redis::cmd("SENTINEL").arg("get-master-addr-by-name").arg(service_name).query_async::<RedisRawValue>(&mut con),
    )
    .await
    .map_err(|_| format!("Redis Sentinel master lookup timed out ({}s)", CONNECTION_TIMEOUT_SECS))?
    .map_err(|e| format!("Redis Sentinel master lookup failed: {e}"))?;

    redis_sentinel_master_endpoint(raw)
}

pub async fn connect_cluster(config: &ConnectionConfig) -> Result<RedisClusterPool, String> {
    let seed_nodes = redis_cluster_seed_nodes(config)?;
    let timeout = Duration::from_secs(config.effective_connect_timeout_secs());
    let certificates = load_redis_tls_certificates(config)?;
    let mut last_error = None;
    for auth in redis_auth_candidates(&config.username, &config.password) {
        let cluster_nodes: Vec<ConnectionInfo> = seed_nodes
            .iter()
            .map(|endpoint| {
                connection_info(
                    &endpoint.host,
                    endpoint.port,
                    config.ssl,
                    config.redis_tls_insecure(),
                    &auth.username,
                    &auth.password,
                    0,
                )
            })
            .collect::<Result<_, _>>()?;
        let mut builder = ClusterClient::builder(cluster_nodes).connection_timeout(timeout);
        if let Some(certificates) = &certificates {
            builder = builder.certs(certificates.clone());
        }
        let client = builder.build().map_err(|e| format!("Redis cluster connection failed: {e}"))?;
        let mut con = match tokio::time::timeout(timeout, client.get_async_connection())
            .await
            .map_err(|_| format!("Redis cluster connection timed out ({}s)", timeout.as_secs()))?
            .map_err(|e| format!("Redis cluster connection failed: {e}"))
        {
            Ok(con) => con,
            Err(err) if last_error.is_none() || is_redis_auth_error(&err) => {
                let should_retry = is_redis_auth_error(&err);
                last_error = Some(err);
                if should_retry {
                    continue;
                }
                break;
            }
            Err(err) => return Err(err),
        };

        let cluster_ping = match tokio::time::timeout(timeout, redis::cmd("PING").query_async::<String>(&mut con)).await
        {
            Ok(Ok(_)) => Ok(()),
            // Reachable and authenticated, only the PING privilege is missing (issue #9394).
            Ok(Err(error)) if is_redis_command_denied_error(&error.to_string()) => Ok(()),
            Ok(Err(error)) => Err(format!("Redis cluster ping failed: {error}")),
            Err(_) => Err(format!("Redis cluster ping timed out ({}s)", timeout.as_secs())),
        };
        match cluster_ping {
            Ok(_) => {
                let seed_routes = identity_routes(&seed_nodes);
                let slot_ranges = cluster_slot_ranges_from_routes(
                    &seed_routes,
                    config.ssl,
                    config.redis_tls_insecure(),
                    certificates.as_ref(),
                    &auth.username,
                    &auth.password,
                )
                .await
                .unwrap_or_default();
                let node_routes = identity_routes(&unique_master_nodes(&slot_ranges));
                return Ok(RedisClusterPool {
                    connection: Some(Mutex::new(con)),
                    database_connections: Box::new(tokio::sync::Mutex::new(HashMap::new())),
                    database_capability: Box::new(tokio::sync::Mutex::new(None)),
                    seed_nodes,
                    seed_routes,
                    slot_ranges,
                    node_routes,
                    tls: config.ssl,
                    tls_insecure: config.redis_tls_insecure(),
                    tls_certificates: certificates.clone().map(Box::new),
                    username: auth.username,
                    password: auth.password,
                    scan_sessions: Box::new(Mutex::new(RedisClusterScanSessions::default())),
                });
            }
            Err(err) if last_error.is_none() || is_redis_auth_error(&err) => {
                let should_retry = is_redis_auth_error(&err);
                last_error = Some(err);
                if !should_retry {
                    break;
                }
            }
            Err(err) => return Err(err),
        }
    }
    Err(last_error.unwrap_or_else(|| "Redis cluster connection failed".to_string()))
}

pub async fn discover_cluster_slot_ranges_from_routes(
    config: &ConnectionConfig,
    seed_routes: &[RedisNodeRoute],
) -> Result<(RedisClusterAuth, Vec<RedisClusterSlotRange>), String> {
    let mut last_error = None;
    let certificates = load_redis_tls_certificates(config)?;
    for auth in redis_auth_candidates(&config.username, &config.password) {
        match cluster_slot_ranges_from_routes(
            seed_routes,
            config.ssl,
            config.redis_tls_insecure(),
            certificates.as_ref(),
            &auth.username,
            &auth.password,
        )
        .await
        {
            Ok(slot_ranges) if !slot_ranges.is_empty() => {
                return Ok((RedisClusterAuth { username: auth.username, password: auth.password }, slot_ranges));
            }
            Ok(_) => {
                last_error = Some("Redis cluster master discovery returned no slots".to_string());
            }
            Err(err) if last_error.is_none() || is_redis_auth_error(&err) => {
                let should_retry = is_redis_auth_error(&err);
                last_error = Some(err);
                if !should_retry {
                    break;
                }
            }
            Err(err) => return Err(err),
        }
    }
    Err(last_error.unwrap_or_else(|| "Redis cluster master discovery failed".to_string()))
}

pub async fn connect_routed_cluster(
    config: &ConnectionConfig,
    seed_routes: Vec<RedisNodeRoute>,
    slot_ranges: Vec<RedisClusterSlotRange>,
    node_routes: Vec<RedisNodeRoute>,
    auth: RedisClusterAuth,
) -> Result<RedisClusterPool, String> {
    let seed_nodes = redis_cluster_seed_nodes(config)?;
    let pool = RedisClusterPool {
        connection: None,
        database_connections: Box::new(tokio::sync::Mutex::new(HashMap::new())),
        database_capability: Box::new(tokio::sync::Mutex::new(None)),
        seed_nodes,
        seed_routes,
        slot_ranges,
        node_routes,
        tls: config.ssl,
        tls_insecure: config.redis_tls_insecure(),
        tls_certificates: load_redis_tls_certificates(config)?.map(Box::new),
        username: auth.username,
        password: auth.password,
        scan_sessions: Box::new(Mutex::new(RedisClusterScanSessions::default())),
    };
    {
        let mut con = cluster_any_connection(&pool).await?;
        redis_ping(&mut con, "Redis cluster", connection_timeout()).await?;
    }
    Ok(pool)
}

pub async fn test_connection(connection: &RedisConnection) -> Result<(), String> {
    match connection {
        RedisConnection::Direct(con) => {
            let mut con = con.lock().await;
            redis_ping(&mut *con, "Redis", connection_timeout()).await
        }
        RedisConnection::Cluster(cluster) => {
            let mut con = cluster_any_connection(cluster).await?;
            redis_ping(&mut con, "Redis cluster", connection_timeout()).await
        }
    }
}

/// Read the Redis server identity without making metadata unavailable when the
/// INFO command is disabled by ACL or server policy.
pub async fn database_connection_info(connection: &RedisConnection) -> Result<DatabaseConnectionInfo, String> {
    match connection {
        RedisConnection::Direct(con) => {
            let mut con = con.lock().await;
            redis_database_connection_info(&mut *con).await
        }
        RedisConnection::Cluster(pool) => {
            let mut con = cluster_any_connection(pool).await?;
            redis_database_connection_info(&mut con).await
        }
    }
}

async fn redis_database_connection_info<C>(con: &mut C) -> Result<DatabaseConnectionInfo, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let info =
        match tokio::time::timeout(connection_timeout(), redis::cmd("INFO").arg("server").query_async::<String>(con))
            .await
        {
            Ok(Ok(info)) => info,
            // Managed Redis accounts and proxies frequently allow connecting but not `INFO`. The
            // connection is still usable, so report the identity we do know instead of failing all
            // server metadata (issue #9394).
            Ok(Err(error)) if is_redis_command_denied_error(&error.to_string()) => String::new(),
            Ok(Err(error)) => return Err(format!("Redis INFO command failed: {error}")),
            Err(_) => {
                return Err(format!("Redis INFO command timed out ({}s)", CONNECTION_TIMEOUT_SECS));
            }
        };
    let product_version = info.lines().find_map(|line| {
        let (key, value) = line.trim().split_once(':')?;
        (key.eq_ignore_ascii_case("redis_version") && !value.trim().is_empty()).then(|| value.trim().to_string())
    });
    Ok(DatabaseConnectionInfo {
        product_name: Some("Redis".to_string()),
        product_version,
        ..DatabaseConnectionInfo::default()
    })
}

async fn redis_ping<C>(con: &mut C, label: &str, timeout: std::time::Duration) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    match tokio::time::timeout(timeout, redis::cmd("PING").query_async::<String>(con)).await {
        Ok(Ok(_)) => Ok(()),
        // The server is reachable and the credentials were accepted; only the PING privilege is
        // missing, which does not make the connection unusable (issue #9394).
        Ok(Err(error)) if is_redis_command_denied_error(&error.to_string()) => Ok(()),
        Ok(Err(error)) => Err(format!("{label} ping failed: {error}")),
        Err(_) => Err(format!("{label} ping timed out ({}s)", timeout.as_secs())),
    }
}

fn redis_sentinel_nodes(config: &ConnectionConfig) -> Result<Vec<ConnectionInfo>, String> {
    redis_sentinel_node_endpoints(config)?
        .iter()
        .map(|endpoint| {
            connection_info(
                &endpoint.host,
                endpoint.port,
                config.redis_sentinel_tls,
                config.redis_tls_insecure(),
                &config.redis_sentinel_username,
                &config.redis_sentinel_password,
                0,
            )
        })
        .collect()
}

pub fn redis_sentinel_node_endpoints(config: &ConnectionConfig) -> Result<Vec<RedisNodeEndpoint>, String> {
    redis_node_endpoints(
        config.redis_sentinel_nodes.trim(),
        config.host.trim(),
        config.port,
        "Redis Sentinel node",
        26379,
    )
}

pub fn redis_cluster_seed_nodes(config: &ConnectionConfig) -> Result<Vec<RedisNodeEndpoint>, String> {
    redis_node_endpoints(
        config.redis_cluster_nodes.trim(),
        config.host.trim(),
        config.port,
        "Redis cluster seed node",
        6379,
    )
}

fn redis_node_endpoints(
    raw_nodes: &str,
    fallback_host: &str,
    fallback_port: u16,
    label: &str,
    default_port: u16,
) -> Result<Vec<RedisNodeEndpoint>, String> {
    let endpoints: Vec<String> = if raw_nodes.is_empty() {
        vec![format!("{fallback_host}:{}", if fallback_port == 0 { default_port } else { fallback_port })]
    } else {
        raw_nodes
            .split([',', ';', '\n', '\r'])
            .map(str::trim)
            .filter(|node| !node.is_empty())
            .map(ToOwned::to_owned)
            .collect()
    };

    if endpoints.is_empty() {
        return Err(format!("At least one {label} is required"));
    }

    endpoints
        .iter()
        .map(|endpoint| {
            let (host, port) = parse_redis_endpoint(endpoint, default_port)?;
            Ok(RedisNodeEndpoint { host, port })
        })
        .collect()
}

fn redis_sentinel_master_endpoint(value: RedisRawValue) -> Result<RedisNodeEndpoint, String> {
    let RedisRawValue::Array(parts) = value else {
        return Err("Redis Sentinel master lookup returned an invalid response".to_string());
    };
    if parts.len() != 2 {
        return Err("Redis Sentinel master lookup returned an invalid endpoint".to_string());
    }
    let Some(host) = redis_value_to_string(parts[0].clone()) else {
        return Err("Redis Sentinel master lookup returned an invalid host".to_string());
    };
    let Some(port_text) = redis_value_to_string(parts[1].clone()) else {
        return Err("Redis Sentinel master lookup returned an invalid port".to_string());
    };
    let port = parse_redis_port(&port_text)?;
    Ok(RedisNodeEndpoint { host, port })
}

/// Loads Redis TLS material from the connection's certificate paths.
///
/// `None` keeps redis-rs on its default trust store. A CA file adds a private
/// root without disabling verification, and a client cert/key pair enables
/// mutual TLS (Redis 6+ `tls-auth-clients yes`). The paths are loaded whenever
/// they are configured because Sentinel nodes can use their own TLS switch
/// (`redis_sentinel_tls`) independently of the data connection.
fn load_redis_tls_certificates(config: &ConnectionConfig) -> Result<Option<redis::TlsCertificates>, String> {
    let ca_path = config.ca_cert_path.trim();
    let client_cert_path = config.client_cert_path.trim();
    let client_key_path = config.client_key_path.trim();
    if client_cert_path.is_empty() != client_key_path.is_empty() {
        return Err("Redis TLS client certificate and key must be configured together".to_string());
    }
    if ca_path.is_empty() && client_cert_path.is_empty() {
        return Ok(None);
    }
    let read = |path: &str, label: &str| {
        fs::read(path).map_err(|error| format!("Failed to read Redis TLS {label} '{path}': {error}"))
    };
    let root_cert = if ca_path.is_empty() { None } else { Some(read(ca_path, "CA certificate")?) };
    let client_tls = if client_cert_path.is_empty() {
        None
    } else {
        Some(redis::ClientTlsConfig {
            client_cert: read(client_cert_path, "client certificate")?,
            client_key: read(client_key_path, "client key")?,
        })
    };
    Ok(Some(redis::TlsCertificates { client_tls, root_cert }))
}

fn build_redis_client(
    info: ConnectionInfo,
    certificates: Option<&redis::TlsCertificates>,
) -> Result<redis::Client, String> {
    let tls_addr = matches!(info.addr(), ConnectionAddr::TcpTls { .. });
    let result = match (tls_addr, certificates) {
        (true, Some(certificates)) => redis::Client::build_with_tls(info, certificates.clone()),
        _ => redis::Client::open(info),
    };
    result.map_err(|error| format!("Redis connection failed: {error}"))
}

fn connection_info(
    host: &str,
    port: u16,
    tls: bool,
    insecure: bool,
    username: &str,
    password: &str,
    db: i64,
) -> Result<ConnectionInfo, String> {
    let addr = if tls {
        ConnectionAddr::TcpTls { host: host.to_string(), port, insecure, tls_params: None }
    } else {
        ConnectionAddr::Tcp(host.to_string(), port)
    };
    addr.into_connection_info()
        .map(|info| info.set_redis_settings(redis_connection_info(username, password, db)))
        .map_err(|error| format!("Redis connection configuration failed: {error}"))
}

fn redis_connection_info(username: &str, password: &str, db: i64) -> RedisConnectionInfo {
    let mut info = RedisConnectionInfo::default().set_db(db).set_protocol(ProtocolVersion::RESP2);
    if let Some(username) = non_empty_string(username) {
        info = info.set_username(username);
    }
    if let Some(password) = non_empty_string(password) {
        info = info.set_password(password);
    }
    info
}

fn redis_auth_candidates(username: &str, password: &str) -> Vec<RedisAuthCandidate> {
    let username = username.trim();
    let password = password.trim();
    let mut candidates = vec![RedisAuthCandidate { username: username.to_string(), password: password.to_string() }];
    if !username.is_empty() && !password.is_empty() {
        candidates.push(RedisAuthCandidate { username: String::new(), password: format!("{username}@{password}") });
    }
    candidates
}

fn redis_database_index(config: &ConnectionConfig) -> i64 {
    config.effective_database().and_then(|database| database.parse::<i64>().ok()).unwrap_or(0)
}

fn is_redis_auth_error(error: &str) -> bool {
    let error = error.to_ascii_lowercase();
    error.contains("auth") || error.contains("wrongpass") || error.contains("invalid username-password")
}

/// True when the server rejected a command because the account may not run it, rather than because
/// the connection or the credentials are broken. Redis reports this as `NOPERM`; managed Redis
/// endpoints and proxies in front of them use "not support" / "unknown command" phrasing for the
/// same situation, which is what issue #9394 hit when its account was denied `PING`.
fn is_redis_command_denied_error(error: &str) -> bool {
    let error = error.to_ascii_lowercase();
    error.contains("noperm")
        || error.contains("no permissions")
        || error.contains("permission denied")
        || error.contains("not support")
        || error.contains("unknown command")
        || error.contains("unsupported command")
}

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

fn parse_redis_endpoint(endpoint: &str, default_port: u16) -> Result<(String, u16), String> {
    let endpoint = endpoint.trim();
    if endpoint.is_empty() {
        return Err("Redis node cannot be empty".to_string());
    }
    let endpoint = endpoint.strip_prefix("redis://").or_else(|| endpoint.strip_prefix("rediss://")).unwrap_or(endpoint);
    let endpoint = endpoint.rsplit_once('@').map(|(_, tail)| tail).unwrap_or(endpoint);
    let endpoint = endpoint.split(['/', '?', '#']).next().unwrap_or(endpoint);

    if let Some(rest) = endpoint.strip_prefix('[') {
        let Some((host, tail)) = rest.split_once(']') else {
            return Err(format!("Invalid Redis node '{endpoint}'"));
        };
        let port = tail.strip_prefix(':').filter(|value| !value.is_empty()).map(parse_redis_port).transpose()?;
        return Ok((host.to_string(), port.unwrap_or(default_port)));
    }

    if let Some((host, port)) = endpoint.rsplit_once(':') {
        if !host.contains(':') && port.chars().all(|ch| ch.is_ascii_digit()) {
            return Ok((host.to_string(), parse_redis_port(port)?));
        }
    }

    Ok((endpoint.to_string(), default_port))
}

fn parse_redis_port(port: &str) -> Result<u16, String> {
    port.parse::<u16>().map_err(|_| format!("Invalid Redis port '{port}'"))
}

fn redis_async_connection_config() -> redis::AsyncConnectionConfig {
    // redis-rs 1.x defaults to 1s connection / 500ms response deadlines. Keep DBX's
    // existing outer connection deadline and unrestricted command duration (for
    // blocking commands and large values), as with redis-rs 0.32.
    redis::AsyncConnectionConfig::new().set_connection_timeout(None).set_response_timeout(None)
}

async fn connect_client(client: redis::Client) -> Result<redis::aio::MultiplexedConnection, String> {
    connect_client_with_timeout(client, connection_timeout(), "Redis").await
}

pub async fn connect_direct_node(
    endpoint: &RedisNodeEndpoint,
    tls: bool,
    insecure: bool,
    certificates: Option<&redis::TlsCertificates>,
    username: &str,
    password: &str,
) -> Result<redis::aio::MultiplexedConnection, String> {
    connect_direct_node_in_db(endpoint, tls, insecure, certificates, username, password, 0).await
}

async fn connect_direct_node_in_db(
    endpoint: &RedisNodeEndpoint,
    tls: bool,
    insecure: bool,
    certificates: Option<&redis::TlsCertificates>,
    username: &str,
    password: &str,
    db: u32,
) -> Result<redis::aio::MultiplexedConnection, String> {
    let client = build_redis_client(
        connection_info(&endpoint.host, endpoint.port, tls, insecure, username, password, i64::from(db))?,
        certificates,
    )?;
    connect_client(client).await
}

pub async fn connect_monitor(
    config: &ConnectionConfig,
    host: &str,
    port: u16,
    timeout: std::time::Duration,
) -> Result<redis::aio::Monitor, String> {
    let mut last_error = String::new();
    let certificates = load_redis_tls_certificates(config)?;
    for info in standalone_connection_infos(config, host, port)? {
        let client = build_redis_client(info, certificates.as_ref())?;
        let connect = async {
            let mut validation =
                client.get_multiplexed_async_connection_with_config(&redis_async_connection_config()).await?;
            redis::cmd("MONITOR").query_async::<()>(&mut validation).await?;
            drop(validation);
            client.get_async_monitor().await
        };
        match tokio::time::timeout(timeout, connect).await {
            Ok(Ok(monitor)) => return Ok(monitor),
            Ok(Err(error)) => {
                last_error = error.to_string();
                if !is_redis_auth_error(&last_error) {
                    break;
                }
            }
            Err(_) => return Err("Redis MONITOR connection timed out".to_string()),
        }
    }
    Err(last_error)
}

pub async fn connect_pubsub(
    config: &ConnectionConfig,
    host: &str,
    port: u16,
    timeout: std::time::Duration,
) -> Result<redis::aio::PubSub, String> {
    let mut last_error = None;
    let certificates = load_redis_tls_certificates(config)?;
    for auth in redis_auth_candidates(&config.username, &config.password) {
        let client = build_redis_client(
            connection_info(
                host,
                port,
                config.ssl,
                config.redis_tls_insecure(),
                &auth.username,
                &auth.password,
                redis_database_index(config),
            )?,
            certificates.as_ref(),
        )?;
        match tokio::time::timeout(timeout, client.get_async_pubsub()).await {
            Ok(Ok(pubsub)) => return Ok(pubsub),
            Ok(Err(err)) => {
                let err_str = err.to_string();
                if last_error.is_none() || is_redis_auth_error(&err_str) {
                    let should_retry = is_redis_auth_error(&err_str);
                    last_error = Some(err_str);
                    if !should_retry {
                        break;
                    }
                } else {
                    return Err(err_str);
                }
            }
            Err(_) => {
                last_error = Some(format!("Redis PubSub connection timed out ({}s)", timeout.as_secs()));
                break;
            }
        }
    }
    Err(last_error.unwrap_or_else(|| "Redis PubSub connection failed".to_string()))
}

pub async fn publish_message<C>(con: &mut C, channel: &str, message: &str) -> Result<u64, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("PUBLISH").arg(channel).arg(message).query_async(con).await.map_err(|e| e.to_string())
}

pub async fn list_databases<C>(con: &mut C) -> Result<Vec<RedisDatabaseInfo>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    list_databases_with_timeout(con, connection_timeout()).await
}

/// Lists the logical databases of a standalone Redis connection.
///
/// Both metadata probes are bounded. A server (or a proxy in front of it) that accepts the
/// connection and answers `PING` but never replies to `CONFIG GET databases` / `INFO keyspace`
/// used to keep the caller waiting forever: the connection dialog's database picker stayed in
/// its loading state with the rest of the dialog disabled (#12426). A probe that never answers
/// now reports a timeout — the call stops there instead of issuing another command, because a
/// multiplexed connection cannot answer later requests while a reply is still outstanding.
pub async fn list_databases_with_timeout<C>(con: &mut C, timeout: Duration) -> Result<Vec<RedisDatabaseInfo>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let configured_count =
        match tokio::time::timeout(timeout, redis::cmd("CONFIG").arg("GET").arg("databases").query_async(con)).await {
            Ok(Ok(value)) => parse_database_count(value),
            // Renamed or denied CONFIG keeps the DBX default, as before.
            Ok(Err(_)) => None,
            Err(_) => {
                return Err(format!(
                    "Redis database list timed out ({}s): the server did not answer CONFIG GET databases",
                    timeout.as_secs()
                ))
            }
        };

    let keyspace_db_infos = match tokio::time::timeout(timeout, list_keyspace_databases(con)).await {
        Ok(Ok(infos)) => infos,
        Ok(Err(_)) => Vec::new(),
        Err(_) => {
            return Err(format!(
                "Redis database list timed out ({}s): the server did not answer INFO keyspace",
                timeout.as_secs()
            ))
        }
    };
    let database_count = configured_count.unwrap_or(DEFAULT_REDIS_DATABASES);
    let max_db = keyspace_db_infos.iter().map(|db| db.db).max().map(|db| db + 1).unwrap_or(0);
    let visible_count = database_count.max(max_db).max(1);
    let keyspace_counts =
        keyspace_db_infos.into_iter().map(|db| (db.db, db.keys)).collect::<std::collections::HashMap<_, _>>();

    Ok((0..visible_count)
        .map(|db| RedisDatabaseInfo { db, keys: keyspace_counts.get(&db).copied().flatten() })
        .collect())
}

fn parse_database_count(value: redis::Value) -> Option<u32> {
    let values = match value {
        redis::Value::Array(values) => values,
        _ => return None,
    };

    values.windows(2).find_map(|pair| {
        let key = String::from_redis_value(pair[0].clone()).ok()?;
        if key.eq_ignore_ascii_case("databases") {
            String::from_redis_value(pair[1].clone()).ok()?.parse().ok()
        } else {
            None
        }
    })
}

async fn list_keyspace_databases<C>(con: &mut C) -> Result<Vec<RedisDatabaseInfo>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let info: String = redis::cmd("INFO").arg("keyspace").query_async(con).await.map_err(|e| e.to_string())?;

    // kvrocks 的键数是异步统计出来的(官方文档:需要先执行 `DBSIZE SCAN` 才会更新
    // DBSIZE 与 INFO keyspace),未统计前它会把 dbN 的 keys 全部报成 0,并在 keyspace
    // 段里带上 `last_dbsize_scan_timestamp:0`。识别到这个标记时不把 0 当成真实数量,
    // 避免侧边栏显示 "db0 (0)" 这类误导信息。
    let keyspace_counts_are_stale = info.lines().any(|line| {
        line.split_once(':').is_some_and(|(key, value)| {
            key.trim().eq_ignore_ascii_case("last_dbsize_scan_timestamp") && value.trim() == "0"
        })
    });

    let mut dbs = Vec::new();
    for line in info.lines() {
        if line.starts_with("db") {
            if let Some((db_part, stats_part)) = line.split_once(':') {
                if let Some(num) = db_part.strip_prefix("db") {
                    if let Ok(db) = num.parse::<u32>() {
                        let keys = if keyspace_counts_are_stale {
                            None
                        } else {
                            stats_part
                                .split(',')
                                .find_map(|part| part.strip_prefix("keys=").and_then(|value| value.parse::<u64>().ok()))
                        };
                        dbs.push(RedisDatabaseInfo { db, keys });
                    }
                }
            }
        }
    }
    Ok(dbs)
}

pub async fn select_db<C>(con: &mut C, db: u32) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("SELECT").arg(db).query_async(con).await.map_err(|e| e.to_string())
}

pub async fn execute_console_command<C>(
    con: &mut C,
    db: u32,
    command_text: &str,
    skip_safety_check: bool,
) -> Result<RedisCommandResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let selection: redis::RedisResult<()> = redis::cmd("SELECT").arg(db).query_async(con).await;
    if let Err(error) = selection {
        if !is_unavailable_db_zero_select(&error, db) {
            return Err(error.to_string());
        }
    }
    execute_command(con, command_text, skip_safety_check).await
}

fn is_unavailable_db_zero_select(error: &redis::RedisError, db: u32) -> bool {
    if db != 0 || error.kind() != redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError) {
        return false;
    }
    let detail = error.detail().unwrap_or_default().trim_start();
    let prefix_len = "unknown command".len();
    detail.get(..prefix_len).is_some_and(|prefix| prefix.eq_ignore_ascii_case("unknown command"))
}

#[derive(Debug, Clone, PartialEq, Eq)]
enum ClusterDatabaseCapability {
    Known(u32),
    Unsupported,
    Unknown(String),
}

fn parse_cluster_database_capability(raw: RedisRawValue) -> Result<ClusterDatabaseCapability, String> {
    let entries = match raw {
        RedisRawValue::Array(entries) if entries.is_empty() => return Ok(ClusterDatabaseCapability::Unsupported),
        RedisRawValue::Map(entries) if entries.is_empty() => return Ok(ClusterDatabaseCapability::Unsupported),
        RedisRawValue::Array(entries) if entries.len() == 2 => entries,
        RedisRawValue::Map(mut entries) if entries.len() == 1 => {
            let (key, value) = entries.remove(0);
            vec![key, value]
        }
        _ => return Err("Malformed CONFIG GET cluster-databases response".to_string()),
    };
    if cluster_config_text(&entries[0]) != Some("cluster-databases") {
        return Err("Unexpected CONFIG GET cluster-databases setting".to_string());
    }
    let count = cluster_config_text(&entries[1])
        .filter(|value| !value.is_empty() && value.bytes().all(|byte| byte.is_ascii_digit()))
        .and_then(|value| value.parse::<u32>().ok())
        .filter(|count| *count > 0 && *count <= i32::MAX as u32)
        .ok_or("Invalid cluster-databases count: expected an integer from 1 through 2147483647")?;
    Ok(ClusterDatabaseCapability::Known(count))
}

fn cluster_config_text(value: &RedisRawValue) -> Option<&str> {
    // CONFIG GET returns string keys and values, not generic numeric RESP values.
    match value {
        RedisRawValue::BulkString(bytes) => std::str::from_utf8(bytes).ok(),
        RedisRawValue::SimpleString(text) => Some(text),
        _ => None,
    }
}

fn combine_cluster_database_capabilities(
    capabilities: Vec<ClusterDatabaseCapability>,
) -> Result<ClusterDatabaseCapability, String> {
    let mut known = None;
    let mut unsupported = false;
    let mut unknown = Vec::new();
    for capability in capabilities {
        match capability {
            ClusterDatabaseCapability::Known(count) => {
                if known.is_some_and(|previous| previous != count) || unsupported {
                    return Err("Conflicting cluster-databases settings across cluster masters".to_string());
                }
                known = Some(count);
            }
            ClusterDatabaseCapability::Unsupported => {
                if known.is_some() {
                    return Err("Conflicting cluster-databases support across cluster masters".to_string());
                }
                unsupported = true;
            }
            ClusterDatabaseCapability::Unknown(reason) => unknown.push(reason),
        }
    }
    if !unknown.is_empty() {
        return Ok(ClusterDatabaseCapability::Unknown(unknown.join("; ")));
    }
    if let Some(count) = known {
        Ok(ClusterDatabaseCapability::Known(count))
    } else if unsupported {
        Ok(ClusterDatabaseCapability::Unsupported)
    } else {
        Err("Redis cluster has no masters for database discovery".to_string())
    }
}

async fn discover_cluster_database_capability(pool: &RedisClusterPool) -> Result<ClusterDatabaseCapability, String> {
    // An explicit metadata refresh invalidates stale success even if it fails.
    *pool.database_capability.lock().await = None;
    let mut capabilities = Vec::new();
    for endpoint in cluster_master_nodes(pool).await? {
        let mut con = connect_cluster_node(pool, &endpoint).await?;
        let capability = match redis::cmd("CONFIG").arg("GET").arg("cluster-databases").query_async(&mut con).await {
            Ok(raw) => parse_cluster_database_capability(raw)?,
            Err(error) if is_redis_command_denied_error(&error.to_string()) => {
                ClusterDatabaseCapability::Unknown(format!("{}:{}: {error}", endpoint.host, endpoint.port))
            }
            Err(error) => {
                return Err(format!("Database discovery on {}:{} failed: {error}", endpoint.host, endpoint.port))
            }
        };
        capabilities.push(capability);
    }
    let capability = combine_cluster_database_capabilities(capabilities)?;
    *pool.database_capability.lock().await = Some(capability.clone());
    Ok(capability)
}

pub async fn cluster_database_diagnostic(pool: &RedisClusterPool) -> Option<String> {
    match &*pool.database_capability.lock().await {
        Some(ClusterDatabaseCapability::Unknown(reason)) => Some(reason.clone()),
        _ => None,
    }
}

pub async fn ensure_cluster_database(pool: &RedisClusterPool, db: u32) -> Result<(), String> {
    // Permission-limited discovery must never make the existing db0 connection unusable.
    if db == 0 {
        return Ok(());
    }
    let cached = pool.database_capability.lock().await.clone();
    let capability = match cached {
        Some(capability @ ClusterDatabaseCapability::Known(_)) => capability,
        _ => discover_cluster_database_capability(pool).await?,
    };
    match capability {
        ClusterDatabaseCapability::Known(count) if db < count => Ok(()),
        ClusterDatabaseCapability::Known(count) => Err(format!("Database db{db} is outside this cluster's configured range db0–db{}; refresh the database list", count - 1)),
        ClusterDatabaseCapability::Unsupported => Err("This cluster does not expose multiple databases; use db0".to_string()),
        ClusterDatabaseCapability::Unknown(reason) => Err(format!("Cannot verify db{db}: {reason}. Allow CONFIG GET cluster-databases on all masters and refresh the database list; db0 remains available")),
    }
}

pub fn encode_cluster_cursor(node_index: usize, cursor: u64) -> Result<u64, String> {
    if node_index > CLUSTER_CURSOR_NODE_MASK as usize {
        return Err("Redis cluster cursor exceeded node limit".to_string());
    }
    if cursor > CLUSTER_CURSOR_SCAN_MASK {
        return Err("Redis cluster cursor exceeded scan limit".to_string());
    }
    Ok(((node_index as u64) << (64 - CLUSTER_CURSOR_NODE_BITS)) | (cursor & CLUSTER_CURSOR_SCAN_MASK))
}

pub fn decode_cluster_cursor(cursor: u64) -> (usize, u64) {
    if cursor == 0 {
        return (0, 0);
    }
    let node_index = (cursor >> (64 - CLUSTER_CURSOR_NODE_BITS)) as usize;
    let node_cursor = cursor & CLUSTER_CURSOR_SCAN_MASK;
    (node_index, node_cursor)
}

pub async fn list_cluster_databases(pool: &RedisClusterPool) -> Result<Vec<RedisDatabaseInfo>, String> {
    let capability = discover_cluster_database_capability(pool).await?;
    let count = cluster_database_list_count(&capability)?;
    let master_nodes = cluster_master_nodes(pool).await?;
    let key_counts = cluster_database_key_counts(pool, &master_nodes).await.ok();
    Ok((0..count)
        .map(|db| RedisDatabaseInfo {
            db,
            keys: key_counts.as_ref().map(|counts| counts.get(&db).copied().unwrap_or(0)),
        })
        .collect())
}

fn cluster_database_list_count(capability: &ClusterDatabaseCapability) -> Result<u32, String> {
    let count = match *capability {
        ClusterDatabaseCapability::Known(count) => count,
        _ => 1,
    };
    if count > MAX_CLUSTER_DATABASE_LIST_ENTRIES {
        return Err(format!("This cluster is configured with {count} databases, exceeding the DBX database-list safety limit of {MAX_CLUSTER_DATABASE_LIST_ENTRIES}; no truncated list was returned"));
    }
    Ok(count)
}

fn parse_cluster_keyspace_counts(info: &str) -> Result<HashMap<u32, u64>, String> {
    if !info.lines().any(|line| line.trim() == "# Keyspace") {
        return Err("Missing INFO keyspace section".to_string());
    }
    let mut counts = HashMap::new();
    for line in info.lines().map(str::trim).filter(|line| line.starts_with("db")) {
        let (database, stats) = line.split_once(':').ok_or("Malformed INFO keyspace entry")?;
        let db = database[2..].parse::<u32>().map_err(|_| "Invalid INFO keyspace database")?;
        let keys = stats
            .split(',')
            .find_map(|stat| stat.strip_prefix("keys="))
            .and_then(|keys| keys.parse::<u64>().ok())
            .ok_or("Invalid INFO keyspace key count")?;
        if counts.insert(db, keys).is_some() {
            return Err("Duplicate INFO keyspace database".to_string());
        }
    }
    Ok(counts)
}

async fn cluster_database_key_counts(
    pool: &RedisClusterPool,
    masters: &[RedisNodeEndpoint],
) -> Result<HashMap<u32, u64>, String> {
    let mut totals: HashMap<u32, u64> = HashMap::new();
    for endpoint in masters {
        let mut con = connect_cluster_node(pool, endpoint).await?;
        let info: String =
            redis::cmd("INFO").arg("keyspace").query_async(&mut con).await.map_err(|error| error.to_string())?;
        for (db, keys) in parse_cluster_keyspace_counts(&info)? {
            let total = totals.entry(db).or_default();
            *total = total.checked_add(keys).ok_or("Cluster key count overflow")?;
        }
    }
    Ok(totals)
}

pub async fn scan_cluster_keys_page(
    pool: &RedisClusterPool,
    cursor: u64,
    pattern: &str,
    count: usize,
) -> Result<RedisScanResult, String> {
    scan_cluster_keys_page_with_options(pool, cursor, pattern, count, true).await
}

pub async fn scan_cluster_keys_page_with_options(
    pool: &RedisClusterPool,
    cursor: u64,
    pattern: &str,
    count: usize,
    include_types: bool,
) -> Result<RedisScanResult, String> {
    scan_cluster_keys_batch(pool, cursor, pattern, count, 1, include_types).await
}

pub async fn scan_cluster_keys_batch(
    pool: &RedisClusterPool,
    cursor: u64,
    pattern: &str,
    count: usize,
    max_iterations: usize,
    include_types: bool,
) -> Result<RedisScanResult, String> {
    scan_cluster_keys_batch_in_db(pool, 0, cursor, pattern, count, max_iterations, include_types).await
}

pub async fn scan_cluster_keys_batch_in_db(
    pool: &RedisClusterPool,
    db: u32,
    cursor: u64,
    pattern: &str,
    count: usize,
    max_iterations: usize,
    include_types: bool,
) -> Result<RedisScanResult, String> {
    ensure_cluster_database(pool, db).await?;
    scan_cluster_keys_batch_in_db_with(
        &pool.scan_sessions,
        || async { cluster_master_nodes(pool).await },
        |endpoint| async move { connect_cluster_node_in_db(pool, &endpoint, db).await },
        db,
        cursor,
        pattern,
        count,
        max_iterations,
        include_types,
    )
    .await
}

#[cfg(test)]
async fn scan_cluster_keys_batch_with<C, Discover, DiscoverFuture, Connect, ConnectFuture>(
    sessions: &Mutex<RedisClusterScanSessions>,
    discover_master_nodes: Discover,
    connect_node: Connect,
    cursor: u64,
    pattern: &str,
    count: usize,
    max_iterations: usize,
    include_types: bool,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
    Discover: FnMut() -> DiscoverFuture,
    DiscoverFuture: Future<Output = Result<Vec<RedisNodeEndpoint>, String>>,
    Connect: FnMut(RedisNodeEndpoint) -> ConnectFuture,
    ConnectFuture: Future<Output = Result<C, String>>,
{
    scan_cluster_keys_batch_in_db_with(
        sessions,
        discover_master_nodes,
        connect_node,
        0,
        cursor,
        pattern,
        count,
        max_iterations,
        include_types,
    )
    .await
}

async fn scan_cluster_keys_batch_in_db_with<C, Discover, DiscoverFuture, Connect, ConnectFuture>(
    sessions: &Mutex<RedisClusterScanSessions>,
    mut discover_master_nodes: Discover,
    connect_node: Connect,
    db: u32,
    cursor: u64,
    pattern: &str,
    count: usize,
    max_iterations: usize,
    include_types: bool,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
    Discover: FnMut() -> DiscoverFuture,
    DiscoverFuture: Future<Output = Result<Vec<RedisNodeEndpoint>, String>>,
    Connect: FnMut(RedisNodeEndpoint) -> ConnectFuture,
    ConnectFuture: Future<Output = Result<C, String>>,
{
    let (mut session, can_continue) = if cursor == 0 {
        let master_nodes = canonical_cluster_master_nodes(discover_master_nodes().await?);
        if master_nodes.is_empty() {
            return Ok(RedisScanResult { cursor: 0, keys: Vec::new(), total_keys: 0 });
        }
        let mut session = RedisClusterKeyScanSession::new(master_nodes, pattern);
        session.db = db;
        (session, false)
    } else {
        let mut store = sessions.lock().await;
        store.remove_expired();
        let session = store.entries.get(&cursor).ok_or(INVALID_CLUSTER_SCAN_CURSOR_ERROR)?;
        if session.pattern != pattern || session.db != db || session.value_filter.is_some() {
            return Err(INVALID_CLUSTER_SCAN_CURSOR_ERROR.to_string());
        }
        (store.take(cursor).ok_or(INVALID_CLUSTER_SCAN_CURSOR_ERROR)?, true)
    };
    let include_total_keys = !can_continue;
    let retry_session = can_continue.then(|| session.clone());

    let batch = match scan_cluster_keys_batch_on_session(
        &mut session,
        connect_node,
        pattern,
        count,
        max_iterations,
        include_types,
        include_total_keys,
    )
    .await
    {
        Ok(batch) => batch,
        Err(error) => {
            if let Some(retry_session) = retry_session {
                // A failed batch may have advanced across nodes without returning its keys, so retries must resume
                // from the request's original position rather than the partially mutated session.
                sessions.lock().await.insert(Some(cursor), retry_session);
            }
            return Err(error);
        }
    };

    if batch.complete {
        return Ok(RedisScanResult { cursor: 0, keys: batch.keys, total_keys: batch.total_keys });
    }

    let session_cursor = sessions.lock().await.insert(can_continue.then_some(cursor), session);
    Ok(RedisScanResult { cursor: session_cursor, keys: batch.keys, total_keys: batch.total_keys })
}

struct RedisClusterKeyScanBatch {
    keys: Vec<RedisKeyInfo>,
    total_keys: u64,
    complete: bool,
}

async fn scan_cluster_keys_batch_on_session<C, Connect, ConnectFuture>(
    session: &mut RedisClusterKeyScanSession,
    mut connect_node: Connect,
    pattern: &str,
    count: usize,
    max_iterations: usize,
    include_types: bool,
    include_total_keys: bool,
) -> Result<RedisClusterKeyScanBatch, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
    Connect: FnMut(RedisNodeEndpoint) -> ConnectFuture,
    ConnectFuture: Future<Output = Result<C, String>>,
{
    if session.master_nodes.is_empty() || session.is_complete() {
        return Ok(RedisClusterKeyScanBatch { keys: Vec::new(), total_keys: 0, complete: true });
    }

    let mut connections: Vec<Option<C>> = std::iter::repeat_with(|| None).take(session.master_nodes.len()).collect();
    let mut total_keys = 0;
    if include_total_keys {
        for (index, endpoint) in session.master_nodes.iter().cloned().enumerate() {
            let Ok(mut connection) = connect_node(endpoint).await else {
                continue;
            };
            total_keys += redis::cmd("DBSIZE").query_async::<u64>(&mut connection).await.unwrap_or(0);
            connections[index] = Some(connection);
        }
    }

    let iterations = max_iterations.max(1);
    let target_keys = count.max(1);
    let mut all_keys = Vec::new();

    for _ in 0..iterations {
        let Some(node_index) = session.next_unfinished_node_index() else {
            return Ok(RedisClusterKeyScanBatch { keys: all_keys, total_keys, complete: true });
        };
        if connections[node_index].is_none() {
            connections[node_index] = Some(connect_node(session.master_nodes[node_index].clone()).await?);
        }
        let connection = connections[node_index].as_mut().ok_or("Redis cluster node connection unavailable")?;
        let page = scan_keys_batch_inner(
            connection,
            session.node_cursors[node_index],
            pattern,
            count,
            1,
            include_types,
            false,
        )
        .await?;
        all_keys.extend(page.keys);

        session.node_cursors[node_index] = page.cursor;
        session.node_complete[node_index] = page.cursor == 0;
        session.advance_after(node_index);
        let complete = session.is_complete();

        if complete || all_keys.len() >= target_keys {
            return Ok(RedisClusterKeyScanBatch { keys: all_keys, total_keys, complete });
        }
    }

    Ok(RedisClusterKeyScanBatch { keys: all_keys, total_keys, complete: false })
}

fn canonical_cluster_master_nodes(mut master_nodes: Vec<RedisNodeEndpoint>) -> Vec<RedisNodeEndpoint> {
    master_nodes.sort_unstable_by(|left, right| left.host.cmp(&right.host).then(left.port.cmp(&right.port)));
    master_nodes.dedup();
    master_nodes
}

pub async fn scan_cluster_values_page(
    pool: &RedisClusterPool,
    cursor: u64,
    pattern: &str,
    query: &str,
    include_key_matches: bool,
    count: usize,
) -> Result<RedisScanResult, String> {
    scan_cluster_values_page_in_db(pool, 0, cursor, pattern, query, include_key_matches, count).await
}

pub async fn scan_cluster_values_page_in_db(
    pool: &RedisClusterPool,
    db: u32,
    cursor: u64,
    pattern: &str,
    query: &str,
    include_key_matches: bool,
    count: usize,
) -> Result<RedisScanResult, String> {
    ensure_cluster_database(pool, db).await?;
    scan_cluster_values_page_with(
        &pool.scan_sessions,
        || async { cluster_master_nodes(pool).await },
        |endpoint| async move { connect_cluster_node_in_db(pool, &endpoint, db).await },
        db,
        cursor,
        pattern,
        query,
        include_key_matches,
        count,
    )
    .await
}

async fn scan_cluster_values_page_with<C, Discover, DiscoverFuture, Connect, ConnectFuture>(
    sessions: &Mutex<RedisClusterScanSessions>,
    mut discover: Discover,
    mut connect: Connect,
    db: u32,
    cursor: u64,
    pattern: &str,
    query: &str,
    include_key_matches: bool,
    count: usize,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
    Discover: FnMut() -> DiscoverFuture,
    DiscoverFuture: Future<Output = Result<Vec<RedisNodeEndpoint>, String>>,
    Connect: FnMut(RedisNodeEndpoint) -> ConnectFuture,
    ConnectFuture: Future<Output = Result<C, String>>,
{
    let filter = Some((query.to_string(), include_key_matches));
    let mut session = if cursor == 0 {
        let mut session = RedisClusterKeyScanSession::new(canonical_cluster_master_nodes(discover().await?), pattern);
        session.db = db;
        session.value_filter = filter.clone();
        session
    } else {
        let mut store = sessions.lock().await;
        store.remove_expired();
        let session = store.entries.get(&cursor).ok_or(INVALID_CLUSTER_SCAN_CURSOR_ERROR)?;
        if session.db != db || session.pattern != pattern || session.value_filter != filter {
            return Err(INVALID_CLUSTER_SCAN_CURSOR_ERROR.to_string());
        }
        store.take(cursor).ok_or(INVALID_CLUSTER_SCAN_CURSOR_ERROR)?
    };
    let retry = session.clone();
    let result = async {
        let mut connections: Vec<Option<C>> =
            std::iter::repeat_with(|| None).take(session.master_nodes.len()).collect();
        if cursor == 0 {
            for (index, endpoint) in session.master_nodes.iter().cloned().enumerate() {
                // Counts are best-effort metadata, not a prerequisite for value search.
                if let Ok(mut con) = connect(endpoint).await {
                    let keys = redis::cmd("DBSIZE").query_async::<u64>(&mut con).await.unwrap_or(0);
                    session.total_keys += keys;
                    connections[index] = Some(con);
                }
            }
        }
        let mut keys = Vec::new();
        while let Some(index) = session.next_unfinished_node_index() {
            if connections[index].is_none() {
                connections[index] = Some(connect(session.master_nodes[index].clone()).await?);
            }
            let con = connections[index].as_mut().ok_or("Redis cluster node connection unavailable")?;
            let page = scan_values_page_inner(
                con,
                session.node_cursors[index],
                pattern,
                query,
                include_key_matches,
                count,
                false,
            )
            .await?;
            session.node_cursors[index] = page.cursor;
            session.node_complete[index] = page.cursor == 0;
            session.advance_after(index);
            keys.extend(page.keys);
            if !keys.is_empty() || page.cursor != 0 {
                break;
            }
        }
        Ok::<_, String>((keys, session.total_keys))
    }
    .await;
    match result {
        Ok((keys, total_keys)) => {
            let cursor = if session.is_complete() {
                0
            } else {
                sessions.lock().await.insert((cursor != 0).then_some(cursor), session)
            };
            Ok(RedisScanResult { cursor, keys, total_keys })
        }
        Err(error) => {
            if cursor != 0 {
                sessions.lock().await.insert(Some(cursor), retry);
            }
            Err(error)
        }
    }
}

pub async fn cluster_master_nodes(pool: &RedisClusterPool) -> Result<Vec<RedisNodeEndpoint>, String> {
    if !pool.seed_routes.is_empty() {
        return cluster_slot_ranges_from_routes(
            &pool.seed_routes,
            pool.tls,
            pool.tls_insecure,
            pool.tls_certificates.as_deref(),
            &pool.username,
            &pool.password,
        )
        .await
        .map(|slot_ranges| unique_master_nodes(&slot_ranges));
    }
    cluster_slot_ranges_from_seeds(
        &pool.seed_nodes,
        pool.tls,
        pool.tls_insecure,
        pool.tls_certificates.as_deref(),
        &pool.username,
        &pool.password,
    )
    .await
    .map(|slot_ranges| unique_master_nodes(&slot_ranges))
}

pub async fn flush_cluster(pool: &RedisClusterPool) -> Result<(), String> {
    flush_cluster_in_db(pool, 0).await
}

pub async fn flush_cluster_in_db(pool: &RedisClusterPool, db: u32) -> Result<(), String> {
    ensure_cluster_database(pool, db).await?;
    let master_nodes = cluster_master_nodes(pool).await?;
    for endpoint in master_nodes {
        let mut con = connect_cluster_node_in_db(pool, &endpoint, db).await?;
        flush_db(&mut con).await?;
    }
    Ok(())
}

async fn cluster_slot_ranges_from_seeds(
    seed_nodes: &[RedisNodeEndpoint],
    tls: bool,
    insecure: bool,
    certificates: Option<&redis::TlsCertificates>,
    username: &str,
    password: &str,
) -> Result<Vec<RedisClusterSlotRange>, String> {
    let seed_routes = identity_routes(seed_nodes);
    cluster_slot_ranges_from_routes(&seed_routes, tls, insecure, certificates, username, password).await
}

async fn cluster_slot_ranges_from_routes(
    seed_routes: &[RedisNodeRoute],
    tls: bool,
    insecure: bool,
    certificates: Option<&redis::TlsCertificates>,
    username: &str,
    password: &str,
) -> Result<Vec<RedisClusterSlotRange>, String> {
    let mut last_error = None;
    for route in seed_routes {
        let mut con = match connect_direct_node(&route.connect, tls, insecure, certificates, username, password).await {
            Ok(con) => con,
            Err(err) => {
                last_error = Some(err);
                continue;
            }
        };
        let raw: RedisRawValue = match redis::cmd("CLUSTER").arg("SLOTS").query_async(&mut con).await {
            Ok(raw) => raw,
            Err(err) => {
                last_error = Some(err.to_string());
                continue;
            }
        };
        let slot_ranges = parse_cluster_slots(raw, &route.advertised.host)?;
        if !slot_ranges.is_empty() {
            return Ok(slot_ranges);
        }
    }

    Err(last_error.unwrap_or_else(|| "Redis cluster master discovery failed".to_string()))
}

fn parse_cluster_slots(raw: RedisRawValue, fallback_host: &str) -> Result<Vec<RedisClusterSlotRange>, String> {
    let RedisRawValue::Array(slots) = raw else {
        return Err("Invalid Redis CLUSTER SLOTS response".to_string());
    };

    let mut slot_ranges = Vec::new();
    for slot in slots {
        let RedisRawValue::Array(parts) = slot else {
            continue;
        };
        if parts.len() < 3 {
            continue;
        }
        let Some(start_text) = redis_value_to_string(parts[0].clone()) else {
            return Err("Invalid Redis cluster slot start".to_string());
        };
        let Some(end_text) = redis_value_to_string(parts[1].clone()) else {
            return Err("Invalid Redis cluster slot end".to_string());
        };
        let start = parse_cluster_slot_number(&start_text)?;
        let end = parse_cluster_slot_number(&end_text)?;
        let Some(endpoint) = parse_cluster_slot_master(parts[2].clone(), fallback_host)? else {
            continue;
        };
        slot_ranges.push(RedisClusterSlotRange { start, end, master: endpoint });
    }
    Ok(slot_ranges)
}

fn parse_cluster_slot_master(value: RedisRawValue, fallback_host: &str) -> Result<Option<RedisNodeEndpoint>, String> {
    let RedisRawValue::Array(parts) = value else {
        return Ok(None);
    };
    if parts.len() < 2 {
        return Ok(None);
    }
    let host = match &parts[0] {
        RedisRawValue::Nil => fallback_host.to_string(),
        other => redis_value_to_string(other.clone()).unwrap_or_else(|| fallback_host.to_string()),
    };
    if host.trim().is_empty() {
        return Ok(None);
    }
    let Some(port_text) = redis_value_to_string(parts[1].clone()) else {
        return Err("Invalid Redis cluster node port".to_string());
    };
    let port = parse_redis_port(&port_text)?;
    Ok(Some(RedisNodeEndpoint { host, port }))
}

fn parse_cluster_slot_number(value: &str) -> Result<u16, String> {
    let slot = value.parse::<u16>().map_err(|_| format!("Invalid Redis cluster slot '{value}'"))?;
    if slot > 16_383 {
        return Err(format!("Invalid Redis cluster slot '{value}'"));
    }
    Ok(slot)
}

fn identity_routes(endpoints: &[RedisNodeEndpoint]) -> Vec<RedisNodeRoute> {
    endpoints
        .iter()
        .cloned()
        .map(|endpoint| RedisNodeRoute { advertised: endpoint.clone(), connect: endpoint })
        .collect()
}

pub fn unique_master_nodes(slot_ranges: &[RedisClusterSlotRange]) -> Vec<RedisNodeEndpoint> {
    let mut seen = std::collections::HashSet::new();
    let mut nodes = Vec::new();
    for slot_range in slot_ranges {
        if seen.insert((slot_range.master.host.clone(), slot_range.master.port)) {
            nodes.push(slot_range.master.clone());
        }
    }
    nodes
}

pub async fn cluster_any_connection(pool: &RedisClusterPool) -> Result<RedisClusterConnectionGuard<'_>, String> {
    cluster_any_connection_in_db(pool, 0).await
}

async fn native_cluster_database_connection(pool: &RedisClusterPool, db: u32) -> Result<ClusterConnection, String> {
    let entry = pool.database_connections.lock().await.entry(db).or_default().clone();
    let mut connection = entry.lock().await;
    if let Some(connection) = &*connection {
        return Ok(connection.clone());
    }
    let nodes = pool
        .seed_nodes
        .iter()
        .map(|endpoint| {
            connection_info(
                &endpoint.host,
                endpoint.port,
                pool.tls,
                pool.tls_insecure,
                &pool.username,
                &pool.password,
                i64::from(db),
            )
        })
        .collect::<Result<Vec<_>, _>>()?;
    let mut builder = ClusterClient::builder(nodes).database_id(i64::from(db));
    if let Some(certificates) = &pool.tls_certificates {
        builder = builder.certs((**certificates).clone());
    }
    let client = builder.build().map_err(|error| error.to_string())?;
    let initialized = tokio::time::timeout(connection_timeout(), client.get_async_connection())
        .await
        .map_err(|_| format!("Redis cluster db{db} connection timed out"))?
        .map_err(|error| format!("Redis cluster db{db} connection failed: {error}"))?;
    *connection = Some(initialized.clone());
    Ok(initialized)
}

pub async fn cluster_any_connection_in_db(
    pool: &RedisClusterPool,
    db: u32,
) -> Result<RedisClusterConnectionGuard<'_>, String> {
    ensure_cluster_database(pool, db).await?;
    if let Some(connection) = &pool.connection {
        if db != 0 {
            return native_cluster_database_connection(pool, db).await.map(RedisClusterConnectionGuard::Database);
        }
        return Ok(RedisClusterConnectionGuard::Native(connection.lock().await));
    }
    let endpoint = pool
        .node_routes
        .first()
        .or_else(|| pool.seed_routes.first())
        .map(|route| &route.advertised)
        .ok_or_else(|| "Redis cluster has no routable nodes".to_string())?;
    connect_cluster_node_in_db(pool, endpoint, db).await.map(RedisClusterConnectionGuard::Direct)
}

pub async fn cluster_key_connection<'a>(
    pool: &'a RedisClusterPool,
    key: &[u8],
) -> Result<RedisClusterConnectionGuard<'a>, String> {
    cluster_key_connection_in_db(pool, key, 0).await
}

pub async fn cluster_key_connection_in_db<'a>(
    pool: &'a RedisClusterPool,
    key: &[u8],
    db: u32,
) -> Result<RedisClusterConnectionGuard<'a>, String> {
    ensure_cluster_database(pool, db).await?;
    if let Some(connection) = &pool.connection {
        if db != 0 {
            return native_cluster_database_connection(pool, db).await.map(RedisClusterConnectionGuard::Database);
        }
        return Ok(RedisClusterConnectionGuard::Native(connection.lock().await));
    }
    let endpoint = cluster_master_for_key(pool, key)?;
    connect_cluster_node_in_db(pool, &endpoint, db).await.map(RedisClusterConnectionGuard::Direct)
}

pub async fn connect_cluster_node(
    pool: &RedisClusterPool,
    advertised_endpoint: &RedisNodeEndpoint,
) -> Result<redis::aio::MultiplexedConnection, String> {
    connect_cluster_node_in_db(pool, advertised_endpoint, 0).await
}

pub async fn connect_cluster_node_in_db(
    pool: &RedisClusterPool,
    advertised_endpoint: &RedisNodeEndpoint,
    db: u32,
) -> Result<redis::aio::MultiplexedConnection, String> {
    let client = build_redis_client(
        cluster_node_connection_info(pool, advertised_endpoint, db)?,
        pool.tls_certificates.as_deref(),
    )?;
    connect_client(client).await
}

fn cluster_node_connection_info(
    pool: &RedisClusterPool,
    advertised_endpoint: &RedisNodeEndpoint,
    db: u32,
) -> Result<ConnectionInfo, String> {
    let connect_endpoint = mapped_cluster_endpoint(pool, advertised_endpoint);
    connection_info(
        &connect_endpoint.host,
        connect_endpoint.port,
        pool.tls,
        pool.tls_insecure,
        &pool.username,
        &pool.password,
        i64::from(db),
    )
}

fn mapped_cluster_endpoint(pool: &RedisClusterPool, advertised_endpoint: &RedisNodeEndpoint) -> RedisNodeEndpoint {
    pool.node_routes
        .iter()
        .chain(pool.seed_routes.iter())
        .find(|route| route.advertised == *advertised_endpoint)
        .map(|route| route.connect.clone())
        .unwrap_or_else(|| advertised_endpoint.clone())
}

fn cluster_master_for_key(pool: &RedisClusterPool, key: &[u8]) -> Result<RedisNodeEndpoint, String> {
    let slot = redis_cluster_slot(key);
    pool.slot_ranges
        .iter()
        .find(|range| range.start <= slot && slot <= range.end)
        .map(|range| range.master.clone())
        .ok_or_else(|| format!("Redis cluster slot {slot} has no known master"))
}

fn redis_cluster_slot(key: &[u8]) -> u16 {
    let hashtag = key.iter().position(|byte| *byte == b'{').and_then(|start| {
        key[start + 1..].iter().position(|byte| *byte == b'}').and_then(|relative_end| {
            if relative_end == 0 {
                None
            } else {
                Some(&key[start + 1..start + 1 + relative_end])
            }
        })
    });
    crc16_xmodem(hashtag.unwrap_or(key)) % 16_384
}

fn crc16_xmodem(bytes: &[u8]) -> u16 {
    let mut crc = 0_u16;
    for byte in bytes {
        crc ^= (*byte as u16) << 8;
        for _ in 0..8 {
            if (crc & 0x8000) != 0 {
                crc = (crc << 1) ^ 0x1021;
            } else {
                crc <<= 1;
            }
        }
    }
    crc
}

pub fn parse_command_argv(command_text: &str) -> Result<Vec<Vec<u8>>, String> {
    // Strip trailing semicolons so commands like "HGETALL aaa;" work naturally
    let command_text = command_text.trim_end().trim_end_matches(';');
    let mut argv: Vec<Vec<u8>> = Vec::new();
    let mut current: Vec<u8> = Vec::new();
    let mut chars = command_text.chars().peekable();
    let mut quote: Option<char> = None;
    let mut escaping = false;
    let mut token_started = false;

    while let Some(ch) = chars.next() {
        if escaping {
            token_started = true;
            if ch == 'x' {
                let hex1 = chars.peek().copied();
                if let Some(h1) = hex1 {
                    if h1.is_ascii_hexdigit() {
                        chars.next();
                        let hex2 = chars.peek().copied();
                        if let Some(h2) = hex2 {
                            if h2.is_ascii_hexdigit() {
                                chars.next();
                                let byte = u8::from_str_radix(&format!("{h1}{h2}"), 16).unwrap();
                                current.push(byte);
                                escaping = false;
                                continue;
                            }
                        }
                    }
                }
                current.push(b'x');
            } else {
                let byte = match ch {
                    'n' => b'\n',
                    'r' => b'\r',
                    't' => b'\t',
                    'a' => b'\x07',
                    'b' => b'\x08',
                    'f' => b'\x0c',
                    'v' => b'\x0b',
                    '\\' => b'\\',
                    '"' => b'"',
                    '\'' => b'\'',
                    other => {
                        let mut buf = [0u8; 4];
                        let s = other.encode_utf8(&mut buf);
                        current.extend_from_slice(s.as_bytes());
                        escaping = false;
                        continue;
                    }
                };
                current.push(byte);
            }
            escaping = false;
            continue;
        }

        if ch == '\\' {
            token_started = true;
            escaping = true;
            continue;
        }

        if let Some(q) = quote {
            if ch == q {
                quote = None;
            } else {
                let mut buf = [0u8; 4];
                let s = ch.encode_utf8(&mut buf);
                current.extend_from_slice(s.as_bytes());
            }
            continue;
        }

        if ch == '"' || ch == '\'' {
            token_started = true;
            quote = Some(ch);
            continue;
        }

        if ch.is_whitespace() {
            if token_started {
                argv.push(std::mem::take(&mut current));
            }
            token_started = false;
            while matches!(chars.peek(), Some(next) if next.is_whitespace()) {
                chars.next();
            }
            continue;
        }

        token_started = true;
        let mut buf = [0u8; 4];
        let s = ch.encode_utf8(&mut buf);
        current.extend_from_slice(s.as_bytes());
    }

    if escaping {
        current.push(b'\\');
    }
    if quote.is_some() {
        return Err("Redis command has an unterminated quote".to_string());
    }
    if token_started {
        argv.push(current);
    }
    if argv.first().is_none_or(Vec::is_empty) {
        return Err("Redis command is empty".to_string());
    }
    Ok(argv)
}

pub fn parse_command_raw_argv(command_text: &str) -> Result<Vec<Vec<u8>>, String> {
    parse_command_argv(command_text)
}

pub fn parse_command_argv_strings(command_text: &str) -> Result<Vec<String>, String> {
    let raw = parse_command_argv(command_text)?;
    Ok(raw.into_iter().map(|b| String::from_utf8_lossy(&b).into_owned()).collect())
}

pub fn classify_command(command: &str) -> RedisCommandSafety {
    // Read access is an explicit allowlist. Commands added by a newer Redis
    // version, module, or proxy remain high-risk until DBX reviews them.
    match command.to_ascii_uppercase().as_str() {
        "BITCOUNT"
        | "BITFIELD_RO"
        | "BITPOS"
        | "COMMAND"
        | "DBSIZE"
        | "DUMP"
        | "ECHO"
        | "EXISTS"
        | "EXPIRETIME"
        | "GEODIST"
        | "GEOHASH"
        | "GEOPOS"
        | "GEORADIUS_RO"
        | "GEORADIUSBYMEMBER_RO"
        | "GEOSEARCH"
        | "GET"
        | "GETBIT"
        | "GETRANGE"
        | "HEXISTS"
        | "HGET"
        | "HGETALL"
        | "HKEYS"
        | "HLEN"
        | "HMGET"
        | "HRANDFIELD"
        | "HSCAN"
        | "HSTRLEN"
        | "HPTTL"
        | "HTTL"
        | "HVALS"
        | "INFO"
        | "LASTSAVE"
        | "LCS"
        | "LINDEX"
        | "LLEN"
        | "LPOS"
        | "LRANGE"
        | "MGET"
        | "OBJECT"
        | "PEXPIRETIME"
        | "PFCOUNT"
        | "PING"
        | "PTTL"
        | "PUBSUB"
        | "RANDOMKEY"
        | "ROLE"
        | "SCAN"
        | "SCARD"
        | "SDIFF"
        | "SINTER"
        | "SINTERCARD"
        | "SISMEMBER"
        | "SMEMBERS"
        | "SMISMEMBER"
        | "SORT_RO"
        | "SRANDMEMBER"
        | "SSCAN"
        | "STRLEN"
        | "SUNION"
        | "TIME"
        | "TTL"
        | "TYPE"
        | "WAIT"
        | "WAITAOF"
        | "XINFO"
        | "XLEN"
        | "XPENDING"
        | "XRANGE"
        | "XREAD"
        | "XREVRANGE"
        | "ZCARD"
        | "ZCOUNT"
        | "ZDIFF"
        | "ZINTER"
        | "ZINTERCARD"
        | "ZLEXCOUNT"
        | "ZMSCORE"
        | "ZRANDMEMBER"
        | "ZRANGE"
        | "ZRANGEBYLEX"
        | "ZRANGEBYSCORE"
        | "ZRANK"
        | "ZREVRANGE"
        | "ZREVRANGEBYLEX"
        | "ZREVRANGEBYSCORE"
        | "ZREVRANK"
        | "ZSCAN"
        | "ZSCORE"
        | "ZUNION"
        | "BF.CARD"
        | "BF.EXISTS"
        | "BF.INFO"
        | "BF.MEXISTS"
        | "CF.COUNT"
        | "CF.EXISTS"
        | "CF.INFO"
        | "CF.MEXISTS"
        | "CMS.INFO"
        | "CMS.QUERY"
        | "FT._LIST"
        | "FT.AGGREGATE"
        | "FT.DICTDUMP"
        | "FT.EXPLAIN"
        | "FT.EXPLAINCLI"
        | "FT.INFO"
        | "FT.PROFILE"
        | "FT.SEARCH"
        | "FT.SPELLCHECK"
        | "FT.SYNDUMP"
        | "FT.TAGVALS"
        | "GRAPH.RO_QUERY"
        | "JSON.ARRINDEX"
        | "JSON.ARRLEN"
        | "JSON.GET"
        | "JSON.MGET"
        | "JSON.OBJKEYS"
        | "JSON.OBJLEN"
        | "JSON.RESP"
        | "JSON.STRLEN"
        | "JSON.TYPE"
        | "TDIGEST.BYRANK"
        | "TDIGEST.BYREVRANK"
        | "TDIGEST.CDF"
        | "TDIGEST.INFO"
        | "TDIGEST.MAX"
        | "TDIGEST.MIN"
        | "TDIGEST.QUANTILE"
        | "TDIGEST.RANK"
        | "TDIGEST.REVRANK"
        | "TDIGEST.TRIMMED_MEAN"
        | "TOPK.INFO"
        | "TOPK.LIST"
        | "TOPK.QUERY"
        | "TS.GET"
        | "TS.INFO"
        | "TS.MGET"
        | "TS.MRANGE"
        | "TS.QUERYINDEX"
        | "TS.RANGE" => RedisCommandSafety::Allowed,
        "DEL" | "UNLINK" | "EXPIRE" | "EXPIREAT" | "PEXPIRE" | "PEXPIREAT" | "RENAME" | "RENAMENX" | "GETDEL"
        | "HDEL" | "HEXPIRE" | "HEXPIREAT" | "HPEXPIRE" | "HPEXPIREAT" | "HPERSIST" | "JSON.ARRPOP"
        | "JSON.ARRTRIM" | "JSON.CLEAR" | "JSON.DEL" | "JSON.FORGET" | "BLMOVE" | "BLMPOP" | "BLPOP" | "BRPOP"
        | "BRPOPLPUSH" | "LPOP" | "LMOVE" | "LMPOP" | "RPOP" | "RPOPLPUSH" | "LREM" | "LTRIM" | "SPOP" | "SREM"
        | "ZREM" | "ZPOPMAX" | "ZPOPMIN" | "ZMPOP" | "BZMPOP" | "BZPOPMAX" | "BZPOPMIN" | "ZREMRANGEBYLEX"
        | "ZREMRANGEBYRANK" | "ZREMRANGEBYSCORE" | "XDEL" | "XTRIM" | "MOVE" | "SORT" | "SDIFFSTORE"
        | "SINTERSTORE" | "SUNIONSTORE" | "ZDIFFSTORE" | "ZINTERSTORE" | "ZRANGESTORE" | "ZUNIONSTORE" | "PFMERGE"
        | "GEOSEARCHSTORE" => RedisCommandSafety::Confirm,
        "APPEND" | "BITFIELD" | "BITOP" | "COPY" | "DECR" | "DECRBY" | "GEOADD" | "GEORADIUS" | "GEORADIUSBYMEMBER"
        | "GETEX" | "GETSET" | "INCR" | "INCRBY" | "INCRBYFLOAT" | "SET" | "SETEX" | "PSETEX" | "SETNX"
        | "SETRANGE" | "MSET" | "MSETNX" | "PERSIST" | "HSET" | "HMSET" | "HINCRBY" | "HINCRBYFLOAT" | "HSETNX"
        | "JSON.ARRAPPEND" | "JSON.ARRINSERT" | "JSON.MERGE" | "JSON.MSET" | "JSON.NUMINCRBY" | "JSON.NUMMULTBY"
        | "JSON.SET" | "JSON.STRAPPEND" | "JSON.TOGGLE" | "LINSERT" | "LSET" | "LPUSH" | "LPUSHX" | "PFADD"
        | "RPUSH" | "RPUSHX" | "RESTORE" | "SADD" | "ZADD" | "ZINCRBY" | "SETBIT" | "SPUBLISH" | "PUBLISH"
        | "TOUCH" | "XADD" | "XACK" | "XAUTOCLAIM" | "XCLAIM" | "XREADGROUP" | "XSETID" => RedisCommandSafety::Write,
        _ => RedisCommandSafety::Blocked,
    }
}

pub fn redis_command_raw_to_json(value: RedisRawValue) -> serde_json::Value {
    match value {
        RedisRawValue::Nil => serde_json::Value::Null,
        RedisRawValue::Array(values) => {
            serde_json::Value::Array(values.into_iter().map(redis_command_raw_to_json).collect())
        }
        RedisRawValue::Map(values) => serde_json::Value::Array(
            values
                .into_iter()
                .map(|(key, value)| {
                    serde_json::json!({
                        "key": redis_command_raw_to_json(key),
                        "value": redis_command_raw_to_json(value),
                    })
                })
                .collect(),
        ),
        RedisRawValue::Set(values) => {
            serde_json::Value::Array(values.into_iter().map(redis_command_raw_to_json).collect())
        }
        RedisRawValue::Attribute { data, attributes } => serde_json::json!({
            "data": redis_command_raw_to_json(*data),
            "attributes": redis_command_raw_to_json(RedisRawValue::Map(attributes)),
        }),
        RedisRawValue::Push { kind, data } => serde_json::json!({
            "kind": format!("{kind:?}"),
            "data": redis_command_raw_to_json(RedisRawValue::Array(data)),
        }),
        RedisRawValue::BulkString(bytes) => {
            let text = redis_bytes_to_display(&bytes);
            let trimmed = text.trim();
            if trimmed.starts_with('{') || trimmed.starts_with('[') {
                if let Ok(json) = serde_json::from_str::<serde_json::Value>(trimmed) {
                    return json_value_for_js(json);
                }
            }
            serde_json::Value::String(text)
        }
        RedisRawValue::SimpleString(value) => serde_json::Value::String(value),
        RedisRawValue::Okay => serde_json::Value::String("OK".to_string()),
        RedisRawValue::Int(value) => safe_i64_to_json(value),
        RedisRawValue::Double(value) => {
            serde_json::Number::from_f64(value).map_or(serde_json::Value::Null, serde_json::Value::Number)
        }
        RedisRawValue::Boolean(value) => serde_json::Value::Bool(value),
        RedisRawValue::VerbatimString { text, .. } => {
            serde_json::Value::String(redis_bytes_to_display(text.as_bytes()))
        }
        RedisRawValue::BigNumber(value) => serde_json::Value::String(value.to_string()),
        RedisRawValue::ServerError(error) => serde_json::Value::String(format!("{error:?}")),
        value => serde_json::Value::String(format!("{value:?}")),
    }
}

pub fn is_redis_json_type(key_type: &str) -> bool {
    matches!(key_type.to_ascii_uppercase().as_str(), "REJSON-RL" | "JSON")
}

pub fn redis_json_raw_to_text(value: RedisRawValue) -> Result<String, String> {
    match value {
        RedisRawValue::BulkString(bytes) => {
            String::from_utf8(bytes).map_err(|e| format!("RedisJSON value is not valid UTF-8: {e}"))
        }
        RedisRawValue::SimpleString(text) => Ok(text),
        RedisRawValue::VerbatimString { text, .. } => Ok(text),
        // Do not turn a key deleted between TYPE and JSON.GET into an editable
        // JSON null; saving that draft would recreate a phantom key.
        RedisRawValue::Nil => Err("RedisJSON key no longer exists".to_string()),
        other => Err(format!("Unexpected RedisJSON response: {other:?}")),
    }
}

pub fn redis_key_value_preview(key_type: &str) -> String {
    if is_redis_json_type(key_type) {
        "{...}".to_string()
    } else {
        String::new()
    }
}

pub async fn flush_db<C>(con: &mut C) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("FLUSHDB").query_async::<()>(con).await.map_err(|e| e.to_string())
}

/// Retrieve slowlog entries via `SLOWLOG GET <count>`.
/// The response is a nested array where each entry has the structure:
///   [id, timestamp_unix_secs, duration_micros, [arg1, arg2, ...], client_addr, client_name, ...]
pub async fn get_slowlog<C>(con: &mut C, count: usize) -> Result<Vec<RedisSlowlogEntry>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let raw: RedisRawValue = redis::cmd("SLOWLOG")
        .arg("GET")
        .arg(count as u64)
        .query_async(con)
        .await
        .map_err(|e| format!("SLOWLOG GET failed: {e}"))?;

    let RedisRawValue::Array(entries) = raw else {
        return Err("SLOWLOG GET returned non-array response".to_string());
    };

    let mut result = Vec::with_capacity(entries.len());
    for entry in entries {
        let RedisRawValue::Array(fields) = entry else {
            continue;
        };
        if fields.len() < 4 {
            continue;
        }

        let id = redis_value_to_u64(&fields[0]).unwrap_or(0);
        let timestamp = fields[1].clone();
        let duration = fields[2].clone();
        let args_raw = fields[3].clone();
        let client_addr = if fields.len() > 4 { redis_raw_value_to_optional_string(&fields[4]) } else { None };
        let client_name = if fields.len() > 5 { redis_raw_value_to_optional_string(&fields[5]) } else { None };

        let command = match args_raw {
            RedisRawValue::Array(args) => {
                let mut parts = Vec::with_capacity(args.len());
                for arg in args {
                    if let Some(s) = redis_raw_value_to_command_arg(&arg) {
                        parts.push(s);
                    }
                }
                parts.join(" ")
            }
            _ => String::new(),
        };

        let timestamp_secs = match timestamp {
            RedisRawValue::Int(i) => i,
            RedisRawValue::BulkString(ref bytes) => {
                std::str::from_utf8(bytes).ok().and_then(|s| s.parse::<i64>().ok()).unwrap_or(0)
            }
            _ => 0,
        };

        let duration_micros = match duration {
            RedisRawValue::Int(i) => i as u64,
            RedisRawValue::BulkString(ref bytes) => {
                std::str::from_utf8(bytes).ok().and_then(|s| s.parse::<u64>().ok()).unwrap_or(0)
            }
            _ => 0,
        };

        result.push(RedisSlowlogEntry {
            id,
            timestamp: timestamp_secs,
            duration_micros,
            command,
            client_addr,
            client_name,
        });
    }

    Ok(result)
}

/// Try to convert a RedisRawValue to an optional string (None for Nil).
fn redis_raw_value_to_optional_string(v: &RedisRawValue) -> Option<String> {
    match v {
        RedisRawValue::BulkString(bytes) => {
            if bytes.is_empty() {
                None
            } else {
                std::str::from_utf8(bytes).ok().map(|s| s.to_string())
            }
        }
        RedisRawValue::SimpleString(s) => Some(s.clone()),
        RedisRawValue::Nil => None,
        _ => None,
    }
}

/// Convert a RedisRawValue to an command argument string.
/// Unlike `redis_raw_value_to_optional_string`, this preserves empty strings
/// and uses `redis_bytes_to_display` to handle non-UTF-8 binary data.
fn redis_raw_value_to_command_arg(v: &RedisRawValue) -> Option<String> {
    match v {
        RedisRawValue::BulkString(bytes) => Some(redis_bytes_to_display(bytes)),
        RedisRawValue::SimpleString(s) => Some(s.clone()),
        RedisRawValue::Nil => None,
        _ => None,
    }
}

/// Try to convert a RedisRawValue to a u64.
fn redis_value_to_u64(v: &RedisRawValue) -> Option<u64> {
    match v {
        RedisRawValue::Int(i) => u64::try_from(*i).ok(),
        RedisRawValue::BulkString(bytes) => std::str::from_utf8(bytes).ok().and_then(|s| s.parse().ok()),
        RedisRawValue::SimpleString(value) => value.parse().ok(),
        _ => None,
    }
}

/// Extract a string reference from a `RedisRawValue` if it is a BulkString or SimpleString.
fn redis_raw_value_as_str(v: &RedisRawValue) -> Option<&str> {
    match v {
        RedisRawValue::BulkString(bytes) => std::str::from_utf8(bytes).ok(),
        RedisRawValue::SimpleString(s) => Some(s.as_str()),
        _ => None,
    }
}

pub async fn execute_command<C>(
    con: &mut C,
    command_text: &str,
    skip_safety_check: bool,
) -> Result<RedisCommandResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let argv = parse_command_argv(command_text)?;
    let command = String::from_utf8_lossy(&argv[0]).to_ascii_uppercase();
    if command == "MONITOR" {
        return Err(
            "MONITOR requires a dedicated streaming connection; run MONITOR alone in the query editor".to_string()
        );
    }
    let safety = classify_command(&command);
    if !skip_safety_check && safety == RedisCommandSafety::Blocked {
        return Err(format!("Redis command is blocked for safety: {command}"));
    }

    let mut cmd = redis::cmd(&command);
    for arg in argv.iter().skip(1) {
        cmd.arg(arg.as_slice());
    }
    let raw: RedisRawValue = cmd.query_async(con).await.map_err(|e| e.to_string())?;

    // Special handling for INFO command in cluster mode.
    // redis-rs ClusterConnection routes INFO to all primaries and
    // aggregates the results as a Map(node_addr → full_info_text).

    // We detect this pattern and return it as an array of
    // [node_addr, info_text] pairs, which the frontend renders
    // as a two-column (index → node_addr, value → info_text) table.
    if command == "INFO" {
        if let RedisRawValue::Map(entries) = &raw {
            // Cluster-aggregated INFO has multi-line values starting with "# "
            // (e.g. "# Server", "# Memory", "# Clients").
            // This distinguishes it from a RESP3 standalone INFO map where values
            // are single field values (e.g. "redis_version", "os") or nested maps.
            let is_cluster_aggregation =
                entries.iter().any(|(_, v)| redis_raw_value_as_str(v).is_some_and(|s| s.starts_with("# ")));

            if is_cluster_aggregation {
                let pairs: Vec<serde_json::Value> = entries
                    .iter()
                    .filter_map(|(key, value)| {
                        let addr = redis_raw_value_as_str(key)?;
                        let info = redis_raw_value_as_str(value)?;
                        Some(serde_json::json!([addr, info]))
                    })
                    .collect();
                return Ok(RedisCommandResult { command, safety, value: serde_json::Value::Array(pairs) });
            }
        }
    }

    Ok(RedisCommandResult { command, safety, value: redis_command_raw_to_json(raw) })
}

pub async fn scan_keys_page<C>(con: &mut C, cursor: u64, pattern: &str, count: usize) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    scan_keys_batch(con, cursor, pattern, count, 1, true).await
}

pub async fn scan_keys_page_with_options<C>(
    con: &mut C,
    cursor: u64,
    pattern: &str,
    count: usize,
    include_types: bool,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    scan_keys_batch(con, cursor, pattern, count, 1, include_types).await
}

/// Batch-scan keys with server-side multi-SCAN support.
///
/// Performs up to `max_iterations` SCAN cycles in a single call. TYPE and TTL
/// metadata is optional so large key-name searches can avoid extra Redis work.
/// DBSIZE is only called on the first iteration (cursor == 0).
pub async fn scan_keys_batch<C>(
    con: &mut C,
    cursor: u64,
    pattern: &str,
    count: usize,
    max_iterations: usize,
    include_types: bool,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    scan_keys_batch_inner(con, cursor, pattern, count, max_iterations, include_types, true).await
}

/// Reads the type and the TTL of one chunk of keys with a single packed pipeline.
///
/// The pipeline interleaves TYPE and TTL, so one round trip carries at most
/// `2 * keys.len()` commands and every answer keeps the key's position.
/// A reply that cannot be parsed becomes ("unknown", -2): the key stays
/// listed, its badge simply stays unknown.
async fn read_type_and_ttl_chunk<C>(con: &mut C, keys: &[Vec<u8>]) -> Result<Vec<(String, i64)>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut pipeline = redis::pipe();
    for key in keys {
        pipeline.cmd("TYPE").arg(key);
        pipeline.cmd("TTL").arg(key);
    }
    let count = pipeline.len();
    let replies = con.req_packed_commands(&pipeline, 0, count).await.map_err(|error| error.to_string())?;
    if replies.len() != count {
        return Err("Redis did not return one TYPE and one TTL reply per key".to_string());
    }

    let mut metadata = Vec::with_capacity(keys.len());
    for index in 0..keys.len() {
        let key_type =
            String::from_redis_value(replies[index * 2].clone()).ok().unwrap_or_else(|| "unknown".to_string());
        let ttl = i64::from_redis_value(replies[index * 2 + 1].clone()).ok().unwrap_or(-2);
        metadata.push((key_type, ttl));
    }
    Ok(metadata)
}

/// Reads the types of one chunk of keys with a single packed pipeline.
///
/// The types are worth a round trip of their own when the combined TYPE/TTL
/// pipeline failed as a whole: one refused command (an ACL without the TTL
/// permission, for example) must not cost the whole chunk its badges.
async fn read_types_chunk<C>(con: &mut C, keys: &[Vec<u8>]) -> Vec<String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut pipeline = redis::pipe();
    for key in keys {
        pipeline.cmd("TYPE").arg(key);
    }
    let count = pipeline.len();
    let replies = match con.req_packed_commands(&pipeline, 0, count).await {
        Ok(replies) => replies,
        Err(_) => return vec!["unknown".to_string(); keys.len()],
    };
    (0..keys.len())
        .map(|index| {
            replies
                .get(index)
                .and_then(|value| String::from_redis_value(value.clone()).ok())
                .unwrap_or_else(|| "unknown".to_string())
        })
        .collect()
}

/// Reads TYPE and TTL for a batch of named keys.
///
/// This is the metadata half of `scan_keys_batch` (one packed pipeline that
/// interleaves TYPE and TTL per key) addressed by key name instead of by scan
/// cursor, so the key browser can fill the badges of rows it already listed
/// without scanning the keyspace again. A key that disappeared meanwhile
/// answers `TYPE` = "none" and `TTL` = -2.
///
/// The batch is split into chunks of `SCAN_METADATA_PIPELINE_CHUNK` keys, so
/// one round trip never carries more than `2 * SCAN_METADATA_PIPELINE_CHUNK`
/// commands. A transport error fails the whole batch; a reply that cannot be
/// parsed becomes ("unknown", -2) instead of an empty type.
pub async fn key_metadata_batch<C>(con: &mut C, keys: &[Vec<u8>]) -> Result<Vec<RedisKeyMetadata>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    if keys.is_empty() {
        return Ok(Vec::new());
    }

    let mut result = Vec::with_capacity(keys.len());
    for chunk in keys.chunks(SCAN_METADATA_PIPELINE_CHUNK) {
        let chunk_metadata = read_type_and_ttl_chunk(con, chunk).await?;
        for (key, (key_type, ttl)) in chunk.iter().zip(chunk_metadata) {
            result.push(RedisKeyMetadata { key_raw: redis_key_bytes_to_raw(key), key_type, ttl });
        }
    }
    Ok(result)
}

async fn scan_keys_batch_inner<C>(
    con: &mut C,
    cursor: u64,
    pattern: &str,
    count: usize,
    max_iterations: usize,
    include_types: bool,
    include_total_keys: bool,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let iterations = max_iterations.max(1);
    let total_keys: u64 =
        if include_total_keys && cursor == 0 { redis::cmd("DBSIZE").query_async(con).await.unwrap_or(0) } else { 0 };

    let is_exact_match = !pattern.contains('*') && !pattern.contains('?') && !pattern.contains('[');
    if cursor == 0 && is_exact_match && !pattern.is_empty() {
        match redis::cmd("EXISTS").arg(pattern).query_async::<bool>(con).await {
            Ok(true) => {
                let key_type: String = if include_types {
                    redis::cmd("TYPE").arg(pattern).query_async(con).await.unwrap_or_else(|_| "unknown".to_string())
                } else {
                    String::new()
                };
                // 精确命中单个 key 时顺带查询一次 TTL(O(1) 命令),
                // 让前端列表行无需再点开 key 就能看到过期信息。
                let key_ttl: i64 = if include_types {
                    redis::cmd("TTL").arg(pattern).query_async(con).await.unwrap_or(-2)
                } else {
                    -2
                };

                let value_preview = if include_types { redis_key_value_preview(&key_type) } else { String::new() };

                let key_info = RedisKeyInfo {
                    key_display: redis_key_bytes_to_display(pattern.as_bytes()),
                    key_raw: redis_key_bytes_to_raw(pattern.as_bytes()),
                    key_type,
                    ttl: key_ttl,
                    size: 0,
                    value_preview,
                };
                return Ok(RedisScanResult { cursor: 0, keys: vec![key_info], total_keys });
            }
            Ok(false) => {
                return Ok(RedisScanResult { cursor: 0, keys: vec![], total_keys });
            }
            Err(_) => {}
        }
    }

    let mut all_keys: Vec<RedisKeyInfo> = Vec::new();

    let mut current_cursor = cursor;

    for iteration in 0..iterations {
        let raw: RedisRawValue = redis::cmd("SCAN")
            .arg(current_cursor)
            .arg("MATCH")
            .arg(pattern)
            .arg("COUNT")
            .arg(count)
            .query_async(con)
            .await
            .map_err(|e| e.to_string())?;

        let (next_cursor, keys) = parse_scan_keys(raw)?;

        if !keys.is_empty() {
            let (key_types, key_ttls): (Vec<String>, Vec<i64>) = if include_types {
                let mut key_types: Vec<String> = Vec::with_capacity(keys.len());
                let mut key_ttls: Vec<i64> = Vec::with_capacity(keys.len());
                // One packed pipeline per chunk keeps a single round trip bounded.
                // The whole batch would otherwise ask the server for tens of
                // thousands of TYPE and TTL commands at once, and Redis answers
                // them one after another on its single thread — every other
                // client of that instance waits for the whole batch.
                for chunk in keys.chunks(SCAN_METADATA_PIPELINE_CHUNK) {
                    match read_type_and_ttl_chunk(con, chunk).await {
                        Ok(chunk_metadata) => {
                            for (key_type, ttl) in chunk_metadata {
                                key_types.push(key_type);
                                key_ttls.push(ttl);
                            }
                        }
                        // Best effort: a chunk whose metadata cannot be read
                        // keeps its keys listed with an unknown badge instead
                        // of failing the whole scan. The types are asked for
                        // on their own, because a single refused command must
                        // not take the badges of the whole chunk with it.
                        Err(_) => {
                            for key_type in read_types_chunk(con, chunk).await {
                                key_types.push(key_type);
                                key_ttls.push(-2);
                            }
                        }
                    }
                }
                (key_types, key_ttls)
            } else {
                (Vec::new(), Vec::new())
            };

            for (index, key) in keys.iter().enumerate() {
                let key_type = if include_types {
                    key_types.get(index).cloned().unwrap_or_else(|| "unknown".to_string())
                } else {
                    String::new()
                };
                let value_preview = if include_types {
                    redis_key_value_preview(key_types.get(index).map(String::as_str).unwrap_or("unknown"))
                } else {
                    String::new()
                };
                all_keys.push(RedisKeyInfo {
                    key_display: redis_key_bytes_to_display(key),
                    key_raw: redis_key_bytes_to_raw(key),
                    key_type,
                    ttl: key_ttls.get(index).copied().unwrap_or(-2),
                    size: 0,
                    value_preview,
                });
            }
        }

        if next_cursor == 0 {
            return Ok(RedisScanResult { cursor: 0, keys: all_keys, total_keys });
        }
        current_cursor = next_cursor;

        // MATCH may yield sparse or empty batches. Keep scanning within the
        // caller's bounded budget, but stop once this result page is full.
        if !should_continue_key_scan(all_keys.len(), count, iteration + 1, iterations) {
            break;
        }
    }

    Ok(RedisScanResult { cursor: current_cursor, keys: all_keys, total_keys })
}

fn should_continue_key_scan(
    matched_keys: usize,
    target_keys: usize,
    completed_iterations: usize,
    max_iterations: usize,
) -> bool {
    matched_keys < target_keys.max(1) && completed_iterations < max_iterations.max(1)
}

pub async fn scan_values_page<C>(
    con: &mut C,
    cursor: u64,
    pattern: &str,
    query: &str,
    include_key_matches: bool,
    count: usize,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    scan_values_page_inner(con, cursor, pattern, query, include_key_matches, count, true).await
}

async fn scan_values_page_inner<C>(
    con: &mut C,
    cursor: u64,
    pattern: &str,
    query: &str,
    include_key_matches: bool,
    count: usize,
    include_total_keys: bool,
) -> Result<RedisScanResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    // Only call DBSIZE on the first page (cursor == 0) to avoid redundant work.
    let total_keys: u64 =
        if include_total_keys && cursor == 0 { redis::cmd("DBSIZE").query_async(con).await.unwrap_or(0) } else { 0 };
    if query.trim().is_empty() {
        return Ok(RedisScanResult { cursor, keys: Vec::new(), total_keys });
    }

    let scan_count = count.max(1);
    let raw: RedisRawValue = redis::cmd("SCAN")
        .arg(cursor)
        .arg("MATCH")
        .arg(pattern)
        .arg("COUNT")
        .arg(scan_count)
        .query_async(con)
        .await
        .map_err(|e| e.to_string())?;

    let (next_cursor, keys) = parse_scan_keys(raw)?;
    let mut result = Vec::new();
    let keys: Vec<_> = keys
        .into_iter()
        .map(|key| {
            let key_display = redis_key_bytes_to_display(&key);
            let key_raw = redis_key_bytes_to_raw(&key);
            let key_matches = include_key_matches && redis_key_matches_query(&key_display, &key_raw, query);
            (key, key_display, key_raw, key_matches)
        })
        .collect();

    let mut key_match_types = Vec::new();
    if include_key_matches {
        let mut pipe = redis::pipe();
        let mut key_match_count = 0usize;
        for (key, _, _, key_matches) in &keys {
            if *key_matches {
                pipe.cmd("TYPE").arg(key);
                key_match_count += 1;
            }
        }
        if key_match_count > 0 {
            key_match_types = pipe.query_async(con).await.unwrap_or_default();
        }
    }

    let mut key_match_type_index = 0usize;
    for (key, key_display, key_raw, key_matches) in keys {
        if key_matches {
            let key_type = key_match_types.get(key_match_type_index).cloned().unwrap_or_else(|| "unknown".to_string());
            key_match_type_index += 1;
            result.push(RedisKeyInfo {
                key_display,
                key_raw,
                value_preview: redis_key_value_preview(&key_type),
                key_type,
                ttl: -2,
                size: 0,
            });
            continue;
        }

        let Ok(value) = get_value(con, &key).await else {
            continue;
        };
        if !redis_value_matches_query(&value, query) {
            continue;
        }

        let value_preview = redis_search_value_preview(&value.data);
        let size = redis_search_value_size(&value);
        result.push(RedisKeyInfo {
            key_display: value.key_display,
            key_raw: value.key_raw,
            key_type: value.redis_type,
            ttl: value.ttl,
            size,
            value_preview,
        });
    }

    Ok(RedisScanResult { cursor: next_cursor, keys: result, total_keys })
}

pub async fn get_value<C>(con: &mut C, key: &[u8]) -> Result<RedisValue, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    get_value_scoped(con, key, &RedisOperationScope::default()).await
}

pub async fn get_value_scoped<C>(con: &mut C, key: &[u8], scope: &RedisOperationScope) -> Result<RedisValue, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    get_value_scoped_with_preview_limit(con, key, scope, STRING_PREVIEW_MAX_BYTES).await
}

pub async fn get_value_scoped_with_preview_limit<C>(
    con: &mut C,
    key: &[u8],
    scope: &RedisOperationScope,
    preview_limit_bytes: usize,
) -> Result<RedisValue, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    validate_value_preview_limit(preview_limit_bytes)?;
    let redis_type: String = redis::cmd("TYPE").arg(key).query_async(con).await.map_err(|e| e.to_string())?;

    // For Streams, fetch metadata and the initial page together after TYPE.
    // This keeps the accurate XLEN without adding another Redis round trip.
    let stream_initial_page =
        if redis_type == "stream" { Some(get_stream_initial_page(con, key).await?) } else { None };
    let ttl: i64 = match stream_initial_page.as_ref() {
        Some((ttl, _, _)) => *ttl,
        None => redis::cmd("TTL").arg(key).query_async(con).await.unwrap_or(-1),
    };

    let data = match redis_type.as_str() {
        "string" => {
            let (bytes, total_bytes, truncated) = read_string_preview(con, key, preview_limit_bytes).await?;
            RedisValueData::String { content: redis_blob_from_bytes(&bytes), total_bytes, truncated }
        }
        "list" => {
            let len: u64 = redis::cmd("LLEN").arg(key).query_async(con).await.unwrap_or(0);
            let end = (COLLECTION_PAGE_SIZE as i64) - 1;
            let v: RedisRawValue =
                redis::cmd("LRANGE").arg(key).arg(0).arg(end).query_async(con).await.map_err(|e| e.to_string())?;
            let mut items = redis_list_items_from_raw(v, 0);
            items.truncate(budgeted_page_len(&items, COLLECTION_PAGE_SIZE, list_item_page_bytes));
            let next = items.len() as u64;
            RedisValueData::List { items, total: len, scan_cursor: (next < len).then_some(next) }
        }
        "set" => {
            let len: u64 = redis::cmd("SCARD").arg(key).query_async(con).await.unwrap_or(0);
            let (cursor, items) = sscan_bounded_page(con, scope, key, 0, COLLECTION_PAGE_SIZE, None).await?;
            RedisValueData::Set { items, total: len, scan_cursor: (cursor > 0).then_some(cursor) }
        }
        "zset" => {
            let len: u64 = redis::cmd("ZCARD").arg(key).query_async(con).await.unwrap_or(0);
            let end = (COLLECTION_PAGE_SIZE as i64) - 1;
            let mut items = zrange_page_raw(con, key, 0, end, false).await?;
            items.truncate(budgeted_page_len(&items, COLLECTION_PAGE_SIZE, zset_item_page_bytes));
            let next = items.len() as u64;
            RedisValueData::Zset { items, total: len, scan_cursor: (next < len).then_some(next) }
        }
        "hash" => {
            let len: u64 = redis::cmd("HLEN").arg(key).query_async(con).await.unwrap_or(0);
            let (cursor, mut items) = hscan_bounded_page(con, scope, key, 0, COLLECTION_PAGE_SIZE, None).await?;
            attach_hash_field_ttls(con, key, &mut items).await?;
            RedisValueData::Hash { items, total: len, scan_cursor: (cursor > 0).then_some(cursor) }
        }
        "stream" => {
            let (_, total, page) = stream_initial_page.expect("Stream page is loaded with its Stream type");
            RedisValueData::Stream { entries: page.entries, total, next_cursor: page.next_cursor }
        }
        key_type if is_redis_json_type(key_type) => {
            let raw: RedisRawValue =
                redis::cmd("JSON.GET").arg(key).query_async(con).await.map_err(|e| e.to_string())?;
            RedisValueData::Json { value: redis_json_raw_to_text(raw)? }
        }
        // kvrocks 的位图/HLL 是独立类型,标准 Redis 类型表里没有它们;不处理就会落到
        // Unknown,界面上表现为“能看到 Key、看不到值”(issue #10406)。
        "bitmap" => {
            // kvrocks 对位图类型只开放 GET(GETRANGE/STRLEN 会报 WRONGTYPE),
            // 且 GET 返回的字节与 Redis 位序一致,可直接按字符串预览。
            let raw: RedisRawValue = redis::cmd("GET").arg(key).query_async(con).await.map_err(|e| e.to_string())?;
            let mut bytes = redis_value_to_bytes(raw).unwrap_or_default();
            let truncated = bytes.len() > preview_limit_bytes;
            if truncated {
                bytes.truncate(preview_limit_bytes);
            }
            // 截断后拿不到准确长度(kvrocks 位图没有可用的 STRLEN),置空交给前端按未知处理
            let total_bytes = (!truncated).then_some(bytes.len() as u64);
            let set_bits: Option<u64> = redis::cmd("BITCOUNT").arg(key).query_async(con).await.ok();
            RedisValueData::Bitmap { content: redis_blob_from_bytes(&bytes), total_bytes, truncated, set_bits }
        }
        "hyperloglog" => {
            // HLL 原始字节不可读,基数估计是唯一可展示的数据
            let count: Option<u64> = redis::cmd("PFCOUNT").arg(key).query_async(con).await.ok();
            RedisValueData::HyperLogLog { count }
        }
        _ => RedisValueData::Unknown { redis_type: redis_type.clone() },
    };

    Ok(RedisValue {
        key_display: redis_key_bytes_to_display(key),
        key_raw: redis_key_bytes_to_raw(key),
        redis_type,
        ttl,
        data,
    })
}

/// Read the preview window of a Redis string value.
///
/// `GETRANGE` is used instead of `GET` so a large value is never pulled over
/// the wire in full. The window is requested optimistically first, the way
/// Redis clamps it to the value length, so reading a value stays a single
/// round trip for the servers that clamp.
///
/// Strict servers reject a window that reaches past the value instead of
/// clamping it: TongRDS answers `ERR 0-65536 is out of bounds` and the read
/// failed, which left the key detail empty for every string shorter than the
/// preview window (issue #13114). Such a rejection is answered with the exact
/// value length, and the windows are then requested inside it.
async fn read_string_preview<C>(
    con: &mut C,
    key: &[u8],
    preview_limit_bytes: usize,
) -> Result<(Vec<u8>, Option<u64>, bool), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    match read_string_windows(con, key, preview_limit_bytes, None).await {
        Ok(result) => Ok(result),
        Err(error) if !is_redis_out_of_bounds_error(&error) => Err(error),
        // The server refuses to clamp the window, so the value length
        // decides where a window may end.
        Err(rejected) => read_string_preview_by_length(con, key, preview_limit_bytes, rejected).await,
    }
}

/// Read a Redis string in windows that never reach past the value.
///
/// `rejected` is the error the optimistic window produced. The value length
/// decides where a window may end, so the same rejection cannot come back —
/// unless the value shrinks between the length read and the window read,
/// which is retried against the fresh length.
///
/// Without a length there is no bounded window to fall back to, and asking
/// for the rejected window again would only repeat the same failure.
async fn read_string_preview_by_length<C>(
    con: &mut C,
    key: &[u8],
    preview_limit_bytes: usize,
    rejected: String,
) -> Result<(Vec<u8>, Option<u64>, bool), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let known_length = match redis_string_length(con, key).await {
        Ok(length) => length,
        // The fallback needs the length, and the reason it is missing belongs
        // in the error: the rejection alone does not say that STRLEN was denied.
        Err(error) => return Err(format!("{rejected} (the value length could not be read: {error})")),
    };
    match read_string_windows(con, key, preview_limit_bytes, Some(known_length)).await {
        Ok(result) => Ok(result),
        Err(error) if is_redis_out_of_bounds_error(&error) => {
            // The value shrank between the length read and the window read.
            let fresh_length = match redis_string_length(con, key).await {
                Ok(length) => length,
                Err(strlen_error) => {
                    return Err(format!("{error} (the value length could not be read: {strlen_error})"))
                }
            };
            read_string_windows(con, key, preview_limit_bytes, Some(fresh_length)).await
        }
        Err(error) => Err(error),
    }
}

/// Read a Redis string in windows.
///
/// `known_length` is the value length reported by `STRLEN`; with it a window
/// never reaches past the value. Without it the window is requested
/// optimistically, the way Redis clamps it, and a short read ends the value.
async fn read_string_windows<C>(
    con: &mut C,
    key: &[u8],
    preview_limit_bytes: usize,
    known_length: Option<u64>,
) -> Result<(Vec<u8>, Option<u64>, bool), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let limit = preview_limit_bytes as u64;
    let mut bytes: Vec<u8> = Vec::new();
    let mut at_budget = false;
    while (bytes.len() as u64) < limit {
        // Windows stay at most `STRING_PREVIEW_MAX_BYTES` wide so a large
        // configured budget is fetched in chunks (issue #11792).
        let span = match known_length {
            Some(total) => {
                let remaining = total.saturating_sub(bytes.len() as u64);
                if remaining == 0 {
                    break;
                }
                remaining.min(limit - bytes.len() as u64).min(STRING_PREVIEW_MAX_BYTES as u64)
            }
            None => (limit - bytes.len() as u64).min(STRING_PREVIEW_MAX_BYTES as u64),
        };
        let start = bytes.len() as i64;
        let chunk: RedisRawValue = redis::cmd("GETRANGE")
            .arg(key)
            .arg(start)
            .arg(start + span as i64 - 1)
            .query_async(con)
            .await
            .map_err(|e| e.to_string())?;
        let chunk =
            redis_value_to_bytes(chunk).ok_or_else(|| "Redis string payload is not byte-addressable".to_string())?;
        let chunk_len = chunk.len() as u64;
        bytes.extend_from_slice(&chunk);
        if chunk_len < span {
            // The value ended before the window did.
            break;
        }
        if (bytes.len() as u64) >= limit {
            at_budget = true;
            break;
        }
    }
    let total_bytes = match known_length {
        Some(total) => Some(total),
        // The budget was filled exactly, so the value may continue — STRLEN
        // settles that without materializing the rest in the backend or IPC
        // layer. A server that denies STRLEN only leaves the size unknown.
        None if at_budget => redis_string_length(con, key).await.ok(),
        None => Some(bytes.len() as u64),
    };
    let truncated = total_bytes.map_or(at_budget, |total| total > limit);
    if truncated {
        bytes.truncate(preview_limit_bytes);
    }
    Ok((bytes, total_bytes, truncated))
}

/// Read the length of a Redis string value.
async fn redis_string_length<C>(con: &mut C, key: &[u8]) -> Result<u64, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let length: i64 = redis::cmd("STRLEN").arg(key).query_async(con).await.map_err(|e| e.to_string())?;
    u64::try_from(length).map_err(|_| "Redis string length is negative".to_string())
}

/// Whether a server rejected a range because it reached past the value.
///
/// TongRDS answers `ERR 0-65536 is out of bounds`; Redis never rejects a
/// range for that reason.
fn is_redis_out_of_bounds_error(error: &str) -> bool {
    error.contains("out of bounds")
}

/// Read the complete raw payload for a Redis string-like key.
///
/// The normal value path caps previews at the configured size. Downloads must
/// bypass that cap while preserving the exact bytes, including non-UTF-8 data.
pub async fn get_raw_value<C>(con: &mut C, key: &[u8]) -> Result<RedisBlob, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let redis_type: String = redis::cmd("TYPE").arg(key).query_async(con).await.map_err(|e| e.to_string())?;
    let raw: RedisRawValue = match redis_type.as_str() {
        "string" | "bitmap" => redis::cmd("GET").arg(key).query_async(con).await.map_err(|e| e.to_string())?,
        "none" => return Err("Redis key does not exist".to_string()),
        _ => return Err("Only Redis string values can be downloaded".to_string()),
    };
    let bytes = redis_value_to_bytes(raw).ok_or_else(|| "Redis value is not byte-addressable".to_string())?;
    Ok(redis_blob_from_bytes(&bytes))
}

/// Read only a key's TTL without loading its value or collection members.
///
/// Redis returns `-2` for a missing key and `-1` for a key without an expiry;
/// callers preserve those sentinel values so the UI can update its detail view
/// without an additional round trip.
pub async fn get_ttl<C>(con: &mut C, key: &[u8]) -> Result<i64, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("TTL").arg(key).query_async(con).await.map_err(|e| e.to_string())
}

fn redis_value_matches_query(value: &RedisValue, query: &str) -> bool {
    let query = query.trim();
    if query.is_empty() {
        return false;
    }
    redis_search_value_text(&value.data).to_lowercase().contains(&query.to_lowercase())
}

fn redis_key_matches_query(key_display: &str, key_raw: &str, query: &str) -> bool {
    let query = query.trim();
    if query.is_empty() {
        return false;
    }
    let query = query.to_lowercase();
    key_display.to_lowercase().contains(&query) || key_raw.to_lowercase().contains(&query)
}

fn redis_search_value_text(value: &RedisValueData) -> String {
    match value {
        RedisValueData::String { content, .. } => redis_blob_display_text(content),
        RedisValueData::Json { value } => value.clone(),
        RedisValueData::List { items, .. } => {
            items.iter().map(|item| redis_blob_display_text(&item.value)).collect::<Vec<_>>().join(" ")
        }
        RedisValueData::Set { items, .. } => {
            items.iter().map(|item| redis_blob_display_text(&item.member)).collect::<Vec<_>>().join(" ")
        }
        RedisValueData::Hash { items, .. } => items
            .iter()
            .flat_map(|item| [redis_blob_display_text(&item.field), redis_blob_display_text(&item.value)])
            .collect::<Vec<_>>()
            .join(" "),
        RedisValueData::Zset { items, .. } => items
            .iter()
            .flat_map(|item| [item.score.clone(), redis_blob_display_text(&item.member)])
            .collect::<Vec<_>>()
            .join(" "),
        RedisValueData::Stream { entries, .. } => entries
            .iter()
            .flat_map(|entry| {
                entry.fields.iter().flat_map(|field| [field.field.clone(), field.value.clone()]).collect::<Vec<_>>()
            })
            .collect::<Vec<_>>()
            .join(" "),
        RedisValueData::Bitmap { content, .. } => redis_blob_display_text(content),
        RedisValueData::HyperLogLog { count } => count.map(|value| value.to_string()).unwrap_or_default(),
        RedisValueData::Unknown { .. } => String::new(),
    }
}

fn redis_search_value_preview(value: &RedisValueData) -> String {
    const MAX_PREVIEW_LEN: usize = 160;
    let text = redis_search_value_text(value);
    if text.chars().count() <= MAX_PREVIEW_LEN {
        return text;
    }
    let mut preview = text.chars().take(MAX_PREVIEW_LEN).collect::<String>();
    preview.push('…');
    preview
}

fn redis_search_value_size(value: &RedisValue) -> u64 {
    match &value.data {
        RedisValueData::String { content, total_bytes, .. } => total_bytes.unwrap_or_else(|| {
            base64::engine::general_purpose::STANDARD
                .decode(&content.raw_base64)
                .map(|bytes| bytes.len() as u64)
                .unwrap_or(0)
        }),
        RedisValueData::Json { value } => value.len() as u64,
        RedisValueData::List { total, .. }
        | RedisValueData::Set { total, .. }
        | RedisValueData::Hash { total, .. }
        | RedisValueData::Zset { total, .. } => *total,
        RedisValueData::Stream { entries, total, .. } => total.unwrap_or(entries.len() as u64),
        RedisValueData::Bitmap { content, total_bytes, .. } => total_bytes.unwrap_or_else(|| {
            base64::engine::general_purpose::STANDARD
                .decode(&content.raw_base64)
                .map(|bytes| bytes.len() as u64)
                .unwrap_or(0)
        }),
        RedisValueData::HyperLogLog { .. } => 0,
        RedisValueData::Unknown { .. } => 0,
    }
}

pub async fn get_stream_entries_page<C>(
    con: &mut C,
    key: &[u8],
    cursor: Option<&str>,
) -> Result<RedisStreamPage, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let cursor = cursor.filter(|value| !value.is_empty());
    let start = cursor.unwrap_or("-");
    // XRANGE starts inclusively. Fetch a duplicate candidate and a lookahead
    // row so this works with Redis 5 and does not skip records after trimming.
    let requested_count = stream_entry_page_request_count(cursor);
    let raw: RedisRawValue = redis::cmd("XRANGE")
        .arg(key)
        .arg(start)
        .arg("+")
        .arg("COUNT")
        .arg(requested_count)
        .query_async(con)
        .await
        .map_err(|e| e.to_string())?;

    Ok(stream_entries_page_from_raw(raw, cursor))
}

async fn get_stream_initial_page<C>(con: &mut C, key: &[u8]) -> Result<(i64, Option<u64>, RedisStreamPage), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut pipe = redis::pipe();
    pipe.cmd("TTL").arg(key);
    pipe.cmd("XLEN").arg(key);
    pipe.cmd("XRANGE").arg(key).arg("-").arg("+").arg("COUNT").arg(stream_entry_page_request_count(None));
    match pipe.query_async::<(i64, u64, RedisRawValue)>(con).await {
        Ok((ttl, total, raw)) => Ok((ttl, Some(total), stream_entries_page_from_raw(raw, None))),
        Err(_) => {
            // An ACL may allow XRANGE while rejecting the optional XLEN
            // metadata. Keep the Stream readable and omit the unknown size.
            let ttl: i64 = redis::cmd("TTL").arg(key).query_async(con).await.unwrap_or(-1);
            let total = redis::cmd("XLEN").arg(key).query_async::<u64>(con).await.ok();
            let page = get_stream_entries_page(con, key, None).await?;
            Ok((ttl, total, page))
        }
    }
}

fn stream_entry_page_request_count(cursor: Option<&str>) -> usize {
    STREAM_ENTRY_PAGE_SIZE + 1 + usize::from(cursor.is_some())
}

fn stream_entries_page_from_raw(raw: RedisRawValue, cursor: Option<&str>) -> RedisStreamPage {
    let mut entries = parse_stream_entries(raw);
    if let Some(cursor) = cursor {
        if entries.first().is_some_and(|entry| entry.id == cursor) {
            entries.remove(0);
        }
    }
    let next_cursor = if entries.len() > STREAM_ENTRY_PAGE_SIZE {
        entries.truncate(STREAM_ENTRY_PAGE_SIZE);
        entries.last().map(|entry| entry.id.clone())
    } else {
        None
    };

    RedisStreamPage { entries, next_cursor }
}

pub async fn get_stream_groups<C>(con: &mut C, key: &[u8]) -> Result<Vec<RedisStreamGroup>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let raw: RedisRawValue =
        redis::cmd("XINFO").arg("GROUPS").arg(key).query_async(con).await.map_err(|e| e.to_string())?;

    Ok(parse_stream_groups(raw))
}

pub async fn get_stream_consumers<C>(con: &mut C, key: &[u8], group: &[u8]) -> Result<Vec<RedisStreamConsumer>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let raw: RedisRawValue =
        redis::cmd("XINFO").arg("CONSUMERS").arg(key).arg(group).query_async(con).await.map_err(|e| e.to_string())?;

    Ok(parse_stream_consumers(raw))
}

pub async fn get_stream_pending_page<C>(
    con: &mut C,
    key: &[u8],
    group: &[u8],
    cursor: Option<&str>,
    consumer: Option<&[u8]>,
) -> Result<RedisStreamPendingPage, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let cursor = cursor.filter(|value| !value.is_empty());
    let start = cursor.unwrap_or("-");
    // Redis before 6.2 has no exclusive XPENDING ranges. A cursor page needs
    // a duplicate candidate and a lookahead row to page without skipping IDs.
    let requested_count = STREAM_PENDING_PAGE_SIZE + 1 + usize::from(cursor.is_some());
    let mut command = redis::cmd("XPENDING");
    command.arg(key).arg(group).arg(start).arg("+").arg(requested_count);
    if let Some(consumer) = consumer {
        command.arg(consumer);
    }
    let raw: RedisRawValue = command.query_async(con).await.map_err(|e| e.to_string())?;

    let mut entries = parse_stream_pending_entries(raw);
    if let Some(cursor) = cursor {
        if entries.first().is_some_and(|entry| entry.id == cursor) {
            entries.remove(0);
        }
    }
    let next_cursor = if entries.len() > STREAM_PENDING_PAGE_SIZE {
        entries.truncate(STREAM_PENDING_PAGE_SIZE);
        entries.last().map(|entry| entry.id.clone())
    } else {
        None
    };

    Ok(RedisStreamPendingPage { entries, next_cursor })
}

fn parse_scan_keys(raw: RedisRawValue) -> Result<(u64, Vec<Vec<u8>>), String> {
    let RedisRawValue::Array(parts) = raw else {
        return Err("Invalid Redis SCAN response".to_string());
    };
    if parts.len() != 2 {
        return Err("Invalid Redis SCAN response".to_string());
    }

    let cursor = redis_value_to_string(parts[0].clone())
        .ok_or_else(|| "Invalid Redis SCAN cursor".to_string())?
        .parse::<u64>()
        .map_err(|_| "Invalid Redis SCAN cursor".to_string())?;

    let RedisRawValue::Array(keys) = &parts[1] else {
        return Err("Invalid Redis SCAN keys payload".to_string());
    };

    let mut parsed = Vec::with_capacity(keys.len());
    for key in keys {
        parsed.push(redis_value_to_bytes(key.clone()).ok_or_else(|| "Invalid Redis key payload".to_string())?);
    }

    Ok((cursor, parsed))
}

fn parse_stream_entries(raw: RedisRawValue) -> Vec<RedisStreamEntry> {
    match raw {
        RedisRawValue::Array(entries) => entries.into_iter().filter_map(parse_stream_entry).collect(),
        _ => Vec::new(),
    }
}

fn parse_stream_entry(entry: RedisRawValue) -> Option<RedisStreamEntry> {
    let mut parts = match entry {
        RedisRawValue::Array(parts) if parts.len() == 2 => parts.into_iter(),
        _ => return None,
    };

    let id = redis_value_to_string(parts.next()?)?;
    let fields = match parts.next()? {
        RedisRawValue::Array(fields) => fields,
        _ => return None,
    };

    let mut parsed_fields = Vec::new();
    let mut fields = fields.into_iter();
    while let Some(field) = fields.next() {
        let Some(value) = fields.next() else {
            break;
        };
        if let Some(field_name) = redis_value_to_string(field) {
            let value = redis_value_to_string(value).unwrap_or_default();
            parsed_fields.push(RedisStreamField { field: field_name, value });
        }
    }

    Some(RedisStreamEntry { id, fields: parsed_fields })
}

fn parse_stream_groups(raw: RedisRawValue) -> Vec<RedisStreamGroup> {
    match raw {
        RedisRawValue::Array(groups) => groups.into_iter().filter_map(parse_stream_group).collect(),
        _ => Vec::new(),
    }
}

fn parse_stream_group(group: RedisRawValue) -> Option<RedisStreamGroup> {
    let mut attributes = parse_stream_info_attributes(group)?;
    Some(RedisStreamGroup {
        name: redis_value_to_blob(attributes.remove("name")?)?,
        consumers: redis_value_to_u64(&attributes.remove("consumers")?)?,
        pending: redis_value_to_u64(&attributes.remove("pending")?)?,
        last_delivered_id: redis_value_to_string(attributes.remove("last-delivered-id")?)?,
        entries_read: attributes.remove("entries-read").and_then(|value| redis_value_to_u64(&value)),
        lag: attributes.remove("lag").and_then(|value| redis_value_to_u64(&value)),
    })
}

fn parse_stream_consumers(raw: RedisRawValue) -> Vec<RedisStreamConsumer> {
    match raw {
        RedisRawValue::Array(consumers) => consumers.into_iter().filter_map(parse_stream_consumer).collect(),
        _ => Vec::new(),
    }
}

fn parse_stream_consumer(consumer: RedisRawValue) -> Option<RedisStreamConsumer> {
    let mut attributes = parse_stream_info_attributes(consumer)?;
    Some(RedisStreamConsumer {
        name: redis_value_to_blob(attributes.remove("name")?)?,
        pending: redis_value_to_u64(&attributes.remove("pending")?)?,
        idle_ms: redis_value_to_u64(&attributes.remove("idle")?)?,
        inactive_ms: attributes.remove("inactive").and_then(|value| redis_value_to_u64(&value)),
    })
}

fn parse_stream_pending_entries(raw: RedisRawValue) -> Vec<RedisStreamPendingEntry> {
    match raw {
        RedisRawValue::Array(entries) => entries.into_iter().filter_map(parse_stream_pending_entry).collect(),
        _ => Vec::new(),
    }
}

fn parse_stream_pending_entry(entry: RedisRawValue) -> Option<RedisStreamPendingEntry> {
    let mut parts = match entry {
        RedisRawValue::Array(parts) if parts.len() == 4 => parts.into_iter(),
        _ => return None,
    };

    Some(RedisStreamPendingEntry {
        id: redis_value_to_string(parts.next()?)?,
        consumer: redis_value_to_blob(parts.next()?)?,
        idle_ms: redis_value_to_u64(&parts.next()?)?,
        deliveries: redis_value_to_u64(&parts.next()?)?,
    })
}

fn parse_stream_info_attributes(raw: RedisRawValue) -> Option<HashMap<String, RedisRawValue>> {
    let RedisRawValue::Array(parts) = raw else {
        return None;
    };

    let mut attributes = HashMap::new();
    let mut parts = parts.into_iter();
    while let Some(name) = parts.next() {
        let value = parts.next()?;
        attributes.insert(redis_value_to_string(name)?, value);
    }
    Some(attributes)
}

fn redis_value_to_blob(value: RedisRawValue) -> Option<RedisBlob> {
    redis_value_to_bytes(value).map(|bytes| redis_blob_from_bytes(&bytes))
}

fn redis_value_to_string(value: RedisRawValue) -> Option<String> {
    match value {
        RedisRawValue::BulkString(bytes) => Some(redis_bytes_to_display(&bytes)),
        RedisRawValue::SimpleString(value) => Some(value),
        RedisRawValue::Int(value) => Some(value.to_string()),
        RedisRawValue::Double(value) => Some(value.to_string()),
        RedisRawValue::Boolean(value) => Some(value.to_string()),
        RedisRawValue::VerbatimString { text, .. } => Some(redis_bytes_to_display(text.as_bytes())),
        RedisRawValue::Okay => Some("OK".to_string()),
        _ => None,
    }
}

fn redis_value_to_bytes(value: RedisRawValue) -> Option<Vec<u8>> {
    match value {
        RedisRawValue::BulkString(bytes) => Some(bytes),
        RedisRawValue::SimpleString(value) => Some(value.into_bytes()),
        RedisRawValue::Int(value) => Some(value.to_string().into_bytes()),
        RedisRawValue::Double(value) => Some(value.to_string().into_bytes()),
        RedisRawValue::Boolean(value) => Some(value.to_string().into_bytes()),
        RedisRawValue::VerbatimString { text, .. } => Some(text.into_bytes()),
        RedisRawValue::Okay => Some(b"OK".to_vec()),
        _ => None,
    }
}

fn redis_blob_from_bytes(bytes: &[u8]) -> RedisBlob {
    RedisBlob {
        raw_base64: base64::engine::general_purpose::STANDARD.encode(bytes),
        encoding: if std::str::from_utf8(bytes).is_ok() { RedisBlobEncoding::Utf8 } else { RedisBlobEncoding::Binary },
    }
}

fn redis_blob_display_text(blob: &RedisBlob) -> String {
    let bytes = base64::engine::general_purpose::STANDARD.decode(&blob.raw_base64).unwrap_or_default();
    if matches!(blob.encoding, RedisBlobEncoding::Utf8) {
        if let Ok(text) = std::str::from_utf8(&bytes) {
            return text.to_string();
        }
    }
    redis_bytes_to_display(&bytes)
}

fn redis_list_items_from_raw(value: RedisRawValue, start_index: u64) -> Vec<RedisListItem> {
    match value {
        RedisRawValue::Array(values) => values
            .into_iter()
            .enumerate()
            .filter_map(|(offset, value)| {
                redis_value_to_bytes(value).map(|bytes| RedisListItem {
                    index: start_index + offset as u64,
                    value: redis_blob_from_bytes(&bytes),
                })
            })
            .collect(),
        _ => Vec::new(),
    }
}

fn redis_bytes_to_display(bytes: &[u8]) -> String {
    if let Ok(text) = std::str::from_utf8(bytes) {
        return text.replace('\\', "\\\\");
    }

    let mut output = String::new();
    for &byte in bytes {
        match byte {
            b'\\' => output.push_str("\\\\"),
            0x20..=0x7e => output.push(byte as char),
            _ => output.push_str(&format!("\\x{:02x}", byte)),
        }
    }
    output
}

pub fn redis_key_bytes_to_display(bytes: &[u8]) -> String {
    redis_bytes_to_display(bytes)
}

pub fn redis_key_bytes_to_raw(bytes: &[u8]) -> String {
    base64::engine::general_purpose::STANDARD.encode(bytes)
}

pub fn redis_key_raw_to_bytes(value: &str) -> Result<Vec<u8>, String> {
    base64::engine::general_purpose::STANDARD.decode(value).map_err(|e| format!("Invalid Redis key encoding: {e}"))
}

pub async fn set_string<C>(con: &mut C, key: &[u8], value: &str, ttl: Option<i64>) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    match ttl {
        Some(t) => {
            redis::cmd("SET").arg(key).arg(value).query_async::<()>(con).await.map_err(|e| e.to_string())?;
            if t > 0 {
                redis::cmd("EXPIRE").arg(key).arg(t).query_async::<()>(con).await.map_err(|e| e.to_string())?;
            }
            Ok(())
        }
        None => set_string_preserving_ttl(con, key, value).await,
    }
}

async fn set_string_preserving_ttl<C>(con: &mut C, key: &[u8], value: &str) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    match redis::cmd("SET").arg(key).arg(value).arg("KEEPTTL").query_async::<()>(con).await {
        Ok(()) => Ok(()),
        Err(error) if is_unsupported_keepttl_error(&error) => {
            let remaining_ms = redis::cmd("PTTL").arg(key).query_async::<i64>(con).await.map_err(|e| e.to_string())?;
            let mut command = redis::cmd("SET");
            command.arg(key).arg(value);
            if remaining_ms >= 0 {
                // Redis requires PX to be positive. A zero PTTL means the key is
                // about to expire, so one millisecond is the closest equivalent.
                command.arg("PX").arg(remaining_ms.max(1));
            }
            command.query_async::<()>(con).await.map_err(|e| e.to_string())
        }
        Err(error) => Err(error.to_string()),
    }
}

fn is_unsupported_keepttl_error(error: &redis::RedisError) -> bool {
    if error.kind() != redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError) {
        return false;
    }

    let detail = error.detail().unwrap_or_default().to_ascii_lowercase();
    detail.contains("syntax error")
        || ((detail.contains("unknown") || detail.contains("unsupported")) && detail.contains("keepttl"))
}

pub async fn delete_key<C>(con: &mut C, key: &[u8]) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("DEL").arg(key).query_async::<()>(con).await.map_err(|e| e.to_string())
}

/// Rename a key without overwriting an existing destination.
pub async fn rename_key<C>(con: &mut C, key: &[u8], new_key: &[u8]) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let renamed =
        redis::cmd("RENAMENX").arg(key).arg(new_key).query_async::<bool>(con).await.map_err(|e| e.to_string())?;
    if renamed {
        Ok(())
    } else {
        Err("Target key already exists".to_string())
    }
}

async fn apply_expire_if_needed<C>(con: &mut C, key: &[u8], ttl: Option<i64>) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    if let Some(t) = ttl {
        if t > 0 {
            redis::cmd("EXPIRE").arg(key).arg(t).query_async::<()>(con).await.map_err(|e| e.to_string())?;
        }
    }
    Ok(())
}

pub async fn hash_set<C>(con: &mut C, key: &[u8], field: &str, value: &str, ttl: Option<i64>) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let previous_field_ttl = if ttl.is_none() { read_hash_field_ttl(con, key, field.as_bytes()).await? } else { None };
    redis::cmd("HSET").arg(key).arg(field).arg(value).query_async::<()>(con).await.map_err(|e| e.to_string())?;
    if let Some(previous_ttl) = previous_field_ttl.filter(|ttl| *ttl > 0) {
        let remaining_ttl = previous_ttl.max(1);
        set_hash_field_ttl(con, key, field, remaining_ttl).await?;
    }
    apply_expire_if_needed(con, key, ttl).await
}

pub async fn hash_del<C>(con: &mut C, key: &[u8], field: &str) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("HDEL").arg(key).arg(field).query_async::<()>(con).await.map_err(|e| e.to_string())
}

/// Atomically update a hash field, optionally moving it to a new name.
///
/// The operation is intentionally implemented as one Lua script rather than
/// as an HSET/HDEL pair.  That keeps destination collision checks and the
/// source deletion in the same server-side critical section.  Hash-field
/// expiry commands were introduced after hashes themselves, so the script
/// probes them with `pcall` and preserves expiry when the server supports
/// HTTL/HEXPIRE while remaining usable on older Redis versions.  Some Redis
/// cluster implementations reject the whole script before Lua can probe those
/// commands, so this also retries with an equivalent script that never
/// references field-expiry commands.  Permission errors are surfaced instead
/// of being mistaken for an unsupported command, since silently dropping a
/// field TTL would be data loss.
pub async fn hash_field_update<C>(
    con: &mut C,
    key: &[u8],
    old_field: &str,
    new_field: &str,
    value: &str,
) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    const SCRIPT_WITH_FIELD_TTL: &str = r#"
        local key = KEYS[1]
        local old_field = ARGV[1]
        local new_field = ARGV[2]
        local value = ARGV[3]

        -- Keep enough source state to undo a destination write if a later
        -- command fails.  EVAL itself is atomic, but Redis does not roll back
        -- writes made before a Lua runtime error.
        if redis.call('HEXISTS', key, old_field) == 0 then
            return 0
        end
        local old_value = redis.call('HGET', key, old_field)
        if old_value == false then
            return 0
        end
        if old_field ~= new_field and redis.call('HEXISTS', key, new_field) == 1 then
            return -1
        end

        if old_field ~= new_field then
            -- The collision check established that new_field is absent. Probe
            -- HDEL before writing so a restricted HDEL permission cannot
            -- leave both fields behind after the later source delete.
            local delete_probe = redis.pcall('HDEL', key, new_field)
            if type(delete_probe) == 'table' and delete_probe.err ~= nil then
                return -3
            end
        end

        local function optional_expiry_error(reply)
            if type(reply) ~= 'table' or reply.err == nil then
                return false
            end
            local detail = string.lower(reply.err)
            -- Redis < 7.4 reports an HTTL/HEXPIRE pcall as "Unknown Redis
            -- command called from [Lua] script", not the top-level "unknown
            -- command" wording. Permission and WRONGTYPE errors use different
            -- wording and must still fail.
            return string.find(detail, 'unknown command', 1, true) ~= nil
                or string.find(detail, 'unknown redis command', 1, true) ~= nil
                or string.find(detail, 'syntax error', 1, true) ~= nil
                or string.find(detail, 'unsupported', 1, true) ~= nil
        end

        -- HTTL returns an array containing -1 (persistent), -2 (missing), or
        -- the remaining seconds.  Unsupported commands are deliberately
        -- ignored so Redis versions without hash-field expiry still work.
        local source_ttl = -2
        local ttl_reply = redis.pcall('HTTL', key, 'FIELDS', 1, old_field)
        if type(ttl_reply) == 'table' and ttl_reply.err ~= nil then
            local detail = string.lower(ttl_reply.err)
            if not optional_expiry_error(ttl_reply)
                and detail ~= 'invalid argument: hash field expiration is not supported by legacy hash encoding'
                and detail ~= 'err invalid argument: hash field expiration is not supported by legacy hash encoding' then
                return -3
            end
        elseif type(ttl_reply) == 'table' and ttl_reply[1] ~= nil then
            source_ttl = tonumber(ttl_reply[1])
            if source_ttl == nil or source_ttl < -2 then
                return -3
            end
            -- The source can expire between the initial HGET and HTTL. Do
            -- not create a new field when the probe already says it is gone.
            if source_ttl == -2 then
                return 0
            end
            -- HTTL rounds down to seconds. HEXPIRE 0 deletes a field, so an
            -- imminent expiry must abort before HSET rather than losing data.
            if source_ttl == 0 then
                return -3
            end
        end

        local function restore_source()
            local restored = redis.pcall('HSET', key, old_field, old_value)
            if type(restored) == 'table' and restored.err ~= nil then
                return false
            end
            if source_ttl > 0 then
                local expiry = redis.pcall('HEXPIRE', key, source_ttl, 'FIELDS', 1, old_field)
                if type(expiry) == 'table' and expiry.err ~= nil and not optional_expiry_error(expiry) then
                    return false
                end
            end
            return true
        end

        local function apply_source_expiry(field)
            if source_ttl < 0 then
                return true
            end
            local expiry = redis.pcall('HEXPIRE', key, source_ttl, 'FIELDS', 1, field)
            if type(expiry) == 'table' and expiry.err ~= nil then
                -- A missing command is expected on Redis versions before
                -- hash-field expiry.  Other errors must fail safely.
                return optional_expiry_error(expiry)
            end
            return type(expiry) == 'table' and tonumber(expiry[1]) == 1
        end

        local written = redis.pcall('HSET', key, new_field, value)
        if type(written) == 'table' and written.err ~= nil then
            return -3
        end

        if not apply_source_expiry(new_field) then
            if old_field == new_field then
                restore_source()
            else
                redis.pcall('HDEL', key, new_field)
            end
            return -3
        end

        if old_field == new_field then
            return 1
        end

        local deleted = redis.pcall('HDEL', key, old_field)
        if type(deleted) == 'table' and deleted.err ~= nil then
            redis.pcall('HDEL', key, new_field)
            return -3
        end
        if tonumber(deleted) ~= 1 then
            redis.pcall('HDEL', key, new_field)
            return 0
        end
        return 2
    "#;

    const SCRIPT_WITHOUT_FIELD_TTL: &str = r#"
        local key = KEYS[1]
        local old_field = ARGV[1]
        local new_field = ARGV[2]
        local value = ARGV[3]

        if redis.call('HEXISTS', key, old_field) == 0 then
            return 0
        end
        if redis.call('HGET', key, old_field) == false then
            return 0
        end
        if old_field ~= new_field and redis.call('HEXISTS', key, new_field) == 1 then
            return -1
        end

        if old_field ~= new_field then
            local delete_probe = redis.pcall('HDEL', key, new_field)
            if type(delete_probe) == 'table' and delete_probe.err ~= nil then
                return -3
            end
        end

        local written = redis.pcall('HSET', key, new_field, value)
        if type(written) == 'table' and written.err ~= nil then
            return -3
        end

        if old_field == new_field then
            return 1
        end

        local deleted = redis.pcall('HDEL', key, old_field)
        if type(deleted) == 'table' and deleted.err ~= nil then
            redis.pcall('HDEL', key, new_field)
            return -3
        end
        if tonumber(deleted) ~= 1 then
            redis.pcall('HDEL', key, new_field)
            return 0
        end
        return 2
    "#;

    let error =
        match execute_hash_field_update_script(con, SCRIPT_WITH_FIELD_TTL, key, old_field, new_field, value).await {
            Ok(()) => return Ok(()),
            Err(error) => error,
        };

    if !is_hash_field_update_cluster_script_rejection(&error) {
        return Err(error);
    }

    execute_hash_field_update_script(con, SCRIPT_WITHOUT_FIELD_TTL, key, old_field, new_field, value).await
}

async fn execute_hash_field_update_script<C>(
    con: &mut C,
    script: &str,
    key: &[u8],
    old_field: &str,
    new_field: &str,
    value: &str,
) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let result = redis::cmd("EVAL")
        .arg(script)
        .arg(1)
        .arg(key)
        .arg(old_field)
        .arg(new_field)
        .arg(value)
        .query_async::<i64>(con)
        .await;

    let result = match result {
        Ok(result) => result,
        Err(error) if is_hash_field_update_acl_compatibility_error(&error) => {
            return Err(
                "Atomic Redis hash field updates require the Redis EVAL and hash command permissions. Ask an administrator to grant them."
                    .to_string(),
            );
        }
        Err(error) => return Err(error.to_string()),
    };

    match result {
        1 | 2 => Ok(()),
        0 => Err("The Redis hash field no longer exists. Refresh and try again.".to_string()),
        -1 => Err("A Redis hash field with the new name already exists.".to_string()),
        -3 => Err("Redis hash field update failed before completion.".to_string()),
        _ => Err("Unexpected result while updating Redis hash field.".to_string()),
    }
}

fn is_hash_field_update_acl_compatibility_error(error: &redis::RedisError) -> bool {
    if error.code() != Some("NOPERM") {
        return false;
    }

    let detail = error.detail().unwrap_or_default().to_ascii_lowercase();
    detail.contains("eval")
        || detail.contains("hexists")
        || detail.contains("hget")
        || detail.contains("hset")
        || detail.contains("hdel")
        || detail.contains("httl")
        || detail.contains("hexpire")
}

fn is_hash_field_update_cluster_script_rejection(error: &str) -> bool {
    let detail = error.to_ascii_lowercase();
    detail.contains("bad lua script for redis cluster") && (detail.contains("httl") || detail.contains("hexpire"))
}

/// Which end of a Redis list to push to. `Right` (RPUSH) is the historical
/// default; `Left` (LPUSH) lets users prepend when using lists as queues.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ListPushSide {
    Left,
    Right,
}

impl ListPushSide {
    pub fn from_str_lossy(value: Option<&str>) -> Self {
        match value.map(str::to_ascii_lowercase).as_deref() {
            Some("left") => ListPushSide::Left,
            _ => ListPushSide::Right,
        }
    }

    fn command(self) -> &'static str {
        match self {
            ListPushSide::Left => "LPUSH",
            ListPushSide::Right => "RPUSH",
        }
    }
}

pub async fn list_push<C>(
    con: &mut C,
    key: &[u8],
    value: &str,
    ttl: Option<i64>,
    side: ListPushSide,
) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd(side.command()).arg(key).arg(value).query_async::<()>(con).await.map_err(|e| e.to_string())?;
    apply_expire_if_needed(con, key, ttl).await
}

pub async fn list_set<C>(con: &mut C, key: &[u8], index: i64, value: &str) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("LSET").arg(key).arg(index).arg(value).query_async::<()>(con).await.map_err(|e| e.to_string())
}

pub async fn list_remove<C>(con: &mut C, key: &[u8], index: i64) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let placeholder = "__DELETED_PLACEHOLDER__";
    redis::cmd("LSET").arg(key).arg(index).arg(placeholder).query_async::<()>(con).await.map_err(|e| e.to_string())?;
    redis::cmd("LREM").arg(key).arg(1).arg(placeholder).query_async::<()>(con).await.map_err(|e| e.to_string())
}

pub async fn set_add<C>(con: &mut C, key: &[u8], member: &str, ttl: Option<i64>) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("SADD").arg(key).arg(member).query_async::<()>(con).await.map_err(|e| e.to_string())?;
    apply_expire_if_needed(con, key, ttl).await
}

pub async fn set_remove<C>(con: &mut C, key: &[u8], member: &str) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("SREM").arg(key).arg(member).query_async::<()>(con).await.map_err(|e| e.to_string())
}

pub async fn zadd<C>(con: &mut C, key: &[u8], member: &str, score: f64, ttl: Option<i64>) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("ZADD").arg(key).arg(score).arg(member).query_async::<()>(con).await.map_err(|e| e.to_string())?;
    apply_expire_if_needed(con, key, ttl).await
}

pub async fn zrem<C>(con: &mut C, key: &[u8], member: &str) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("ZREM").arg(key).arg(member).query_async::<()>(con).await.map_err(|e| e.to_string())
}

pub async fn zset_update<C>(
    con: &mut C,
    key: &[u8],
    original_member: &str,
    expected_score: &str,
    member: &str,
    score: &str,
) -> Result<bool, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    // Keep the source check, duplicate check, score write, and optional rename
    // in one Redis operation so a failed save cannot delete the original member.
    const SCRIPT: &str = r#"
        local current_score = redis.call('ZSCORE', KEYS[1], ARGV[1])
        if current_score == false then
            return 0
        end
        if current_score ~= ARGV[3] then
            return -2
        end
        if ARGV[1] ~= ARGV[2] and redis.call('ZSCORE', KEYS[1], ARGV[2]) ~= false then
            return -1
        end
        redis.call('ZADD', KEYS[1], ARGV[4], ARGV[2])
        if ARGV[1] ~= ARGV[2] then
            redis.call('ZREM', KEYS[1], ARGV[1])
        end
        return 1
    "#;

    let result = redis::cmd("EVAL")
        .arg(SCRIPT)
        .arg(1)
        .arg(key)
        .arg(original_member)
        .arg(member)
        .arg(expected_score)
        .arg(score)
        .query_async::<i64>(con)
        .await;

    let result = match result {
        Ok(result) => result,
        Err(error) if is_zset_update_acl_compatibility_error(&error) => {
            return Err(
                "Atomic ZSet updates require the Redis EVAL and ZSCORE permissions. Ask an administrator to grant them."
                    .to_string(),
            );
        }
        Err(error) => return Err(error.to_string()),
    };

    match result {
        1 => Ok(false),
        0 => Err("The ZSet member no longer exists. Refresh and try again.".to_string()),
        -1 => Err("A ZSet member with the new value already exists.".to_string()),
        -2 => Err("The ZSet score changed after it was loaded. Refresh and try again.".to_string()),
        _ => Err("Unexpected result while updating ZSet member.".to_string()),
    }
}

fn is_zset_update_acl_compatibility_error(error: &redis::RedisError) -> bool {
    if error.code() != Some("NOPERM") {
        return false;
    }

    let detail = error.detail().unwrap_or_default().to_ascii_lowercase();
    detail.contains("eval") || detail.contains("zscore")
}

pub async fn stream_add<C>(
    con: &mut C,
    key: &[u8],
    entry_id: &str,
    fields: &[(String, String)],
    ttl: Option<i64>,
) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut cmd = redis::cmd("XADD");
    cmd.arg(key).arg(entry_id);
    for (field, value) in fields {
        cmd.arg(field.as_str()).arg(value.as_str());
    }
    cmd.query_async::<()>(con).await.map_err(|e| e.to_string())?;
    apply_expire_if_needed(con, key, ttl).await
}

pub async fn json_set<C>(con: &mut C, key: &[u8], value: &str, ttl: Option<i64>) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    redis::cmd("JSON.SET").arg(key).arg("$").arg(value).query_async::<()>(con).await.map_err(|e| e.to_string())?;
    apply_expire_if_needed(con, key, ttl).await
}

pub async fn check_json_module<C>(con: &mut C) -> Result<bool, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let raw: RedisRawValue = redis::cmd("MODULE").arg("LIST").query_async(con).await.map_err(|e| e.to_string())?;
    Ok(match raw {
        RedisRawValue::Array(modules) => modules.iter().any(|module| {
            if let RedisRawValue::Array(kvs) = module {
                kvs.get(1)
                    .is_some_and(|v| matches!(v, RedisRawValue::BulkString(n) if n.eq_ignore_ascii_case(b"ReJSON")))
            } else {
                false
            }
        }),
        _ => false,
    })
}

pub async fn set_ttl<C>(con: &mut C, key: &[u8], ttl: i64) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    if ttl > 0 {
        let applied =
            redis::cmd("EXPIRE").arg(key).arg(ttl).query_async::<i64>(con).await.map_err(|e| e.to_string())?;
        if applied == 1 {
            Ok(())
        } else {
            Err("Redis key no longer exists; EXPIRE was not applied".to_string())
        }
    } else {
        // Redis treats PERSIST as idempotent: a zero reply also means the key
        // was already persistent. Follow-up reads in the UI handle a key that
        // disappeared concurrently without requiring an extra ACL permission.
        redis::cmd("PERSIST").arg(key).query_async::<()>(con).await.map_err(|e| e.to_string())
    }
}

pub async fn set_expire_at<C>(con: &mut C, key: &[u8], expire_at: i64) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let applied =
        redis::cmd("EXPIREAT").arg(key).arg(expire_at).query_async::<i64>(con).await.map_err(|e| e.to_string())?;
    if applied == 1 {
        Ok(())
    } else {
        Err("Redis key no longer exists; EXPIREAT was not applied".to_string())
    }
}

/// Applies one expiration command per selected key in a single bounded round trip.
///
/// Keys the caller already selected may disappear concurrently, so this reports
/// them instead of failing the whole batch. `PERSIST` stays idempotent: Redis
/// answers 0 both for a missing key and for a key that is already persistent.
pub async fn set_keys_expiry<C>(
    con: &mut C,
    keys: &[Vec<u8>],
    expiry: RedisKeysExpiry,
) -> Result<RedisKeysExpiryResult, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    if keys.is_empty() {
        return Ok(RedisKeysExpiryResult::default());
    }

    let mut pipeline = Pipeline::with_capacity(keys.len());
    for key in keys {
        match expiry {
            RedisKeysExpiry::Persist => {
                pipeline.cmd("PERSIST").arg(key.as_slice());
            }
            RedisKeysExpiry::Ttl(ttl) => {
                pipeline.cmd("EXPIRE").arg(key.as_slice()).arg(ttl);
            }
            RedisKeysExpiry::At(expire_at) => {
                pipeline.cmd("EXPIREAT").arg(key.as_slice()).arg(expire_at);
            }
        }
    }

    let replies: Vec<RedisRawValue> = pipeline.query_async(con).await.map_err(|error| error.to_string())?;
    summarize_keys_expiry(keys, expiry, &replies)
}

fn summarize_keys_expiry(
    keys: &[Vec<u8>],
    expiry: RedisKeysExpiry,
    replies: &[RedisRawValue],
) -> Result<RedisKeysExpiryResult, String> {
    let mut result = RedisKeysExpiryResult::default();
    for (index, key) in keys.iter().enumerate() {
        let applied = match expiry {
            // Redis answers 0 for an already-persistent key as well, so PERSIST
            // must not be reported as a missing key.
            RedisKeysExpiry::Persist => true,
            _ => match replies.get(index) {
                Some(RedisRawValue::Int(reply)) => *reply == 1,
                // A server error or a short reply must not be silently counted
                // as a per-key miss, or the batch would report a false success.
                _ => return Err(format!("{} did not return one reply per selected key", expiry.command())),
            },
        };
        if applied {
            result.applied += 1;
        } else {
            result.missing_key_raws.push(redis_key_bytes_to_raw(key));
        }
    }
    Ok(result)
}

pub async fn set_hash_field_ttl<C>(con: &mut C, key: &[u8], field: &str, ttl: i64) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    if ttl <= 0 {
        let raw: RedisRawValue = redis::cmd("HPERSIST")
            .arg(key)
            .arg("FIELDS")
            .arg(1)
            .arg(field)
            .query_async(con)
            .await
            .map_err(|e| e.to_string())?;
        return parse_hash_field_expiry_result(raw, "HPERSIST", true);
    }

    let raw: RedisRawValue = redis::cmd("HEXPIRE")
        .arg(key)
        .arg(ttl)
        .arg("FIELDS")
        .arg(1)
        .arg(field)
        .query_async(con)
        .await
        .map_err(|e| e.to_string())?;
    parse_hash_field_expiry_result(raw, "HEXPIRE", false)
}

pub async fn set_hash_field_expire_at<C>(con: &mut C, key: &[u8], field: &str, expire_at: i64) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let raw: RedisRawValue = redis::cmd("HEXPIREAT")
        .arg(key)
        .arg(expire_at)
        .arg("FIELDS")
        .arg(1)
        .arg(field)
        .query_async(con)
        .await
        .map_err(|e| e.to_string())?;
    parse_hash_field_expiry_result(raw, "HEXPIREAT", false)
}

fn parse_hash_field_expiry_result(raw: RedisRawValue, command: &str, allow_persist_noop: bool) -> Result<(), String> {
    let RedisRawValue::Array(mut values) = raw else {
        return Err(format!("Invalid {command} response"));
    };
    let Some(result) = values.pop().and_then(redis_value_to_string).and_then(|value| value.parse::<i64>().ok()) else {
        return Err(format!("Invalid {command} response"));
    };
    match result {
        1 => Ok(()),
        -1 if allow_persist_noop => Ok(()),
        2 => Err(format!("{command} removed the hash field because it was already expired")),
        -2 => Err("Redis hash field no longer exists".to_string()),
        _ => Err(format!("{command} was not applied to the hash field")),
    }
}

pub async fn delete_keys<C>(con: &mut C, keys: &[Vec<u8>]) -> Result<u64, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut cmd = redis::cmd("DEL");
    for key in keys {
        cmd.arg(key.as_slice());
    }
    cmd.query_async(con).await.map_err(|e| e.to_string())
}

/// `SCAN COUNT` hint used by [`delete_keys_by_pattern`]; large enough to keep
/// the cycle count low, small enough that one cycle stays cheap on the server.
pub const DELETE_KEYS_BY_PATTERN_SCAN_COUNT: usize = 500;
/// Upper bound on the keys carried by a single `DEL` command.
const DELETE_KEYS_BY_PATTERN_DELETE_BATCH: usize = 512;

/// Deletes every key matching `pattern` with repeated `SCAN` + `DEL` cycles.
///
/// A group in the key browser is a key *prefix*: the loaded rows are only the
/// part of that subtree the browser has scanned so far, so deleting just those
/// rows leaves the rest of the subtree behind. `KEYS` or one oversized `DEL`
/// would block the server for a large subtree, so keys are discovered with one
/// `SCAN` cycle at a time and deleted in bounded batches.
pub async fn delete_keys_by_pattern<C>(con: &mut C, pattern: &str, scan_count: usize) -> Result<u64, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let count = scan_count.max(1);
    let mut cursor = 0u64;
    let mut deleted = 0u64;
    loop {
        let page = scan_keys_batch_inner(con, cursor, pattern, count, 1, false, false).await?;
        let keys: Result<Vec<Vec<u8>>, String> =
            page.keys.iter().map(|key| redis_key_raw_to_bytes(&key.key_raw)).collect();
        for batch in keys?.chunks(DELETE_KEYS_BY_PATTERN_DELETE_BATCH) {
            deleted += delete_keys(con, batch).await?;
        }
        cursor = page.cursor;
        if cursor == 0 {
            return Ok(deleted);
        }
    }
}

pub async fn load_more_collection<C>(
    con: &mut C,
    key: &[u8],
    key_type: &str,
    cursor: u64,
    count: usize,
    filter_query: Option<&str>,
    sort_direction: Option<&str>,
) -> Result<RedisCollectionPage, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    load_more_collection_scoped(
        con,
        key,
        key_type,
        cursor,
        count,
        filter_query,
        sort_direction,
        &RedisOperationScope::default(),
    )
    .await
}

pub async fn load_more_collection_scoped<C>(
    con: &mut C,
    key: &[u8],
    key_type: &str,
    cursor: u64,
    count: usize,
    filter_query: Option<&str>,
    sort_direction: Option<&str>,
    scope: &RedisOperationScope,
) -> Result<RedisCollectionPage, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    if cursor >= COLLECTION_OVERFLOW_CURSOR_START && !matches!(key_type, "hash" | "set") {
        return Err("Collection cursor belongs to a different collection type".to_string());
    }
    let filter_query = filter_query.filter(|query| !query.is_empty());
    match key_type {
        "list" => {
            let len: u64 = redis::cmd("LLEN").arg(key).query_async(con).await.unwrap_or(0);
            if let Some(query) = filter_query {
                let (items, next) = lrange_filtered_page_raw(con, key, cursor, count, len, query).await?;
                return Ok(RedisCollectionPage::List { items, scan_cursor: (next < len).then_some(next) });
            }
            let start = cursor as i64;
            let end = start + count as i64 - 1;
            let v: RedisRawValue =
                redis::cmd("LRANGE").arg(key).arg(start).arg(end).query_async(con).await.map_err(|e| e.to_string())?;
            let mut items = redis_list_items_from_raw(v, cursor);
            items.truncate(budgeted_page_len(&items, count, list_item_page_bytes));
            let next = cursor + items.len() as u64;
            Ok(RedisCollectionPage::List { items, scan_cursor: (next < len).then_some(next) })
        }
        "set" => {
            let (next_cursor, items) = if let Some(query) = filter_query {
                sscan_bounded_page(con, scope, key, cursor, count, Some(query)).await?
            } else {
                sscan_bounded_page(con, scope, key, cursor, count, None).await?
            };
            Ok(RedisCollectionPage::Set { items, scan_cursor: (next_cursor > 0).then_some(next_cursor) })
        }
        "zset" => {
            let descending = match sort_direction.unwrap_or("asc") {
                "asc" => false,
                "desc" => true,
                direction => return Err(format!("Invalid ZSet sort direction: {direction}")),
            };
            if let Some(query) = filter_query {
                let (items, next, has_more) =
                    zrange_filtered_page_raw(con, key, cursor, count, descending, query).await?;
                return Ok(RedisCollectionPage::Zset { items, scan_cursor: has_more.then_some(next) });
            }
            let start = cursor as i64;
            let end = start + count as i64;
            let mut items = zrange_page_raw(con, key, start, end, descending).await?;
            // `zrange_page_raw` reads one extra member to detect a further page; the byte budget
            // can also end the page before `count`, which likewise leaves members behind.
            let has_more = items.len() > count;
            let page_len = budgeted_page_len(&items, count, zset_item_page_bytes);
            let ended_early = page_len < items.len().min(count);
            items.truncate(page_len);
            let next = cursor + items.len() as u64;
            Ok(RedisCollectionPage::Zset { items, scan_cursor: (has_more || ended_early).then_some(next) })
        }
        "hash" => {
            let (next_cursor, mut items) = if let Some(query) = filter_query {
                hscan_bounded_page(con, scope, key, cursor, count, Some(query)).await?
            } else {
                hscan_bounded_page(con, scope, key, cursor, count, None).await?
            };
            attach_hash_field_ttls(con, key, &mut items).await?;
            Ok(RedisCollectionPage::Hash { items, scan_cursor: (next_cursor > 0).then_some(next_cursor) })
        }
        _ => Err(format!("Pagination not supported for type: {key_type}")),
    }
}

async fn hscan_page_raw<C>(
    con: &mut C,
    key: &[u8],
    cursor: u64,
    count: usize,
    lowered_query: Option<&str>,
) -> Result<(u64, Vec<RedisHashItem>), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut cmd = redis::cmd("HSCAN");
    cmd.arg(key).arg(cursor).arg("COUNT").arg(count);
    let raw: RedisRawValue = cmd.query_async(con).await.map_err(|e| e.to_string())?;
    parse_scan_hash_entries(raw, lowered_query)
}

async fn hscan_filtered_page_raw<C>(
    con: &mut C,
    key: &[u8],
    cursor: u64,
    count: usize,
    query: &str,
) -> Result<(u64, Vec<RedisHashItem>), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut cur = cursor;
    let mut items = Vec::new();
    let target = count.max(1);
    let lowered = query.to_lowercase();

    // A full field name should not have to wait for its hash-table scan bucket.
    // Still scan one batch to obtain a real continuation for the fuzzy search.
    if cursor == 0 {
        let exact: Option<Vec<u8>> = match redis::cmd("HGET").arg(key).arg(query.as_bytes()).query_async(con).await {
            Ok(value) => value,
            Err(error) if is_redis_command_denied_error(&error.to_string()) => None,
            Err(error) => return Err(error.to_string()),
        };
        if let Some(value) = exact {
            items.push(RedisHashItem {
                field: redis_blob_from_bytes(query.as_bytes()),
                value: redis_blob_from_bytes(&value),
                field_ttl: None,
            });
        }
    }
    let exact_match = !items.is_empty();
    let mut positions: HashMap<String, usize> =
        items.iter().enumerate().map(|(index, item)| (item.field.raw_base64.clone(), index)).collect();
    for _ in 0..COLLECTION_FILTER_SCAN_MAX_ITERATIONS {
        let (next, page) = hscan_page_raw(con, key, cur, target, Some(&lowered)).await?;
        for item in page {
            if let Some(&index) = positions.get(&item.field.raw_base64) {
                items[index] = item;
            } else {
                positions.insert(item.field.raw_base64.clone(), items.len());
                items.push(item);
            }
        }
        cur = next;
        // HSCAN MATCH only checks field names, so value search has to filter returned pairs client-side.
        // Keep a hard scan bound so sparse value matches cannot turn one UI search into a full hash walk.
        if exact_match || cur == 0 || items.len() >= target {
            break;
        }
    }

    Ok((cur, items))
}

async fn sscan_filtered_page_raw<C>(
    con: &mut C,
    key: &[u8],
    cursor: u64,
    count: usize,
    query: &str,
) -> Result<(u64, Vec<RedisSetItem>), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut cur = cursor;
    let mut items = Vec::new();
    let target = count.max(1);
    let lowered = query.to_lowercase();

    for _ in 0..COLLECTION_FILTER_SCAN_MAX_ITERATIONS {
        let (next, page) = sscan_page_raw(con, key, cur, target).await?;
        items.extend(page.into_iter().filter(|item| blob_matches_query(&item.member, &lowered)));
        cur = next;
        // SSCAN MATCH uses glob syntax over the raw member bytes, so substring search filters
        // returned members client-side. Keep the same hard scan bound the hash filter uses.
        if cur == 0 || items.len() >= target {
            break;
        }
    }

    Ok((cur, items))
}

/// Scans ZRANGE/ZREVRANGE pages so score ordering and the index-based cursor survive filtering.
async fn zrange_filtered_page_raw<C>(
    con: &mut C,
    key: &[u8],
    cursor: u64,
    count: usize,
    descending: bool,
    query: &str,
) -> Result<(Vec<RedisZsetItem>, u64, bool), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut cur = cursor;
    let mut items = Vec::new();
    let target = count.max(1);
    let lowered = query.to_lowercase();
    let mut has_more = false;

    for _ in 0..COLLECTION_FILTER_SCAN_MAX_ITERATIONS {
        let start = cur as i64;
        // Overshoot by one so a full page tells us more members remain past this window.
        let mut page = zrange_page_raw(con, key, start, start + target as i64, descending).await?;
        has_more = page.len() > target;
        page.truncate(target);
        let scanned = page.len();
        items.extend(page.into_iter().filter(|item| blob_matches_query(&item.member, &lowered)));
        cur += scanned as u64;
        if !has_more || items.len() >= target {
            break;
        }
    }

    Ok((items, cur, has_more))
}

/// Walks LRANGE windows and filters each one after indices are assigned, so the surviving
/// items keep their real list positions (the UI deletes list entries by index).
async fn lrange_filtered_page_raw<C>(
    con: &mut C,
    key: &[u8],
    cursor: u64,
    count: usize,
    len: u64,
    query: &str,
) -> Result<(Vec<RedisListItem>, u64), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let mut cur = cursor;
    let mut items = Vec::new();
    let target = count.max(1);
    let lowered = query.to_lowercase();

    for _ in 0..COLLECTION_FILTER_SCAN_MAX_ITERATIONS {
        // LLEN is only a bound here: it falls back to 0 when the command is unavailable,
        // and an empty LRANGE window is what actually proves the walk is done.
        if len > 0 && cur >= len {
            break;
        }
        let start = cur as i64;
        let raw: RedisRawValue = redis::cmd("LRANGE")
            .arg(key)
            .arg(start)
            .arg(start + target as i64 - 1)
            .query_async(con)
            .await
            .map_err(|e| e.to_string())?;
        let page = redis_list_items_from_raw(raw, cur);
        let scanned = page.len();
        items.extend(page.into_iter().filter(|item| blob_matches_query(&item.value, &lowered)));
        if scanned == 0 {
            cur = len;
            break;
        }
        cur += scanned as u64;
        if items.len() >= target {
            break;
        }
    }

    Ok((items, cur))
}

async fn hscan_bounded_page<C>(
    con: &mut C,
    scope: &RedisOperationScope,
    key: &[u8],
    cursor: u64,
    count: usize,
    filter_query: Option<&str>,
) -> Result<(u64, Vec<RedisHashItem>), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let count = count.max(1);
    let (buffered_cursor, mut items) = match take_hash_overflow_page(scope, key, cursor, count, filter_query).await {
        Some((next, items)) => {
            let has_more_buffered = {
                let sessions = collection_overflow_sessions().lock().await;
                match sessions.entries.get(&cursor).map(|s| &s.items) {
                    Some(RedisCollectionOverflowItems::Hash(items)) => !items.is_empty(),
                    _ => false,
                }
            };
            let page_bytes: usize = items.iter().map(hash_item_page_bytes).sum();
            if items.len() >= count || next == 0 || has_more_buffered || page_bytes >= COLLECTION_PAGE_MAX_BYTES {
                return Ok((next, items));
            }
            (next, items)
        }
        None => (cursor, Vec::new()),
    };

    let (scan_cursor, previous_session) = if buffered_cursor == cursor {
        take_collection_scan_cursor(scope, key, cursor, RedisCollectionOverflowKind::Hash, filter_query).await?
    } else {
        (buffered_cursor, None)
    };

    if cursor != 0 && scan_cursor == 0 {
        return Ok((0, items));
    }

    let needed = count.saturating_sub(items.len()).max(1);
    let scanned = if let Some(query) = filter_query {
        hscan_filtered_page_raw(con, key, scan_cursor, needed, query).await
    } else {
        hscan_page_raw(con, key, scan_cursor, needed, None).await
    };

    let (next_cursor, scanned_items) = match scanned {
        Ok(page) => page,
        Err(error) => {
            if let Some(mut session) = previous_session {
                if !items.is_empty() {
                    session.items = RedisCollectionOverflowItems::Hash(items);
                }
                collection_overflow_sessions().lock().await.reinsert(cursor, session);
            }
            return Err(error);
        }
    };

    let mut seen: HashSet<String> = items.iter().map(|item| item.field.raw_base64.clone()).collect();
    for item in scanned_items {
        if seen.insert(item.field.raw_base64.clone()) {
            items.push(item);
        }
    }

    let page_len = budgeted_page_len(&items, count, hash_item_page_bytes);
    let next_cursor = store_hash_overflow_page(scope, key, &mut items, page_len, next_cursor, filter_query).await;
    Ok((next_cursor, items))
}

async fn sscan_bounded_page<C>(
    con: &mut C,
    scope: &RedisOperationScope,
    key: &[u8],
    cursor: u64,
    count: usize,
    filter_query: Option<&str>,
) -> Result<(u64, Vec<RedisSetItem>), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let count = count.max(1);
    let (buffered_cursor, mut items) = match take_set_overflow_page(scope, key, cursor, count, filter_query).await {
        Some((next, items)) => {
            let has_more_buffered = {
                let sessions = collection_overflow_sessions().lock().await;
                match sessions.entries.get(&cursor).map(|s| &s.items) {
                    Some(RedisCollectionOverflowItems::Set(items)) => !items.is_empty(),
                    _ => false,
                }
            };
            let page_bytes: usize = items.iter().map(set_item_page_bytes).sum();
            if items.len() >= count || next == 0 || has_more_buffered || page_bytes >= COLLECTION_PAGE_MAX_BYTES {
                return Ok((next, items));
            }
            (next, items)
        }
        None => (cursor, Vec::new()),
    };

    let (scan_cursor, previous_session) = if buffered_cursor == cursor {
        take_collection_scan_cursor(scope, key, cursor, RedisCollectionOverflowKind::Set, filter_query).await?
    } else {
        (buffered_cursor, None)
    };

    if cursor != 0 && scan_cursor == 0 {
        return Ok((0, items));
    }

    let needed = count.saturating_sub(items.len()).max(1);
    let scanned = if let Some(query) = filter_query {
        sscan_filtered_page_raw(con, key, scan_cursor, needed, query).await
    } else {
        sscan_page_raw(con, key, scan_cursor, needed).await
    };

    let (next_cursor, scanned_items) = match scanned {
        Ok(page) => page,
        Err(error) => {
            if let Some(mut session) = previous_session {
                if !items.is_empty() {
                    session.items = RedisCollectionOverflowItems::Set(items);
                }
                collection_overflow_sessions().lock().await.reinsert(cursor, session);
            }
            return Err(error);
        }
    };

    let mut seen: HashSet<String> = items.iter().map(|item| item.member.raw_base64.clone()).collect();
    for item in scanned_items {
        if seen.insert(item.member.raw_base64.clone()) {
            items.push(item);
        }
    }

    let page_len = budgeted_page_len(&items, count, set_item_page_bytes);
    let next_cursor = store_set_overflow_page(scope, key, &mut items, page_len, next_cursor, filter_query).await;
    Ok((next_cursor, items))
}

async fn take_hash_overflow_page(
    scope: &RedisOperationScope,
    key: &[u8],
    cursor: u64,
    count: usize,
    filter_query: Option<&str>,
) -> Option<(u64, Vec<RedisHashItem>)> {
    if cursor == 0 {
        return None;
    }

    let mut sessions = collection_overflow_sessions().lock().await;
    let mut session =
        sessions.take_matching(cursor, scope, key, RedisCollectionOverflowKind::Hash, filter_query, None)?;
    let page = match &mut session.items {
        RedisCollectionOverflowItems::Hash(items) if !items.is_empty() => {
            take_vec_page(items, budgeted_page_len(items, count, hash_item_page_bytes))
        }
        RedisCollectionOverflowItems::Hash(_) => {
            sessions.reinsert(cursor, session);
            return None;
        }
        RedisCollectionOverflowItems::Set(_) => return None,
    };
    let has_buffered_items = match &session.items {
        RedisCollectionOverflowItems::Hash(items) => !items.is_empty(),
        RedisCollectionOverflowItems::Set(_) => false,
    };
    let retain_cursor = has_buffered_items || session.followup_cursor != 0;
    let next_cursor = if retain_cursor { cursor } else { session.followup_cursor };
    if retain_cursor {
        sessions.reinsert(cursor, session);
    }
    Some((next_cursor, page))
}

async fn take_set_overflow_page(
    scope: &RedisOperationScope,
    key: &[u8],
    cursor: u64,
    count: usize,
    filter_query: Option<&str>,
) -> Option<(u64, Vec<RedisSetItem>)> {
    if cursor == 0 {
        return None;
    }

    let mut sessions = collection_overflow_sessions().lock().await;
    let mut session =
        sessions.take_matching(cursor, scope, key, RedisCollectionOverflowKind::Set, filter_query, None)?;
    let page = match &mut session.items {
        RedisCollectionOverflowItems::Set(items) if !items.is_empty() => {
            take_vec_page(items, budgeted_page_len(items, count, set_item_page_bytes))
        }
        RedisCollectionOverflowItems::Set(_) => {
            sessions.reinsert(cursor, session);
            return None;
        }
        RedisCollectionOverflowItems::Hash(_) => return None,
    };
    let has_buffered_items = match &session.items {
        RedisCollectionOverflowItems::Set(items) => !items.is_empty(),
        RedisCollectionOverflowItems::Hash(_) => false,
    };
    let retain_cursor = has_buffered_items || session.followup_cursor != 0;
    let next_cursor = if retain_cursor { cursor } else { session.followup_cursor };
    if retain_cursor {
        sessions.reinsert(cursor, session);
    }
    Some((next_cursor, page))
}

async fn store_hash_overflow_page(
    scope: &RedisOperationScope,
    key: &[u8],
    items: &mut Vec<RedisHashItem>,
    count: usize,
    followup_cursor: u64,
    filter_query: Option<&str>,
) -> u64 {
    if items.len() <= count && (followup_cursor == 0 || scope == &RedisOperationScope::default()) {
        return followup_cursor;
    }

    let overflow = items.split_off(count.min(items.len()));
    let session = RedisCollectionOverflowSession {
        scope: scope.clone(),
        key: key.to_vec(),
        kind: RedisCollectionOverflowKind::Hash,
        filter: filter_query.map(str::to_string),
        sort_direction: None,
        followup_cursor,
        items: RedisCollectionOverflowItems::Hash(overflow),
        last_used: Instant::now(),
    };
    collection_overflow_sessions().lock().await.insert(session)
}

async fn store_set_overflow_page(
    scope: &RedisOperationScope,
    key: &[u8],
    items: &mut Vec<RedisSetItem>,
    count: usize,
    followup_cursor: u64,
    filter_query: Option<&str>,
) -> u64 {
    if items.len() <= count && (followup_cursor == 0 || scope == &RedisOperationScope::default()) {
        return followup_cursor;
    }

    let overflow = items.split_off(count.min(items.len()));
    let session = RedisCollectionOverflowSession {
        scope: scope.clone(),
        key: key.to_vec(),
        kind: RedisCollectionOverflowKind::Set,
        filter: filter_query.map(str::to_string),
        sort_direction: None,
        followup_cursor,
        items: RedisCollectionOverflowItems::Set(overflow),
        last_used: Instant::now(),
    };
    collection_overflow_sessions().lock().await.insert(session)
}

async fn take_collection_scan_cursor(
    scope: &RedisOperationScope,
    key: &[u8],
    cursor: u64,
    kind: RedisCollectionOverflowKind,
    filter_query: Option<&str>,
) -> Result<(u64, Option<RedisCollectionOverflowSession>), String> {
    if cursor == 0 {
        return Ok((0, None));
    }
    if let Some(session) =
        collection_overflow_sessions().lock().await.take_matching(cursor, scope, key, kind, filter_query, None)
    {
        return Ok((session.followup_cursor, Some(session)));
    }
    if cursor >= COLLECTION_OVERFLOW_CURSOR_START || scope != &RedisOperationScope::default() {
        return Err("Collection cursor is invalid, expired, or belongs to a different connection/database".to_string());
    }
    Ok((cursor, None))
}

/// How many leading items fit in one page, honouring both the item count and the byte budget.
///
/// Always returns at least one item so a member larger than the whole budget still loads (and
/// pagination cannot stall), and never more than `items.len()`.
fn budgeted_page_len<T>(items: &[T], count: usize, size_of: impl Fn(&T) -> usize) -> usize {
    let limit = count.max(1).min(items.len());
    let mut used = 0usize;
    for (index, item) in items.iter().take(limit).enumerate() {
        used = used.saturating_add(size_of(item));
        if used > COLLECTION_PAGE_MAX_BYTES {
            return index.max(1);
        }
    }
    limit
}

fn blob_page_bytes(blob: &RedisBlob) -> usize {
    blob.raw_base64.len()
}

fn hash_item_page_bytes(item: &RedisHashItem) -> usize {
    blob_page_bytes(&item.field) + blob_page_bytes(&item.value)
}

fn set_item_page_bytes(item: &RedisSetItem) -> usize {
    blob_page_bytes(&item.member)
}

fn list_item_page_bytes(item: &RedisListItem) -> usize {
    blob_page_bytes(&item.value)
}

fn zset_item_page_bytes(item: &RedisZsetItem) -> usize {
    blob_page_bytes(&item.member) + item.score.len()
}

fn take_vec_page<T>(items: &mut Vec<T>, count: usize) -> Vec<T> {
    let page_size = items.len().min(count.max(1));
    let overflow = items.split_off(page_size);
    std::mem::replace(items, overflow)
}

async fn attach_hash_field_ttls<C>(con: &mut C, key: &[u8], items: &mut [RedisHashItem]) -> Result<(), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    if items.is_empty() {
        return Ok(());
    }

    let fields = items
        .iter()
        .map(|item| {
            base64::engine::general_purpose::STANDARD
                .decode(&item.field.raw_base64)
                .map_err(|error| format!("Invalid Redis hash field encoding: {error}"))
        })
        .collect::<Result<Vec<_>, _>>()?;

    // Redis < 7.4 echoes command arguments verbatim in unknown-command errors.
    // Binary arguments can make that RESP error invalid UTF-8 (or inject CRLF),
    // so redis-rs fails to parse it before the optional-error fallback can run.
    // Discover support using ASCII-only arguments before sending unsafe bytes.
    let unsafe_error_arg =
        |bytes: &[u8]| std::str::from_utf8(bytes).is_err() || bytes.windows(2).any(|pair| pair == b"\r\n");
    if unsafe_error_arg(key) || fields.iter().any(|field| unsafe_error_arg(field)) {
        let info: RedisRawValue = match redis::cmd("COMMAND").arg("INFO").arg("HTTL").query_async(con).await {
            Ok(info) => info,
            Err(error) if is_optional_hash_field_expiry_error(&error) => return Ok(()),
            Err(error) => return Err(error.to_string()),
        };
        if matches!(info, RedisRawValue::Nil)
            || matches!(&info, RedisRawValue::Array(commands) if commands.is_empty() || matches!(commands.first(), Some(RedisRawValue::Nil)))
        {
            return Ok(());
        }
    }

    let mut command = redis::cmd("HTTL");
    command.arg(key).arg("FIELDS").arg(fields.len());
    for field in fields {
        command.arg(field);
    }

    let raw: RedisRawValue = match command.query_async(con).await {
        Ok(raw) => raw,
        Err(error) if is_optional_hash_field_expiry_error(&error) => return Ok(()),
        Err(error) => return Err(error.to_string()),
    };
    if matches!(raw, RedisRawValue::Nil) {
        return Ok(());
    }
    let RedisRawValue::Array(values) = raw else {
        return Ok(());
    };
    if values.len() != items.len() {
        return Ok(());
    }
    for (item, value) in items.iter_mut().zip(values) {
        let Some(ttl) = redis_value_to_string(value).and_then(|value| value.parse::<i64>().ok()) else {
            return Ok(());
        };
        item.field_ttl = (ttl != -2).then_some(ttl);
    }
    Ok(())
}

async fn read_hash_field_ttl<C>(con: &mut C, key: &[u8], field: &[u8]) -> Result<Option<i64>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let raw: RedisRawValue = match redis::cmd("HTTL").arg(key).arg("FIELDS").arg(1).arg(field).query_async(con).await {
        Ok(raw) => raw,
        Err(error) if is_optional_hash_field_expiry_error(&error) => return Ok(None),
        Err(error) => return Err(error.to_string()),
    };
    if matches!(raw, RedisRawValue::Nil) {
        return Ok(None);
    }
    let RedisRawValue::Array(mut values) = raw else {
        return Ok(None);
    };
    let Some(ttl) = values.pop().and_then(redis_value_to_string).and_then(|value| value.parse::<i64>().ok()) else {
        return Ok(None);
    };
    Ok((ttl >= 0).then_some(ttl))
}

fn is_optional_hash_field_expiry_error(error: &redis::RedisError) -> bool {
    let detail = error.detail().unwrap_or_default().to_ascii_lowercase();
    detail.contains("unknown command")
        || detail.contains("unknown redis command")
        || detail.contains("unsupported")
        || detail.contains("syntax error")
        || detail.contains("noperm")
        || detail.contains("no permission")
        || detail == "invalid argument: hash field expiration is not supported by legacy hash encoding"
}

fn blob_matches_query(blob: &RedisBlob, lowered_query: &str) -> bool {
    redis_blob_display_text(blob).to_lowercase().contains(lowered_query)
}

fn bytes_match_query(bytes: &[u8], lowered_query: &str) -> bool {
    // Match the same text as redis_blob_display_text, including binary escapes.
    match std::str::from_utf8(bytes) {
        Ok(text) => text.to_lowercase().contains(lowered_query),
        Err(_) => redis_bytes_to_display(bytes).to_lowercase().contains(lowered_query),
    }
}

async fn sscan_page_raw<C>(
    con: &mut C,
    key: &[u8],
    cursor: u64,
    count: usize,
) -> Result<(u64, Vec<RedisSetItem>), String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let raw: RedisRawValue = redis::cmd("SSCAN")
        .arg(key)
        .arg(cursor)
        .arg("COUNT")
        .arg(count)
        .query_async(con)
        .await
        .map_err(|e| e.to_string())?;
    parse_scan_members(raw)
}

async fn zrange_page_raw<C>(
    con: &mut C,
    key: &[u8],
    start: i64,
    end: i64,
    descending: bool,
) -> Result<Vec<RedisZsetItem>, String>
where
    C: ConnectionLike + Send + Sync + Unpin,
{
    let command = if descending { "ZREVRANGE" } else { "ZRANGE" };
    let raw: RedisRawValue = redis::cmd(command)
        .arg(key)
        .arg(start)
        .arg(end)
        .arg("WITHSCORES")
        .query_async(con)
        .await
        .map_err(|e| e.to_string())?;

    let RedisRawValue::Array(entries) = raw else {
        return Err("Invalid ZRANGE response".to_string());
    };
    if entries.len() % 2 != 0 {
        return Err("Invalid ZRANGE response".to_string());
    }

    let mut items = Vec::with_capacity(entries.len() / 2);
    for pair in entries.chunks_exact(2) {
        let member = redis_value_to_bytes(pair[0].clone())
            .map(|bytes| redis_blob_from_bytes(&bytes))
            .ok_or_else(|| "Invalid ZRANGE member payload".to_string())?;
        let score = redis_value_to_string(pair[1].clone()).ok_or_else(|| "Invalid ZRANGE score".to_string())?;
        items.push(RedisZsetItem { score, member });
    }
    Ok(items)
}

fn parse_scan_hash_entries(
    raw: RedisRawValue,
    lowered_query: Option<&str>,
) -> Result<(u64, Vec<RedisHashItem>), String> {
    let RedisRawValue::Array(mut parts) = raw else {
        return Err("Invalid SCAN response".to_string());
    };
    if parts.len() != 2 {
        return Err("Invalid SCAN response".to_string());
    }

    let entries = parts.pop().unwrap();
    let cursor = redis_value_to_string(parts.pop().unwrap())
        .ok_or("Invalid cursor")?
        .parse::<u64>()
        .map_err(|_| "Invalid cursor".to_string())?;

    let RedisRawValue::Array(entries) = entries else {
        return Err("Invalid SCAN entries".to_string());
    };

    let mut items = Vec::new();
    let mut iter = entries.into_iter();
    while let Some(field) = iter.next() {
        let Some(value) = iter.next() else { break };
        let field = redis_value_to_bytes(field).ok_or_else(|| "Invalid hash field payload".to_string())?;
        let value = redis_value_to_bytes(value).ok_or_else(|| "Invalid hash value payload".to_string())?;
        if lowered_query.is_some_and(|query| !bytes_match_query(&field, query) && !bytes_match_query(&value, query)) {
            continue;
        }
        let field = redis_blob_from_bytes(&field);
        let value = redis_blob_from_bytes(&value);
        items.push(RedisHashItem { field, value, field_ttl: None });
    }

    Ok((cursor, items))
}

fn parse_scan_members(raw: RedisRawValue) -> Result<(u64, Vec<RedisSetItem>), String> {
    let RedisRawValue::Array(parts) = raw else {
        return Err("Invalid SCAN response".to_string());
    };
    if parts.len() != 2 {
        return Err("Invalid SCAN response".to_string());
    }

    let cursor = redis_value_to_string(parts[0].clone())
        .ok_or("Invalid cursor")?
        .parse::<u64>()
        .map_err(|_| "Invalid cursor".to_string())?;

    let RedisRawValue::Array(entries) = &parts[1] else {
        return Err("Invalid SCAN entries".to_string());
    };

    let items = entries
        .iter()
        .filter_map(|value| {
            redis_value_to_bytes(value.clone()).map(|bytes| RedisSetItem { member: redis_blob_from_bytes(&bytes) })
        })
        .collect();

    Ok((cursor, items))
}

#[cfg(test)]
mod tests {
    use base64::Engine;
    use std::time::Duration;
    use std::{
        collections::{HashMap, VecDeque},
        future::ready,
        sync::{
            atomic::{AtomicUsize, Ordering},
            Arc, Mutex as StdMutex,
        },
    };

    use super::{
        classify_command, connection_info, decode_cluster_cursor, encode_cluster_cursor, is_redis_auth_error,
        is_redis_command_denied_error, is_redis_json_type, load_redis_tls_certificates, parse_cluster_slots,
        parse_command_argv, parse_database_count, parse_redis_endpoint, parse_scan_keys, parse_stream_consumers,
        parse_stream_entries, parse_stream_groups, parse_stream_pending_entries, redis_auth_candidates,
        redis_blob_display_text, redis_blob_from_bytes, redis_cluster_slot, redis_command_raw_to_json,
        redis_database_index, redis_key_bytes_to_display, redis_key_bytes_to_raw, redis_key_matches_query,
        redis_key_raw_to_bytes, redis_key_value_preview, redis_sentinel_master_endpoint, redis_value_matches_query,
        redis_value_to_bytes, standalone_connection_infos, RedisAuthCandidate, RedisBlob, RedisBlobEncoding,
        RedisClusterSlotRange, RedisCollectionPage, RedisCommandSafety, RedisHashItem, RedisListItem,
        RedisNodeEndpoint, RedisNodeRoute, RedisRawValue, RedisSetItem, RedisStreamConsumer, RedisStreamEntry,
        RedisStreamField, RedisStreamGroup, RedisStreamPendingEntry, RedisValue, RedisValueData, RedisZsetItem,
    };
    use dbx_types::models::connection::ConnectionConfig;
    use redis::{aio::ConnectionLike, Cmd, ConnectionAddr, Pipeline, RedisFuture};

    #[test]
    fn cluster_database_capability_is_strict_and_cluster_specific() {
        use super::ClusterDatabaseCapability as Capability;
        for count in [1, 4, i32::MAX as u32] {
            assert_eq!(
                super::parse_cluster_database_capability(RedisRawValue::Array(vec![
                    bulk("cluster-databases"),
                    bulk(&count.to_string())
                ]))
                .unwrap(),
                Capability::Known(count)
            );
        }
        assert_eq!(
            super::parse_cluster_database_capability(RedisRawValue::Array(vec![])).unwrap(),
            Capability::Unsupported
        );
        assert_eq!(
            super::parse_cluster_database_capability(RedisRawValue::Map(vec![(bulk("cluster-databases"), bulk("4"))]))
                .unwrap(),
            Capability::Known(4)
        );
        for raw in [
            RedisRawValue::Nil,
            RedisRawValue::Array(vec![bulk("databases"), bulk("16")]),
            RedisRawValue::Array(vec![bulk("cluster-databases")]),
            RedisRawValue::Array(vec![bulk("cluster-databases"), bulk("4"), bulk("extra")]),
        ] {
            assert!(super::parse_cluster_database_capability(raw).is_err());
        }
        for count in ["0", "-1", "2147483648", "4294967295", "4294967296", "4.0", " 4", ""] {
            assert!(
                super::parse_cluster_database_capability(RedisRawValue::Array(vec![
                    bulk("cluster-databases"),
                    bulk(count)
                ]))
                .is_err(),
                "{count}"
            );
        }
        assert_eq!(
            super::combine_cluster_database_capabilities(vec![Capability::Known(4), Capability::Known(4)]).unwrap(),
            Capability::Known(4)
        );
        assert!(super::combine_cluster_database_capabilities(vec![Capability::Known(4), Capability::Known(8)]).is_err());
        assert!(
            super::combine_cluster_database_capabilities(vec![Capability::Known(1), Capability::Unsupported]).is_err()
        );
        assert!(super::combine_cluster_database_capabilities(vec![]).is_err());
        assert_eq!(
            super::combine_cluster_database_capabilities(vec![
                Capability::Known(4),
                Capability::Unknown("node: NOPERM".to_string())
            ])
            .unwrap(),
            Capability::Unknown("node: NOPERM".to_string())
        );
        for raw in [
            RedisRawValue::Double(4.0),
            RedisRawValue::Boolean(true),
            RedisRawValue::Int(4),
            RedisRawValue::VerbatimString { format: redis::VerbatimFormat::Text, text: "4".to_string() },
            RedisRawValue::Nil,
            RedisRawValue::Okay,
            RedisRawValue::BulkString(vec![0xff]),
        ] {
            assert!(super::parse_cluster_database_capability(RedisRawValue::Array(vec![
                bulk("cluster-databases"),
                raw
            ]))
            .is_err());
        }
        assert!(super::parse_cluster_database_capability(RedisRawValue::Map(vec![(
            RedisRawValue::VerbatimString {
                format: redis::VerbatimFormat::Text,
                text: "cluster-databases".to_string()
            },
            bulk("4")
        )]))
        .is_err());
    }

    #[test]
    fn cluster_database_keyspace_counts_require_trustworthy_metadata() {
        assert_eq!(
            super::parse_cluster_keyspace_counts("# Keyspace\r\ndb0:keys=3,expires=0\r\ndb1:keys=2,expires=0\r\n")
                .unwrap(),
            HashMap::from([(0, 3), (1, 2)])
        );
        assert!(super::parse_cluster_keyspace_counts("# Keyspace\r\n").unwrap().is_empty());
        for info in [
            "",
            "db0:keys=3",
            "# Keyspace\r\ndb0:expires=1",
            "# Keyspace\r\ndb0:keys=no",
            "# Keyspace\r\ndb0:keys=1\r\ndb0:keys=2",
        ] {
            assert!(super::parse_cluster_keyspace_counts(info).is_err(), "{info}");
        }
    }

    #[test]
    fn cluster_database_list_limit_is_separate_from_server_configuration_range() {
        assert_eq!(
            super::cluster_database_list_count(&super::ClusterDatabaseCapability::Known(10_000)).unwrap(),
            10_000
        );
        let error = super::cluster_database_list_count(&super::ClusterDatabaseCapability::Known(10_001)).unwrap_err();
        assert!(error.contains("10001"));
        assert!(error.contains("10000"));
        assert!(error.contains("DBX"));
        assert!(super::parse_cluster_database_capability(RedisRawValue::Array(vec![
            bulk("cluster-databases"),
            bulk("10001")
        ]))
        .is_ok());
    }

    #[tokio::test]
    async fn cluster_database_bounds_and_db_zero_do_not_require_network() {
        let super::RedisConnection::Cluster(pool) = super::redis_connection_test_stub() else { unreachable!() };
        *pool.database_capability.lock().await = Some(super::ClusterDatabaseCapability::Known(4));
        super::ensure_cluster_database(&pool, 3).await.unwrap();
        assert!(super::ensure_cluster_database(&pool, 4).await.unwrap_err().contains("range"));
        *pool.database_capability.lock().await = Some(super::ClusterDatabaseCapability::Unknown("denied".to_string()));
        super::ensure_cluster_database(&pool, 0).await.unwrap();
        assert_eq!(super::cluster_database_diagnostic(&pool).await.as_deref(), Some("denied"));
    }

    #[test]
    fn cluster_node_connection_options_keep_database_transport_auth_and_tls() {
        let super::RedisConnection::Cluster(mut pool) = super::redis_connection_test_stub() else { unreachable!() };
        let advertised = RedisNodeEndpoint { host: "remote.invalid".to_string(), port: 7000 };
        pool.node_routes.push(RedisNodeRoute {
            advertised: advertised.clone(),
            connect: RedisNodeEndpoint { host: "127.0.0.1".to_string(), port: 17000 },
        });
        pool.username = "acl-user".to_string();
        pool.password = "acl-password".to_string();
        let info = super::cluster_node_connection_info(&pool, &advertised, 3).unwrap();
        assert!(matches!(info.addr(), ConnectionAddr::Tcp(host, 17000) if host == "127.0.0.1"));
        assert_eq!(info.redis_settings().db(), 3);
        assert_eq!(info.redis_settings().username(), Some("acl-user"));
        assert_eq!(info.redis_settings().password(), Some("acl-password"));
        pool.tls = true;
        pool.tls_insecure = true;
        let info = super::cluster_node_connection_info(&pool, &advertised, 2).unwrap();
        assert!(
            matches!(info.addr(), ConnectionAddr::TcpTls { host, port: 17000, insecure: true, .. } if host == "127.0.0.1")
        );
        assert_eq!(info.redis_settings().db(), 2);
        let fallback = super::cluster_node_connection_info(
            &pool,
            &RedisNodeEndpoint { host: "unmapped.invalid".to_string(), port: 7001 },
            2,
        )
        .unwrap();
        assert!(
            matches!(fallback.addr(), ConnectionAddr::TcpTls { host, port: 7001, insecure: true, .. } if host == "unmapped.invalid")
        );
        assert_eq!(fallback.redis_settings().db(), 2);
    }

    #[tokio::test]
    async fn cluster_value_scan_counts_all_masters_and_preserves_total_on_continuation() {
        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
        let masters = vec![
            RedisNodeEndpoint { host: "node-a".to_string(), port: 1 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 2 },
            RedisNodeEndpoint { host: "node-c".to_string(), port: 3 },
        ];
        let mut connections = HashMap::from([
            (
                masters[0].clone(),
                FakeRedisConnection::new(vec![
                    RedisRawValue::Int(10),
                    scan_response("0", vec!["needle:a"]),
                    bulk("string"),
                ]),
            ),
            (masters[1].clone(), FakeRedisConnection::new(vec![RedisRawValue::Int(20)])),
            (masters[2].clone(), FakeRedisConnection::new(vec![RedisRawValue::Int(30)])),
        ]);
        let first = super::scan_cluster_values_page_with(
            &sessions,
            || ready(Ok(masters.clone())),
            |endpoint| ready(connections.remove(&endpoint).ok_or("unexpected reconnect".to_string())),
            1,
            0,
            "*",
            "needle",
            true,
            1,
        )
        .await
        .unwrap();
        assert_eq!(first.total_keys, 60);
        assert_eq!(first.keys.len(), 1);
        assert_ne!(first.cursor, 0);
        let next = super::scan_cluster_values_page_with(
            &sessions,
            || ready(Err("unexpected rediscovery".to_string())),
            |_| ready(Ok(FakeRedisConnection::new(vec![scan_response("0", vec![])]))),
            1,
            first.cursor,
            "*",
            "needle",
            true,
            1,
        )
        .await
        .unwrap();
        assert_eq!(next.total_keys, 60);
        assert_eq!(next.cursor, 0);
    }

    #[tokio::test]
    async fn cluster_value_scan_count_denial_does_not_prevent_search() {
        let mut store = super::RedisClusterScanSessions::default();
        let previous = store.insert(None, super::RedisClusterKeyScanSession::new(vec![], "existing"));
        let sessions = tokio::sync::Mutex::new(store);
        let master = RedisNodeEndpoint { host: "count-node".to_string(), port: 7001 };
        let page = super::scan_cluster_values_page_with(
            &sessions,
            || ready(Ok(vec![master.clone()])),
            |_| {
                ready(Ok(FakeRedisConnection::with_results(vec![
                    Err(noperm("dbsize")),
                    Ok(scan_response("0", vec!["needle:a"])),
                    Ok(bulk("string")),
                    Ok(RedisRawValue::Int(-1)),
                    Ok(bulk("needle value")),
                ])))
            },
            1,
            0,
            "*",
            "needle",
            false,
            1,
        )
        .await
        .unwrap();
        assert_eq!(page.total_keys, 0);
        assert_eq!(page.keys.len(), 1);
        assert_eq!(page.keys[0].value_preview, "needle value");
        assert_eq!(page.cursor, 0);
        let sessions = sessions.lock().await;
        assert_eq!(sessions.entries.len(), 1);
        assert!(sessions.entries.contains_key(&previous));
    }

    #[tokio::test]
    async fn cluster_value_scan_retries_count_connection_but_propagates_scan_failures() {
        for scan_failure in [false, true] {
            let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
            let master = RedisNodeEndpoint { host: "count-node".to_string(), port: 7001 };
            let mut attempts = 0;
            let result = super::scan_cluster_values_page_with(
                &sessions,
                || ready(Ok(vec![master.clone()])),
                |_| {
                    attempts += 1;
                    ready(if attempts == 1 {
                        Err("count connection unavailable".to_string())
                    } else if scan_failure {
                        Ok(FakeRedisConnection::with_results(vec![Err(noperm("scan"))]))
                    } else {
                        Ok(FakeRedisConnection::new(vec![scan_response("0", vec!["needle:a"]), bulk("string")]))
                    })
                },
                1,
                0,
                "*",
                "needle",
                true,
                1,
            )
            .await;
            assert_eq!(attempts, 2);
            if scan_failure {
                assert_eq!(result.unwrap_err(), noperm("scan").to_string());
            } else {
                let page = result.unwrap();
                assert_eq!(page.total_keys, 0);
                assert_eq!(page.keys.len(), 1);
            }
            assert!(sessions.lock().await.entries.is_empty());
        }

        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
        let mut attempts = 0;
        let error = super::scan_cluster_values_page_with::<FakeRedisConnection, _, _, _, _>(
            &sessions,
            || ready(Ok(vec![RedisNodeEndpoint { host: "unavailable".to_string(), port: 7001 }])),
            |_| {
                attempts += 1;
                ready(Err("scan connection unavailable".to_string()))
            },
            1,
            0,
            "*",
            "needle",
            true,
            1,
        )
        .await
        .unwrap_err();
        assert_eq!(attempts, 2);
        assert_eq!(error, "scan connection unavailable");
        assert!(sessions.lock().await.entries.is_empty());
    }

    #[tokio::test]
    async fn cluster_key_cursor_rejects_wrong_database_without_consuming_session() {
        let mut store = super::RedisClusterScanSessions::default();
        let mut session =
            super::RedisClusterKeyScanSession::new(vec![RedisNodeEndpoint { host: "test".to_string(), port: 1 }], "*");
        session.db = 1;
        let cursor = store.insert(None, session);
        let sessions = tokio::sync::Mutex::new(store);
        let result = super::scan_cluster_keys_batch_in_db_with::<FakeRedisConnection, _, _, _, _>(
            &sessions,
            || ready(Err("unexpected discovery".to_string())),
            |_| ready(Err("unexpected connection".to_string())),
            0,
            cursor,
            "*",
            1,
            1,
            false,
        )
        .await;
        assert_eq!(result.unwrap_err(), super::INVALID_CLUSTER_SCAN_CURSOR_ERROR);
        assert!(sessions.lock().await.entries.contains_key(&cursor));
        let result = super::scan_cluster_keys_batch_in_db_with(
            &sessions,
            || ready(Err("unexpected discovery".to_string())),
            |_| ready(Ok(FakeRedisConnection::new(vec![scan_response("0", vec![])]))),
            1,
            cursor,
            "*",
            1,
            1,
            false,
        )
        .await
        .unwrap();
        assert_eq!(result.cursor, 0);
    }

    #[tokio::test]
    async fn cluster_value_cursor_rejects_scope_and_filter_mismatch_and_restores_on_failure() {
        let mut store = super::RedisClusterScanSessions::default();
        let mut session =
            super::RedisClusterKeyScanSession::new(vec![RedisNodeEndpoint { host: "test".to_string(), port: 1 }], "*");
        session.db = 1;
        session.value_filter = Some(("needle".to_string(), false));
        session.node_cursors[0] = 42;
        let cursor = store.insert(None, session);
        let sessions = tokio::sync::Mutex::new(store);
        for (db, query, include_keys, token) in [
            (0, "needle", false, cursor),
            (1, "other", false, cursor),
            (1, "needle", true, cursor),
            (1, "needle", false, cursor + 1_000_000),
        ] {
            let error = super::scan_cluster_values_page_with::<FakeRedisConnection, _, _, _, _>(
                &sessions,
                || ready(Err("unexpected discovery".to_string())),
                |_| ready(Err("unexpected connection".to_string())),
                db,
                token,
                "*",
                query,
                include_keys,
                1,
            )
            .await
            .unwrap_err();
            assert_eq!(error, super::INVALID_CLUSTER_SCAN_CURSOR_ERROR);
            assert_eq!(sessions.lock().await.entries.get(&cursor).unwrap().node_cursors[0], 42);
        }
        let error = super::scan_cluster_values_page_with::<FakeRedisConnection, _, _, _, _>(
            &sessions,
            || ready(Err("unexpected discovery".to_string())),
            |_| ready(Err("network failed".to_string())),
            1,
            cursor,
            "*",
            "needle",
            false,
            1,
        )
        .await
        .unwrap_err();
        assert_eq!(error, "network failed");
        assert_eq!(sessions.lock().await.entries.get(&cursor).unwrap().node_cursors[0], 42);
        let result = super::scan_cluster_values_page_with(
            &sessions,
            || ready(Err("unexpected discovery".to_string())),
            |_| ready(Ok(FakeRedisConnection::new(vec![scan_response("0", vec![])]))),
            1,
            cursor,
            "*",
            "needle",
            false,
            1,
        )
        .await
        .unwrap();
        assert_eq!(result.cursor, 0);
    }

    #[test]
    fn cluster_cursor_ids_do_not_collide_across_connection_pools() {
        let mut first = super::RedisClusterScanSessions::default();
        let mut second = super::RedisClusterScanSessions::default();
        let session = super::RedisClusterKeyScanSession::new(vec![], "*");
        let first_id = first.insert(None, session.clone());
        let second_id = second.insert(None, session);
        assert_ne!(first_id, second_id);
        assert!(second.take(first_id).is_none());
        assert!(second.take(second_id).is_some());
    }

    #[tokio::test]
    async fn collection_overflow_is_connection_and_database_scoped() {
        let scope = super::RedisOperationScope { connection_id: "overflow-scope-test".to_string(), db: 1 };
        let pairs = (0..202).map(|index| (format!("field:{index}"), format!("value:{index}"))).collect();
        let mut con = FakeRedisConnection::new(vec![
            bulk("hash"),
            RedisRawValue::Int(-1),
            RedisRawValue::Int(202),
            hscan_response_owned("0", pairs),
            httl_response(200, -1),
        ]);
        let value = super::get_value_scoped(&mut con, b"scoped-hash", &scope).await.unwrap();
        let RedisValueData::Hash { scan_cursor: Some(cursor), .. } = value.data else {
            panic!("expected overflow");
        };
        for wrong_scope in [
            super::RedisOperationScope { db: 0, ..scope.clone() },
            super::RedisOperationScope { connection_id: "another-connection".to_string(), ..scope.clone() },
        ] {
            let mut wrong = FakeRedisConnection::new(vec![]);
            assert!(super::load_more_collection_scoped(
                &mut wrong,
                b"scoped-hash",
                "hash",
                cursor,
                1,
                None,
                None,
                &wrong_scope
            )
            .await
            .is_err());
            assert!(wrong.commands.is_empty());
        }
        let mut continuation = FakeRedisConnection::new(vec![httl_response(1, 30)]);
        let page = super::load_more_collection_scoped(
            &mut continuation,
            b"scoped-hash",
            "hash",
            cursor,
            1,
            None,
            None,
            &scope,
        )
        .await
        .unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = page else {
            panic!("expected hash");
        };
        assert_eq!(items[0].field, redis_blob_from_bytes(b"field:200"));
        assert_eq!(items[0].field_ttl, Some(30));
        assert_eq!(scan_cursor, Some(cursor));
        assert_eq!(continuation.command_count("HSCAN"), 0);
        super::collection_overflow_sessions().lock().await.entries.get_mut(&cursor).unwrap().last_used =
            std::time::Instant::now() - super::COLLECTION_OVERFLOW_SESSION_TTL;
        let mut expired = FakeRedisConnection::new(vec![]);
        assert!(super::load_more_collection_scoped(
            &mut expired,
            b"scoped-hash",
            "hash",
            cursor,
            1,
            None,
            None,
            &scope
        )
        .await
        .is_err());
        assert!(expired.commands.is_empty());
    }

    /// Replays the standalone-Redis pagination sequence from issue #12640: a large
    /// hash is read once through the scoped value API, then continued through the
    /// scoped load-more API with the same scope (the pairing the desktop app uses).
    /// Every field must eventually arrive exactly once, and a continuation under a
    /// different (unseoped) scope must fail instead of restarting the walk.
    #[tokio::test]
    async fn scoped_hash_pagination_walks_large_collections_without_repeating_the_first_page() {
        const FIELDS: usize = 4000;
        const PAGE: usize = 200;
        let scope = super::RedisOperationScope { connection_id: "issue-12640-standalone".to_string(), db: 0 };

        // Real HSCAN cursors: one batch of `PAGE` fields per server round trip.
        let mut responses = vec![bulk("hash"), RedisRawValue::Int(-1), RedisRawValue::Int(FIELDS as i64)];
        let pages = FIELDS.div_ceil(PAGE);
        for page in 0..pages {
            let cursor = if page + 1 == pages { "0".to_string() } else { (page + 1).to_string() };
            let pairs = (page * PAGE..((page + 1) * PAGE).min(FIELDS))
                .map(|index| (format!("field:{index}"), format!("value:{index}")))
                .collect();
            responses.push(hscan_response_owned(&cursor, pairs));
            responses.push(httl_response(PAGE, -1));
        }
        let mut con = FakeRedisConnection::new(responses);

        let value = super::get_value_scoped(&mut con, b"issue-12640-hash", &scope).await.unwrap();
        let RedisValueData::Hash { items: mut seen, scan_cursor, total } = value.data else {
            panic!("expected hash");
        };
        assert_eq!(total, FIELDS as u64);
        assert_eq!(seen.len(), PAGE, "the first page defaults to the configured page size");
        let mut cursor = scan_cursor.expect("a 4000-field hash must offer a continuation");
        assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START, "the continuation is an overflow session marker");

        // The old desktop path continued under the default (unseoped) connection,
        // which rejected the marker and stopped pagination at the first page.
        let mut mismatched = FakeRedisConnection::new(vec![]);
        let error = super::load_more_collection(&mut mismatched, b"issue-12640-hash", "hash", cursor, PAGE, None, None)
            .await
            .unwrap_err();
        assert!(error.contains("invalid, expired"), "{error}");
        assert!(mismatched.commands.is_empty(), "a foreign cursor must not reach the server");

        let mut pages_seen = 1;
        while cursor != 0 {
            let page = super::load_more_collection_scoped(
                &mut con,
                b"issue-12640-hash",
                "hash",
                cursor,
                PAGE,
                None,
                None,
                &scope,
            )
            .await
            .unwrap();
            let RedisCollectionPage::Hash { items, scan_cursor: next } = page else {
                panic!("expected hash");
            };
            seen.extend(items);
            pages_seen += 1;
            assert!(pages_seen <= pages, "pagination must terminate");
            match next {
                Some(next) => {
                    assert_ne!(next, cursor, "each page must continue with a fresh marker");
                    cursor = next;
                }
                None => break,
            }
        }

        assert_eq!(pages_seen, pages);
        assert_eq!(seen.len(), FIELDS);
        let unique: std::collections::HashSet<_> = seen.iter().map(|item| item.field.raw_base64.clone()).collect();
        assert_eq!(unique.len(), FIELDS, "every field arrives exactly once");
        // Every page came from a fresh HSCAN round trip — no page was re-served from
        // the start of the hash, which is what a foreign or replayed cursor would do.
        assert_eq!(con.command_count("HSCAN"), pages);
    }

    /// Regression test for #12640 follow-up:
    /// In a Redis hash where initial HSCAN returns 201 items (COUNT is a hint), the
    /// initial page takes 200 items and stores 1 item in the overflow session with followup_cursor != 0.
    /// When the user clicks "Load more" (count = 200) for the first time, the driver must NOT return
    /// just the 1 buffered item (200 -> 201). Instead, it must drain the 1 buffered item, continue
    /// scanning the server for the remaining needed items, and return a full page of 200 items (200 -> 400).
    #[tokio::test]
    async fn scoped_hash_pagination_first_load_more_with_overflow_reaches_full_page() {
        const TOTAL_FIELDS: usize = 500;
        const PAGE: usize = 200;
        let scope = super::RedisOperationScope { connection_id: "issue-12640-first-load-more-hash".to_string(), db: 0 };

        let initial_pairs: Vec<(String, String)> =
            (0..201).map(|i| (format!("field:{i}"), format!("value:{i}"))).collect();
        let second_pairs: Vec<(String, String)> =
            (201..401).map(|i| (format!("field:{i}"), format!("value:{i}"))).collect();
        let third_pairs: Vec<(String, String)> =
            (401..500).map(|i| (format!("field:{i}"), format!("value:{i}"))).collect();

        let responses = vec![
            bulk("hash"),
            RedisRawValue::Int(-1),
            RedisRawValue::Int(TOTAL_FIELDS as i64),
            hscan_response_owned("100", initial_pairs),
            httl_response(PAGE, -1),
            hscan_response_owned("200", second_pairs),
            httl_response(PAGE, -1),
            hscan_response_owned("0", third_pairs),
            httl_response(100, -1),
        ];
        let mut con = FakeRedisConnection::new(responses);

        // Initial read: 200 items
        let value = super::get_value_scoped(&mut con, b"hash-key", &scope).await.unwrap();
        let RedisValueData::Hash { items: first_page, scan_cursor, total } = value.data else {
            panic!("expected hash");
        };
        assert_eq!(total, TOTAL_FIELDS as u64);
        assert_eq!(first_page.len(), PAGE);
        assert_eq!(redis_blob_display_text(&first_page[0].field), "field:0");
        assert_eq!(redis_blob_display_text(&first_page[199].field), "field:199");
        let cursor = scan_cursor.expect("must offer continuation");
        assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);

        let mut seen = first_page;

        // First Load More: MUST return a full page of 200 items (NOT 1 item)!
        let second_page =
            super::load_more_collection_scoped(&mut con, b"hash-key", "hash", cursor, PAGE, None, None, &scope)
                .await
                .unwrap();
        let RedisCollectionPage::Hash { items: p2_items, scan_cursor: c2 } = second_page else {
            panic!("expected hash page");
        };
        assert_eq!(p2_items.len(), PAGE, "first load_more must return full page of 200 items, not +1");
        assert_eq!(redis_blob_display_text(&p2_items[0].field), "field:200");
        assert_eq!(redis_blob_display_text(&p2_items[199].field), "field:399");
        seen.extend(p2_items);
        assert_eq!(seen.len(), 400, "total loaded after first load_more must be 400 (200 -> 400)");

        let cursor2 = c2.expect("must offer second continuation");
        assert!(cursor2 >= super::COLLECTION_OVERFLOW_CURSOR_START);

        // Second Load More: returns remaining 100 items (400..499)
        let third_page =
            super::load_more_collection_scoped(&mut con, b"hash-key", "hash", cursor2, PAGE, None, None, &scope)
                .await
                .unwrap();
        let RedisCollectionPage::Hash { items: p3_items, scan_cursor: c3 } = third_page else {
            panic!("expected hash page");
        };
        assert_eq!(p3_items.len(), 100);
        assert_eq!(redis_blob_display_text(&p3_items[0].field), "field:400");
        assert_eq!(redis_blob_display_text(&p3_items[99].field), "field:499");
        seen.extend(p3_items);
        assert_eq!(seen.len(), TOTAL_FIELDS);
        assert_eq!(c3, None, "walk is complete");

        let unique: std::collections::HashSet<_> = seen.iter().map(|item| item.field.raw_base64.clone()).collect();
        assert_eq!(unique.len(), TOTAL_FIELDS, "every field arrives exactly once");
        assert_eq!(con.command_count("HSCAN"), 3);
    }

    /// Regression test for #12640 follow-up on Redis sets:
    /// SSCAN returning 201 items on initial load results in 1 item buffered in overflow session.
    /// First load_more must return a full page of 200 items (200 -> 400).
    #[tokio::test]
    async fn scoped_set_pagination_first_load_more_with_overflow_reaches_full_page() {
        const TOTAL_MEMBERS: usize = 500;
        const PAGE: usize = 200;
        let scope = super::RedisOperationScope { connection_id: "issue-12640-first-load-more-set".to_string(), db: 0 };

        let initial_members: Vec<String> = (0..201).map(|i| format!("member:{i}")).collect();
        let second_members: Vec<String> = (201..401).map(|i| format!("member:{i}")).collect();
        let third_members: Vec<String> = (401..500).map(|i| format!("member:{i}")).collect();

        let responses = vec![
            bulk("set"),
            RedisRawValue::Int(-1),
            RedisRawValue::Int(TOTAL_MEMBERS as i64),
            int_scan_response_owned("100", initial_members),
            int_scan_response_owned("200", second_members),
            int_scan_response_owned("0", third_members),
        ];
        let mut con = FakeRedisConnection::new(responses);

        // Initial read: 200 items
        let value = super::get_value_scoped(&mut con, b"set-key", &scope).await.unwrap();
        let RedisValueData::Set { items: first_page, scan_cursor, total } = value.data else {
            panic!("expected set");
        };
        assert_eq!(total, TOTAL_MEMBERS as u64);
        assert_eq!(first_page.len(), PAGE);
        assert_eq!(redis_blob_display_text(&first_page[0].member), "member:0");
        assert_eq!(redis_blob_display_text(&first_page[199].member), "member:199");
        let cursor = scan_cursor.expect("must offer continuation");
        assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);

        let mut seen = first_page;

        // First Load More: MUST return a full page of 200 items (NOT 1 item)!
        let second_page =
            super::load_more_collection_scoped(&mut con, b"set-key", "set", cursor, PAGE, None, None, &scope)
                .await
                .unwrap();
        let RedisCollectionPage::Set { items: p2_items, scan_cursor: c2 } = second_page else {
            panic!("expected set page");
        };
        assert_eq!(p2_items.len(), PAGE, "first load_more must return full page of 200 items, not +1");
        assert_eq!(redis_blob_display_text(&p2_items[0].member), "member:200");
        assert_eq!(redis_blob_display_text(&p2_items[199].member), "member:399");
        seen.extend(p2_items);
        assert_eq!(seen.len(), 400, "total loaded after first load_more must be 400 (200 -> 400)");

        let cursor2 = c2.expect("must offer second continuation");
        assert!(cursor2 >= super::COLLECTION_OVERFLOW_CURSOR_START);

        // Second Load More: returns remaining 100 items (400..499)
        let third_page =
            super::load_more_collection_scoped(&mut con, b"set-key", "set", cursor2, PAGE, None, None, &scope)
                .await
                .unwrap();
        let RedisCollectionPage::Set { items: p3_items, scan_cursor: c3 } = third_page else {
            panic!("expected set page");
        };
        assert_eq!(p3_items.len(), 100);
        assert_eq!(redis_blob_display_text(&p3_items[0].member), "member:400");
        assert_eq!(redis_blob_display_text(&p3_items[99].member), "member:499");
        seen.extend(p3_items);
        assert_eq!(seen.len(), TOTAL_MEMBERS);
        assert_eq!(c3, None, "walk is complete");

        let unique: std::collections::HashSet<_> = seen.iter().map(|item| item.member.raw_base64.clone()).collect();
        assert_eq!(unique.len(), TOTAL_MEMBERS, "every member arrives exactly once");
        assert_eq!(con.command_count("SSCAN"), 3);
    }

    #[tokio::test]
    async fn set_overflow_rejects_unknown_and_foreign_tokens_without_server_scan() {
        let scope = super::RedisOperationScope { connection_id: "set-scope-test".to_string(), db: 1 };
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Array(vec![
            bulk("0"),
            RedisRawValue::Array(vec![bulk("a"), bulk("b")]),
        ])]);
        let page =
            super::load_more_collection_scoped(&mut con, b"scoped-set", "set", 0, 1, None, None, &scope).await.unwrap();
        let RedisCollectionPage::Set { scan_cursor: Some(cursor), .. } = page else {
            panic!("expected set overflow");
        };
        let mut wrong = FakeRedisConnection::new(vec![]);
        for token in [cursor, super::MAX_SAFE_INTEGER_CURSOR] {
            assert!(super::load_more_collection_scoped(
                &mut wrong,
                b"scoped-set",
                "set",
                token,
                1,
                None,
                None,
                &super::RedisOperationScope { db: 0, ..scope.clone() }
            )
            .await
            .is_err());
        }
        assert!(wrong.commands.is_empty());
        let page = super::load_more_collection_scoped(&mut wrong, b"scoped-set", "set", cursor, 1, None, None, &scope)
            .await
            .unwrap();
        let RedisCollectionPage::Set { items, scan_cursor } = page else {
            panic!("expected set");
        };
        assert_eq!(items[0].member, redis_blob_from_bytes(b"b"));
        assert_eq!(scan_cursor, None);
        assert!(wrong.commands.is_empty());
    }

    #[tokio::test]
    async fn native_collection_cursors_reject_foreign_scope_key_kind_and_filter() {
        for key_type in ["hash", "set"] {
            let scope = super::RedisOperationScope { connection_id: format!("native-{key_type}"), db: 1 };
            let response = if key_type == "hash" {
                hscan_response("128", vec![("field", "value")])
            } else {
                scan_response("128", vec!["member"])
            };
            let mut first = FakeRedisConnection::new(vec![response, httl_response(1, -1)]);
            let page = super::load_more_collection_scoped(&mut first, b"key", key_type, 0, 2, None, None, &scope)
                .await
                .unwrap();
            let cursor = match page {
                RedisCollectionPage::Hash { scan_cursor, .. } | RedisCollectionPage::Set { scan_cursor, .. } => {
                    scan_cursor.unwrap()
                }
                _ => panic!("expected collection"),
            };
            assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);
            let mut wrong = FakeRedisConnection::new(vec![]);
            let other_kind = if key_type == "hash" { "set" } else { "hash" };
            for (wrong_scope, wrong_key, wrong_kind, wrong_filter) in [
                (super::RedisOperationScope { db: 0, ..scope.clone() }, b"key".as_slice(), key_type, None),
                (
                    super::RedisOperationScope { connection_id: "foreign".to_string(), ..scope.clone() },
                    b"key".as_slice(),
                    key_type,
                    None,
                ),
                (scope.clone(), b"other".as_slice(), key_type, None),
                (scope.clone(), b"key".as_slice(), other_kind, None),
                (scope.clone(), b"key".as_slice(), key_type, Some("filter")),
            ] {
                assert!(super::load_more_collection_scoped(
                    &mut wrong,
                    wrong_key,
                    wrong_kind,
                    cursor,
                    2,
                    wrong_filter,
                    None,
                    &wrong_scope
                )
                .await
                .is_err());
            }
            assert!(super::load_more_collection_scoped(&mut wrong, b"key", key_type, 128, 2, None, None, &scope)
                .await
                .is_err());
            assert!(wrong.commands.is_empty());
            let response = if key_type == "hash" {
                hscan_response("0", vec![("next", "value")])
            } else {
                scan_response("0", vec!["next"])
            };
            let mut owner = FakeRedisConnection::new(vec![response, httl_response(1, -1)]);
            let page = super::load_more_collection_scoped(&mut owner, b"key", key_type, cursor, 2, None, None, &scope)
                .await
                .unwrap();
            assert!(owner.commands[0].contains("\r\n128\r\n"));
            match page {
                RedisCollectionPage::Hash { items, scan_cursor } => {
                    assert_eq!(items[0].field, redis_blob_from_bytes(b"next"));
                    assert_eq!(scan_cursor, None);
                }
                RedisCollectionPage::Set { items, scan_cursor } => {
                    assert_eq!(items[0].member, redis_blob_from_bytes(b"next"));
                    assert_eq!(scan_cursor, None);
                }
                _ => panic!("expected collection"),
            }
            assert!(!super::collection_overflow_sessions().lock().await.entries.contains_key(&cursor));
        }
    }

    #[tokio::test]
    async fn partial_overflow_fill_restores_buffer_after_scan_failure() {
        for key_type in ["hash", "set"] {
            for connection_id in ["", "retry-partial-overflow"] {
                let scope = super::RedisOperationScope { connection_id: connection_id.into(), db: 0 };
                let response = if key_type == "hash" {
                    hscan_response("128", vec![("one", "value"), ("two", "value")])
                } else {
                    scan_response("128", vec!["one", "two"])
                };
                let mut first = FakeRedisConnection::new(vec![response, httl_response(1, -1)]);
                let page =
                    super::load_more_collection_scoped(&mut first, b"retry-key", key_type, 0, 1, None, None, &scope)
                        .await
                        .unwrap();
                let cursor = match page {
                    RedisCollectionPage::Hash { scan_cursor, .. } | RedisCollectionPage::Set { scan_cursor, .. } => {
                        scan_cursor.unwrap()
                    }
                    _ => panic!("expected collection"),
                };
                let mut failed = FakeRedisConnection::with_results(vec![Err(redis::RedisError::from((
                    redis::ErrorKind::Io,
                    "temporary scan failure",
                )))]);
                assert!(super::load_more_collection_scoped(
                    &mut failed,
                    b"retry-key",
                    key_type,
                    cursor,
                    2,
                    None,
                    None,
                    &scope
                )
                .await
                .is_err());
                assert!(
                    super::collection_overflow_sessions().lock().await.entries.contains_key(&cursor),
                    "lost {key_type} buffer in scope {connection_id:?}"
                );
                let response = if key_type == "hash" {
                    hscan_response("0", vec![("three", "value")])
                } else {
                    scan_response("0", vec!["three"])
                };
                let mut retry = FakeRedisConnection::new(vec![response, httl_response(2, -1)]);
                let page = super::load_more_collection_scoped(
                    &mut retry,
                    b"retry-key",
                    key_type,
                    cursor,
                    2,
                    None,
                    None,
                    &scope,
                )
                .await
                .unwrap();
                let (names, next) = match page {
                    RedisCollectionPage::Hash { items, scan_cursor } => {
                        (items.iter().map(|item| redis_blob_display_text(&item.field)).collect::<Vec<_>>(), scan_cursor)
                    }
                    RedisCollectionPage::Set { items, scan_cursor } => (
                        items.iter().map(|item| redis_blob_display_text(&item.member)).collect::<Vec<_>>(),
                        scan_cursor,
                    ),
                    _ => panic!("expected collection"),
                };
                assert_eq!(names, vec!["two", "three"]);
                assert_eq!(next, None);
                assert!(retry.commands[0].contains("\r\n128\r\n"));
            }
        }
    }

    #[tokio::test]
    async fn scoped_collection_overflow_keeps_followup_scoped_and_retries_failed_scan() {
        for key_type in ["hash", "set"] {
            let scope = super::RedisOperationScope { connection_id: format!("followup-{key_type}"), db: 1 };
            let response = if key_type == "hash" {
                hscan_response("128", vec![("one", "value"), ("two", "value")])
            } else {
                scan_response("128", vec!["one", "two"])
            };
            let mut first = FakeRedisConnection::new(vec![response, httl_response(1, -1)]);
            let page = super::load_more_collection_scoped(&mut first, b"key", key_type, 0, 1, None, None, &scope)
                .await
                .unwrap();
            let cursor = match page {
                RedisCollectionPage::Hash { scan_cursor, .. } | RedisCollectionPage::Set { scan_cursor, .. } => {
                    scan_cursor.unwrap()
                }
                _ => panic!("expected collection"),
            };
            let mut buffered = FakeRedisConnection::new(vec![httl_response(1, -1)]);
            let page =
                super::load_more_collection_scoped(&mut buffered, b"key", key_type, cursor, 1, None, None, &scope)
                    .await
                    .unwrap();
            match page {
                RedisCollectionPage::Hash { scan_cursor, .. } | RedisCollectionPage::Set { scan_cursor, .. } => {
                    assert_eq!(scan_cursor, Some(cursor));
                }
                _ => panic!("expected collection"),
            }
            assert_eq!(buffered.command_count("HSCAN") + buffered.command_count("SSCAN"), 0);
            let mut wrong = FakeRedisConnection::new(vec![]);
            assert!(super::load_more_collection_scoped(
                &mut wrong,
                b"key",
                key_type,
                cursor,
                1,
                None,
                None,
                &super::RedisOperationScope { db: 0, ..scope.clone() }
            )
            .await
            .is_err());
            assert!(wrong.commands.is_empty());
            let mut failed = FakeRedisConnection::with_results(vec![Err(redis::RedisError::from((
                redis::ErrorKind::Io,
                "temporary scan failure",
            )))]);
            assert!(super::load_more_collection_scoped(&mut failed, b"key", key_type, cursor, 1, None, None, &scope)
                .await
                .is_err());
            assert!(super::collection_overflow_sessions().lock().await.entries.contains_key(&cursor));
            let response = if key_type == "hash" {
                hscan_response("0", vec![("three", "value")])
            } else {
                scan_response("0", vec!["three"])
            };
            let mut retry = FakeRedisConnection::new(vec![response, httl_response(1, -1)]);
            let page = super::load_more_collection_scoped(&mut retry, b"key", key_type, cursor, 1, None, None, &scope)
                .await
                .unwrap();
            match page {
                RedisCollectionPage::Hash { items, scan_cursor } => {
                    assert_eq!(items[0].field, redis_blob_from_bytes(b"three"));
                    assert_eq!(scan_cursor, None);
                }
                RedisCollectionPage::Set { items, scan_cursor } => {
                    assert_eq!(items[0].member, redis_blob_from_bytes(b"three"));
                    assert_eq!(scan_cursor, None);
                }
                _ => panic!("expected collection"),
            }
            assert!(retry.commands[0].contains("\r\n128\r\n"));
        }
    }

    #[tokio::test]
    async fn collection_overflow_session_store_and_take_lifecycle() {
        let scope_a = super::RedisOperationScope { connection_id: "conn-alpha".to_string(), db: 2 };
        let scope_b = super::RedisOperationScope { connection_id: "conn-beta".to_string(), db: 2 };
        let scope_a_db3 = super::RedisOperationScope { connection_id: "conn-alpha".to_string(), db: 3 };
        let unscoped = super::RedisOperationScope::default();

        // 1. Direct Hash overflow store & take lifecycle
        {
            let key = b"direct-hash-lifecycle";
            let mut items: Vec<RedisHashItem> = (0..5)
                .map(|i| RedisHashItem {
                    field: text_blob(&format!("f{i}")),
                    value: text_blob(&format!("v{i}")),
                    field_ttl: None,
                })
                .collect();

            // Storing with count = 2 keeps 2 items in `items` and buffers the remaining 3 items.
            let followup_cursor = 888u64;
            let session_cursor =
                super::store_hash_overflow_page(&scope_a, key, &mut items, 2, followup_cursor, None).await;
            assert_eq!(items.len(), 2);
            assert!(session_cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);

            // Scope isolation: foreign connection, foreign db, unscoped default, wrong key, wrong filter, wrong kind
            // must all return None and leave the stored session intact.
            assert!(super::take_hash_overflow_page(&scope_b, key, session_cursor, 2, None).await.is_none());
            assert!(super::take_hash_overflow_page(&scope_a_db3, key, session_cursor, 2, None).await.is_none());
            assert!(super::take_hash_overflow_page(&unscoped, key, session_cursor, 2, None).await.is_none());
            assert!(super::take_hash_overflow_page(&scope_a, b"other-key", session_cursor, 2, None).await.is_none());
            assert!(super::take_hash_overflow_page(&scope_a, key, session_cursor, 2, Some("query")).await.is_none());
            assert!(super::take_set_overflow_page(&scope_a, key, session_cursor, 2, None).await.is_none());

            // First take with matching scope: takes 2 of the 3 buffered items.
            // Since 1 item remains in the session, cursor must be retained.
            let (next_cursor, p1) = super::take_hash_overflow_page(&scope_a, key, session_cursor, 2, None)
                .await
                .expect("take first buffered page");
            assert_eq!(p1.len(), 2);
            assert_eq!(p1[0].field, text_blob("f2"));
            assert_eq!(p1[1].field, text_blob("f3"));
            assert_eq!(next_cursor, session_cursor, "cursor must be retained while buffer has items");

            // Second take: takes the last buffered item.
            // Buffer is now empty, but followup_cursor != 0 and scope != default,
            // so cursor is still retained for the subsequent server scan.
            let (next_cursor, p2) = super::take_hash_overflow_page(&scope_a, key, session_cursor, 2, None)
                .await
                .expect("take remaining buffered page");
            assert_eq!(p2.len(), 1);
            assert_eq!(p2[0].field, text_blob("f4"));
            assert_eq!(next_cursor, session_cursor, "cursor must be retained for followup server scan");

            // Buffer is now empty, so take_hash_overflow_page returns None.
            assert!(super::take_hash_overflow_page(&scope_a, key, session_cursor, 2, None).await.is_none());

            // take_collection_scan_cursor must enforce scope isolation.
            assert!(super::take_collection_scan_cursor(
                &scope_b,
                key,
                session_cursor,
                super::RedisCollectionOverflowKind::Hash,
                None,
            )
            .await
            .is_err());
            assert!(super::take_collection_scan_cursor(
                &unscoped,
                key,
                session_cursor,
                super::RedisCollectionOverflowKind::Hash,
                None,
            )
            .await
            .is_err());

            // Matching scope takes the followup server scan cursor and consumes the session.
            let (server_cursor, session_opt) = super::take_collection_scan_cursor(
                &scope_a,
                key,
                session_cursor,
                super::RedisCollectionOverflowKind::Hash,
                None,
            )
            .await
            .expect("take scan cursor");
            assert_eq!(server_cursor, followup_cursor);
            assert!(session_opt.is_some());

            // Session has been consumed from registry; any subsequent access is rejected.
            assert!(super::take_collection_scan_cursor(
                &scope_a,
                key,
                session_cursor,
                super::RedisCollectionOverflowKind::Hash,
                None,
            )
            .await
            .is_err());
        }

        // 2. Direct Set overflow store & take lifecycle
        {
            let key = b"direct-set-lifecycle";
            let mut items: Vec<RedisSetItem> =
                (0..5).map(|i| RedisSetItem { member: text_blob(&format!("m{i}")) }).collect();

            let followup_cursor = 999u64;
            let session_cursor =
                super::store_set_overflow_page(&scope_a, key, &mut items, 2, followup_cursor, None).await;
            assert_eq!(items.len(), 2);
            assert!(session_cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);

            // Scope isolation
            assert!(super::take_set_overflow_page(&scope_b, key, session_cursor, 2, None).await.is_none());
            assert!(super::take_set_overflow_page(&scope_a_db3, key, session_cursor, 2, None).await.is_none());
            assert!(super::take_set_overflow_page(&unscoped, key, session_cursor, 2, None).await.is_none());
            assert!(super::take_set_overflow_page(&scope_a, b"other-key", session_cursor, 2, None).await.is_none());
            assert!(super::take_hash_overflow_page(&scope_a, key, session_cursor, 2, None).await.is_none());

            // Paging buffered items
            let (next_cursor, p1) =
                super::take_set_overflow_page(&scope_a, key, session_cursor, 2, None).await.expect("take set page 1");
            assert_eq!(p1.len(), 2);
            assert_eq!(p1[0].member, text_blob("m2"));
            assert_eq!(p1[1].member, text_blob("m3"));
            assert_eq!(next_cursor, session_cursor);

            let (next_cursor, p2) =
                super::take_set_overflow_page(&scope_a, key, session_cursor, 2, None).await.expect("take set page 2");
            assert_eq!(p2.len(), 1);
            assert_eq!(p2[0].member, text_blob("m4"));
            assert_eq!(next_cursor, session_cursor);

            // Buffer drained -> take_collection_scan_cursor
            let (server_cursor, session_opt) = super::take_collection_scan_cursor(
                &scope_a,
                key,
                session_cursor,
                super::RedisCollectionOverflowKind::Set,
                None,
            )
            .await
            .expect("take set scan cursor");
            assert_eq!(server_cursor, followup_cursor);
            assert!(session_opt.is_some());
        }

        // 3. Exhaustion behavior when followup_cursor is 0
        {
            let key = b"direct-exhaustion-hash";
            let mut items: Vec<RedisHashItem> = (0..3)
                .map(|i| RedisHashItem {
                    field: text_blob(&format!("fx{i}")),
                    value: text_blob(&format!("vx{i}")),
                    field_ttl: None,
                })
                .collect();

            // followup_cursor == 0: no further server pages exist
            let cursor = super::store_hash_overflow_page(&scope_a, key, &mut items, 1, 0, None).await;
            assert_eq!(items.len(), 1);
            assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);

            // Drain remaining 2 items in one page
            let (next_cursor, p) =
                super::take_hash_overflow_page(&scope_a, key, cursor, 2, None).await.expect("take exhausted page");
            assert_eq!(p.len(), 2);
            // Since buffer is now empty AND followup_cursor == 0, cursor is NOT retained
            assert_eq!(next_cursor, 0);

            // Session has been evicted from registry on exhaustion
            assert!(!super::collection_overflow_sessions().lock().await.entries.contains_key(&cursor));
            assert!(super::take_hash_overflow_page(&scope_a, key, cursor, 1, None).await.is_none());
            assert!(super::take_collection_scan_cursor(
                &scope_a,
                key,
                cursor,
                super::RedisCollectionOverflowKind::Hash,
                None,
            )
            .await
            .is_err());
        }

        // 4. Expiration behavior (TTL purge)
        {
            let key = b"direct-expiration-hash";
            let mut items: Vec<RedisHashItem> = (0..3)
                .map(|i| RedisHashItem {
                    field: text_blob(&format!("fe{i}")),
                    value: text_blob(&format!("ve{i}")),
                    field_ttl: None,
                })
                .collect();

            let cursor = super::store_hash_overflow_page(&scope_a, key, &mut items, 1, 0, None).await;
            assert!(super::collection_overflow_sessions().lock().await.entries.contains_key(&cursor));

            // Force expiration by winding last_used back past TTL
            super::collection_overflow_sessions().lock().await.entries.get_mut(&cursor).unwrap().last_used =
                std::time::Instant::now() - super::COLLECTION_OVERFLOW_SESSION_TTL - std::time::Duration::from_secs(1);

            // take_matching purges expired entries
            assert!(super::take_hash_overflow_page(&scope_a, key, cursor, 1, None).await.is_none());
            assert!(!super::collection_overflow_sessions().lock().await.entries.contains_key(&cursor));
            assert!(super::take_collection_scan_cursor(
                &scope_a,
                key,
                cursor,
                super::RedisCollectionOverflowKind::Hash,
                None,
            )
            .await
            .is_err());
        }
    }

    /// Replays standalone-Redis pagination for sets (issue #12640 sibling collection):
    /// a large set is read through get_value_scoped, then paged through load_more_collection_scoped.
    /// Every member must arrive exactly once, foreign scopes must be rejected without server scan,
    /// and pagination terminates cleanly when the collection is exhausted.
    #[tokio::test]
    async fn scoped_set_pagination_walks_large_collections_without_repeating_the_first_page() {
        const MEMBERS: usize = 4000;
        const PAGE: usize = 200;
        let scope = super::RedisOperationScope { connection_id: "issue-12640-standalone-set".to_string(), db: 0 };

        // Real SSCAN cursors: one batch of `PAGE` members per server round trip.
        let mut responses = vec![bulk("set"), RedisRawValue::Int(-1), RedisRawValue::Int(MEMBERS as i64)];
        let pages = MEMBERS.div_ceil(PAGE);
        for page in 0..pages {
            let cursor = if page + 1 == pages { "0".to_string() } else { (page + 1).to_string() };
            let members: Vec<String> =
                (page * PAGE..((page + 1) * PAGE).min(MEMBERS)).map(|index| format!("member:{index}")).collect();
            responses.push(int_scan_response_owned(&cursor, members));
        }
        let mut con = FakeRedisConnection::new(responses);

        let value = super::get_value_scoped(&mut con, b"issue-12640-set", &scope).await.unwrap();
        let RedisValueData::Set { items: mut seen, scan_cursor, total } = value.data else {
            panic!("expected set");
        };
        assert_eq!(total, MEMBERS as u64);
        assert_eq!(seen.len(), PAGE, "the first page defaults to the configured page size");
        let mut cursor = scan_cursor.expect("a 4000-member set must offer a continuation");
        assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START, "the continuation is an overflow session marker");

        // The unscoped path (default scope) must reject the marker without touching the server.
        let mut mismatched = FakeRedisConnection::new(vec![]);
        let error = super::load_more_collection(&mut mismatched, b"issue-12640-set", "set", cursor, PAGE, None, None)
            .await
            .unwrap_err();
        assert!(error.contains("invalid, expired"), "{error}");
        assert!(mismatched.commands.is_empty(), "foreign cursor must not reach the server");

        // Foreign connection id must also be rejected without touching the server.
        let foreign_scope = super::RedisOperationScope { connection_id: "foreign-conn".to_string(), db: 0 };
        let mut wrong = FakeRedisConnection::new(vec![]);
        let error = super::load_more_collection_scoped(
            &mut wrong,
            b"issue-12640-set",
            "set",
            cursor,
            PAGE,
            None,
            None,
            &foreign_scope,
        )
        .await
        .unwrap_err();
        assert!(error.contains("invalid, expired"), "{error}");
        assert!(wrong.commands.is_empty());

        // Foreign database must also be rejected without touching the server.
        let foreign_db = super::RedisOperationScope { connection_id: scope.connection_id.clone(), db: 1 };
        let error = super::load_more_collection_scoped(
            &mut wrong,
            b"issue-12640-set",
            "set",
            cursor,
            PAGE,
            None,
            None,
            &foreign_db,
        )
        .await
        .unwrap_err();
        assert!(error.contains("invalid, expired"), "{error}");
        assert!(wrong.commands.is_empty());

        // Mismatched collection type must be rejected without touching the server.
        let error = super::load_more_collection_scoped(
            &mut wrong,
            b"issue-12640-set",
            "hash",
            cursor,
            PAGE,
            None,
            None,
            &scope,
        )
        .await
        .unwrap_err();
        assert!(error.contains("different collection type") || error.contains("invalid, expired"), "{error}");
        assert!(wrong.commands.is_empty());

        let mut pages_seen = 1;
        while cursor != 0 {
            let page = super::load_more_collection_scoped(
                &mut con,
                b"issue-12640-set",
                "set",
                cursor,
                PAGE,
                None,
                None,
                &scope,
            )
            .await
            .unwrap();
            let RedisCollectionPage::Set { items, scan_cursor: next } = page else {
                panic!("expected set");
            };
            seen.extend(items);
            pages_seen += 1;
            assert!(pages_seen <= pages, "pagination must terminate");
            match next {
                Some(next) => {
                    assert_ne!(next, cursor, "each page must continue with a fresh marker");
                    cursor = next;
                }
                None => break,
            }
        }

        assert_eq!(pages_seen, pages);
        assert_eq!(seen.len(), MEMBERS);
        let unique: std::collections::HashSet<_> = seen.iter().map(|item| item.member.raw_base64.clone()).collect();
        assert_eq!(unique.len(), MEMBERS, "every member arrives exactly once");
        assert_eq!(con.command_count("SSCAN"), pages);
    }

    #[tokio::test]
    async fn concurrent_collection_overflow_sessions_isolate_across_scopes_and_keys() {
        let scope_1 = super::RedisOperationScope { connection_id: "conn-prod".to_string(), db: 0 };
        let scope_2 = super::RedisOperationScope { connection_id: "conn-staging".to_string(), db: 0 };
        let scope_3 = super::RedisOperationScope { connection_id: "conn-prod".to_string(), db: 1 };
        let unscoped = super::RedisOperationScope::default();

        let mut hash_items_1: Vec<RedisHashItem> = (0..4)
            .map(|i| RedisHashItem {
                field: text_blob(&format!("p_f{i}")),
                value: text_blob(&format!("p_v{i}")),
                field_ttl: None,
            })
            .collect();
        let mut hash_items_2: Vec<RedisHashItem> = (0..4)
            .map(|i| RedisHashItem {
                field: text_blob(&format!("s_f{i}")),
                value: text_blob(&format!("s_v{i}")),
                field_ttl: None,
            })
            .collect();
        let mut set_items_3: Vec<RedisSetItem> =
            (0..4).map(|i| RedisSetItem { member: text_blob(&format!("db1_m{i}")) }).collect();

        // All 3 use key b"shared-name", but have different scopes or kinds!
        let key = b"shared-name";
        let c1 = super::store_hash_overflow_page(&scope_1, key, &mut hash_items_1, 1, 101, None).await;
        let c2 = super::store_hash_overflow_page(&scope_2, key, &mut hash_items_2, 1, 202, None).await;
        let c3 = super::store_set_overflow_page(&scope_3, key, &mut set_items_3, 1, 303, None).await;

        // Distinct session cursors allocated
        assert_ne!(c1, c2);
        assert_ne!(c1, c3);
        assert_ne!(c2, c3);

        // Cross-scope and cross-kind isolation:
        // Session 1 (scope_1, Hash) cannot be consumed by scope_2, scope_3, unscoped, or as Set
        assert!(super::take_hash_overflow_page(&scope_2, key, c1, 1, None).await.is_none());
        assert!(super::take_hash_overflow_page(&scope_3, key, c1, 1, None).await.is_none());
        assert!(super::take_hash_overflow_page(&unscoped, key, c1, 1, None).await.is_none());
        assert!(super::take_set_overflow_page(&scope_1, key, c1, 1, None).await.is_none());

        // Session 2 (scope_2, Hash) cannot be consumed by scope_1, scope_3, unscoped, or as Set
        assert!(super::take_hash_overflow_page(&scope_1, key, c2, 1, None).await.is_none());
        assert!(super::take_hash_overflow_page(&scope_3, key, c2, 1, None).await.is_none());
        assert!(super::take_hash_overflow_page(&unscoped, key, c2, 1, None).await.is_none());
        assert!(super::take_set_overflow_page(&scope_2, key, c2, 1, None).await.is_none());

        // Session 3 (scope_3, Set) cannot be consumed by scope_1, scope_2, unscoped, or as Hash
        assert!(super::take_set_overflow_page(&scope_1, key, c3, 1, None).await.is_none());
        assert!(super::take_set_overflow_page(&scope_2, key, c3, 1, None).await.is_none());
        assert!(super::take_set_overflow_page(&unscoped, key, c3, 1, None).await.is_none());
        assert!(super::take_hash_overflow_page(&scope_3, key, c3, 1, None).await.is_none());

        // Valid interleaved page consumption:
        let (_, p1_a) = super::take_hash_overflow_page(&scope_1, key, c1, 1, None).await.unwrap();
        assert_eq!(p1_a[0].field, text_blob("p_f1"));

        let (_, p2_a) = super::take_hash_overflow_page(&scope_2, key, c2, 1, None).await.unwrap();
        assert_eq!(p2_a[0].field, text_blob("s_f1"));

        let (_, p3_a) = super::take_set_overflow_page(&scope_3, key, c3, 1, None).await.unwrap();
        assert_eq!(p3_a[0].member, text_blob("db1_m1"));

        // Drain the rest of session 1
        let (_, p1_b) = super::take_hash_overflow_page(&scope_1, key, c1, 2, None).await.unwrap();
        assert_eq!(p1_b.len(), 2);
        assert_eq!(p1_b[0].field, text_blob("p_f2"));
        assert_eq!(p1_b[1].field, text_blob("p_f3"));

        // Session 1 buffer is drained; transition to server scan cursor
        let (srv1, _) =
            super::take_collection_scan_cursor(&scope_1, key, c1, super::RedisCollectionOverflowKind::Hash, None)
                .await
                .unwrap();
        assert_eq!(srv1, 101);

        // Session 2 and Session 3 are still intact and can continue
        let (_, p2_b) = super::take_hash_overflow_page(&scope_2, key, c2, 2, None).await.unwrap();
        assert_eq!(p2_b.len(), 2);
        assert_eq!(p2_b[0].field, text_blob("s_f2"));
        assert_eq!(p2_b[1].field, text_blob("s_f3"));
        let (srv2, _) =
            super::take_collection_scan_cursor(&scope_2, key, c2, super::RedisCollectionOverflowKind::Hash, None)
                .await
                .unwrap();
        assert_eq!(srv2, 202);

        let (_, p3_b) = super::take_set_overflow_page(&scope_3, key, c3, 2, None).await.unwrap();
        assert_eq!(p3_b.len(), 2);
        assert_eq!(p3_b[0].member, text_blob("db1_m2"));
        assert_eq!(p3_b[1].member, text_blob("db1_m3"));
        let (srv3, _) =
            super::take_collection_scan_cursor(&scope_3, key, c3, super::RedisCollectionOverflowKind::Set, None)
                .await
                .unwrap();
        assert_eq!(srv3, 303);
    }

    #[test]
    fn collection_overflow_sessions_capacity_and_lru_eviction() {
        let mut sessions = super::RedisCollectionOverflowSessions::default();
        let scope = super::RedisOperationScope { connection_id: "capacity-test".to_string(), db: 0 };

        let mut cursors = Vec::new();
        for i in 0..super::COLLECTION_OVERFLOW_SESSION_LIMIT {
            let session = super::RedisCollectionOverflowSession {
                scope: scope.clone(),
                key: format!("key-{i}").into_bytes(),
                kind: super::RedisCollectionOverflowKind::Hash,
                filter: None,
                sort_direction: None,
                followup_cursor: 0,
                items: super::RedisCollectionOverflowItems::Hash(vec![]),
                last_used: std::time::Instant::now(),
            };
            let cursor = sessions.insert(session);
            cursors.push(cursor);
        }

        assert_eq!(sessions.entries.len(), super::COLLECTION_OVERFLOW_SESSION_LIMIT);

        // Mark the first cursor as oldest
        let oldest_cursor = cursors[0];
        sessions.entries.get_mut(&oldest_cursor).unwrap().last_used =
            std::time::Instant::now() - std::time::Duration::from_secs(60);

        // Inserting the 129th session must evict the oldest cursor
        let extra_session = super::RedisCollectionOverflowSession {
            scope: scope.clone(),
            key: b"extra-key".to_vec(),
            kind: super::RedisCollectionOverflowKind::Hash,
            filter: None,
            sort_direction: None,
            followup_cursor: 0,
            items: super::RedisCollectionOverflowItems::Hash(vec![]),
            last_used: std::time::Instant::now(),
        };
        let extra_cursor = sessions.insert(extra_session);

        assert_eq!(sessions.entries.len(), super::COLLECTION_OVERFLOW_SESSION_LIMIT);
        assert!(!sessions.entries.contains_key(&oldest_cursor));
        assert!(sessions
            .take_matching(oldest_cursor, &scope, b"key-0", super::RedisCollectionOverflowKind::Hash, None, None)
            .is_none());

        assert!(sessions.entries.contains_key(&extra_cursor));
        assert!(sessions
            .take_matching(extra_cursor, &scope, b"extra-key", super::RedisCollectionOverflowKind::Hash, None, None)
            .is_some());
    }

    #[tokio::test]
    #[ignore = "requires approved disposable Valkey multi-DB, default-one and Redis cluster fixtures"]
    async fn cluster_databases_live_native_mapped_and_permission_controls() {
        let mut config = redis_test_connection_config();
        config.host = "127.0.0.1".to_string();
        config.port =
            std::env::var("DBX_TEST_VALKEY_CLUSTER_PORT").expect("DBX_TEST_VALKEY_CLUSTER_PORT").parse().unwrap();
        config.username.clear();
        config.password.clear();
        let pool = super::connect_cluster(&config).await.unwrap();
        assert!(pool.database_connections.lock().await.is_empty());
        let databases = super::list_cluster_databases(&pool).await.unwrap();
        assert_eq!(databases.iter().map(|database| database.db).collect::<Vec<_>>(), vec![0, 1, 2, 3]);
        assert!(databases.iter().all(|database| database.keys.is_some()));
        assert!(
            pool.database_connections.lock().await.is_empty(),
            "listing must not create one cluster connection per database"
        );
        let mut keys = Vec::new();
        for (index, range) in pool.slot_ranges.iter().enumerate() {
            let key = (0..100_000)
                .map(|candidate| format!("dbx1271:driver-live:{}:{index}:{candidate}", std::process::id()))
                .find(|key| (range.start..=range.end).contains(&redis_cluster_slot(key.as_bytes())))
                .unwrap();
            for db in [0, 1] {
                let mut con = super::cluster_key_connection_in_db(&pool, key.as_bytes(), db).await.unwrap();
                redis::cmd("SET")
                    .arg(&key)
                    .arg(format!("db{db}:master{index}"))
                    .query_async::<()>(&mut con)
                    .await
                    .unwrap();
            }
            keys.push(key);
        }
        assert_eq!(keys.len(), 3);
        assert_eq!(pool.database_connections.lock().await.len(), 1);
        let cold = super::connect_cluster(&config).await.unwrap();
        super::list_cluster_databases(&cold).await.unwrap();
        assert!(cold.database_connections.lock().await.is_empty());
        let cold_ref = &cold;
        let cold_values = futures_util::future::join_all(keys.iter().map(|key| async move {
            let mut con = super::cluster_key_connection_in_db(cold_ref, key.as_bytes(), 1).await.unwrap();
            redis::cmd("GET").arg(key).query_async::<String>(&mut con).await.unwrap()
        }))
        .await;
        for (index, value) in cold_values.iter().enumerate() {
            assert_eq!(value, &format!("db1:master{index}"));
        }
        assert_eq!(cold.database_connections.lock().await.len(), 1);
        for (index, key) in keys.iter().enumerate() {
            for _ in 0..10 {
                let pool_ref = &pool;
                let read = |db| async move {
                    let mut con = super::cluster_key_connection_in_db(pool_ref, key.as_bytes(), db).await.unwrap();
                    redis::cmd("GET").arg(key).query_async::<String>(&mut con).await.unwrap()
                };
                let (zero, one) = tokio::join!(read(0), read(1));
                assert_eq!(zero, format!("db0:master{index}"));
                assert_eq!(one, format!("db1:master{index}"));
            }
        }
        let forwarded_port: u16 =
            std::env::var("DBX_TEST_VALKEY_FORWARDED_PORT").expect("DBX_TEST_VALKEY_FORWARDED_PORT").parse().unwrap();
        let routes = pool
            .node_routes
            .iter()
            .map(|route| RedisNodeRoute {
                advertised: route.advertised.clone(),
                connect: RedisNodeEndpoint {
                    host: "127.0.0.1".to_string(),
                    port: forwarded_port + route.advertised.port - config.port,
                },
            })
            .collect::<Vec<_>>();
        let mapped = super::connect_routed_cluster(
            &config,
            routes.clone(),
            pool.slot_ranges.clone(),
            routes,
            super::RedisClusterAuth { username: String::new(), password: String::new() },
        )
        .await
        .unwrap();
        let mapped_databases = super::list_cluster_databases(&mapped).await.unwrap();
        assert_eq!(mapped_databases.len(), 4);
        for (index, key) in keys.iter().enumerate() {
            let mut con = super::cluster_key_connection_in_db(&mapped, key.as_bytes(), 1).await.unwrap();
            assert_eq!(
                redis::cmd("GET").arg(key).query_async::<String>(&mut con).await.unwrap(),
                format!("db1:master{index}")
            );
        }
        for db in [0, 1] {
            let mut cursor = 0;
            let mut found = Vec::new();
            loop {
                let page = super::scan_cluster_keys_batch_in_db(
                    &mapped,
                    db,
                    cursor,
                    &format!("dbx1271:driver-live:{}:*", std::process::id()),
                    100,
                    3,
                    false,
                )
                .await
                .unwrap();
                found.extend(page.keys);
                cursor = page.cursor;
                if cursor == 0 {
                    break;
                }
            }
            assert_eq!(found.len(), 3);
        }
        let pattern = format!("dbx1271:driver-live:{}:*", std::process::id());
        let mut cursor = 0;
        let mut found = Vec::new();
        loop {
            let page = super::scan_cluster_values_page_in_db(&mapped, 1, cursor, &pattern, "db1:master", false, 100)
                .await
                .unwrap();
            assert_eq!(Some(page.total_keys), mapped_databases[1].keys);
            found.extend(page.keys);
            cursor = page.cursor;
            if cursor == 0 {
                break;
            }
            assert!(super::scan_cluster_values_page_in_db(&mapped, 0, cursor, &pattern, "db1:master", false, 100)
                .await
                .is_err());
        }
        assert_eq!(found.len(), 3);
        let mut denied_config = config.clone();
        denied_config.username = "dbx1271-no-config".to_string();
        denied_config.password = "dbx1271-fixture-only".to_string();
        let denied = super::connect_cluster(&denied_config).await.unwrap();
        assert_eq!(super::list_cluster_databases(&denied).await.unwrap().len(), 1);
        let diagnostic = super::cluster_database_diagnostic(&denied).await.unwrap();
        assert!(is_redis_command_denied_error(&diagnostic), "{diagnostic}");
        let mut con = super::cluster_key_connection_in_db(&denied, keys[0].as_bytes(), 0).await.unwrap();
        assert_eq!(redis::cmd("GET").arg(&keys[0]).query_async::<String>(&mut con).await.unwrap(), "db0:master0");
        assert!(super::ensure_cluster_database(&denied, 1).await.unwrap_err().contains("CONFIG"));
        for variable in ["DBX_TEST_VALKEY_DEFAULT_CLUSTER_PORT", "DBX_TEST_REDIS_CONTROL_CLUSTER_PORT"] {
            let mut control_config = config.clone();
            control_config.port = std::env::var(variable).expect(variable).parse().unwrap();
            let control = super::connect_cluster(&control_config).await.unwrap();
            assert_eq!(super::list_cluster_databases(&control).await.unwrap().len(), 1);
            assert!(super::ensure_cluster_database(&control, 1).await.is_err());
            super::cluster_any_connection_in_db(&control, 0).await.unwrap();
        }
        for db in [0, 1] {
            for key in &keys {
                let mut con = super::cluster_key_connection_in_db(&pool, key.as_bytes(), db).await.unwrap();
                redis::cmd("DEL").arg(key).query_async::<u64>(&mut con).await.unwrap();
            }
        }
    }

    struct FakeRedisConnection {
        responses: VecDeque<redis::RedisResult<RedisRawValue>>,
        commands: Vec<String>,
    }

    impl FakeRedisConnection {
        fn new(responses: Vec<RedisRawValue>) -> Self {
            Self { responses: responses.into_iter().map(Ok).collect(), commands: Vec::new() }
        }

        fn with_results(responses: Vec<redis::RedisResult<RedisRawValue>>) -> Self {
            Self { responses: responses.into(), commands: Vec::new() }
        }

        fn command_count(&self, command: &str) -> usize {
            let needle = format!("\r\n{command}\r\n");
            self.commands.iter().filter(|packed| packed.contains(&needle)).count()
        }
    }

    impl ConnectionLike for FakeRedisConnection {
        fn req_packed_command<'a>(&'a mut self, cmd: &'a Cmd) -> RedisFuture<'a, RedisRawValue> {
            self.commands.push(String::from_utf8_lossy(&cmd.get_packed_command()).into_owned());
            let response = self.responses.pop_front().unwrap_or(Ok(RedisRawValue::Nil));
            Box::pin(async move { response })
        }

        fn req_packed_commands<'a>(
            &'a mut self,
            cmd: &'a Pipeline,
            _offset: usize,
            count: usize,
        ) -> RedisFuture<'a, Vec<RedisRawValue>> {
            self.commands.push(String::from_utf8_lossy(&cmd.get_packed_pipeline()).into_owned());
            let responses = (0..count)
                .map(|_| self.responses.pop_front().unwrap_or(Ok(RedisRawValue::Nil)))
                .collect::<redis::RedisResult<Vec<_>>>();
            Box::pin(async move { responses })
        }

        fn get_db(&self) -> i64 {
            0
        }
    }

    struct TrackedRedisConnection {
        responses: VecDeque<redis::RedisResult<RedisRawValue>>,
        commands: Arc<StdMutex<Vec<String>>>,
    }

    impl TrackedRedisConnection {
        fn new(responses: Vec<RedisRawValue>, commands: Arc<StdMutex<Vec<String>>>) -> Self {
            Self { responses: responses.into_iter().map(Ok).collect(), commands }
        }
    }

    impl ConnectionLike for TrackedRedisConnection {
        fn req_packed_command<'a>(&'a mut self, cmd: &'a Cmd) -> RedisFuture<'a, RedisRawValue> {
            self.commands.lock().unwrap().push(String::from_utf8_lossy(&cmd.get_packed_command()).into_owned());
            let response = self.responses.pop_front().unwrap_or(Ok(RedisRawValue::Nil));
            Box::pin(async move { response })
        }

        fn req_packed_commands<'a>(
            &'a mut self,
            cmd: &'a Pipeline,
            _offset: usize,
            count: usize,
        ) -> RedisFuture<'a, Vec<RedisRawValue>> {
            self.commands.lock().unwrap().push(String::from_utf8_lossy(&cmd.get_packed_pipeline()).into_owned());
            let responses = (0..count)
                .map(|_| self.responses.pop_front().unwrap_or(Ok(RedisRawValue::Nil)))
                .collect::<redis::RedisResult<Vec<_>>>();
            Box::pin(async move { responses })
        }

        fn get_db(&self) -> i64 {
            0
        }
    }

    fn tracked_command_count(commands: &Arc<StdMutex<Vec<String>>>, command: &str) -> usize {
        let needle = format!("\r\n{command}\r\n");
        commands.lock().unwrap().iter().filter(|packed| packed.contains(&needle)).count()
    }

    /// Byte offsets of every occurrence of `command` inside a packed pipeline.
    ///
    /// The offsets make the order of the commands observable, so a test can
    /// tell an interleaved pipeline (TYPE, TTL, TYPE, TTL) from a grouped one
    /// (TYPE, TYPE, TTL, TTL) that carries the same commands.
    fn command_offsets(packed: &str, command: &str) -> Vec<usize> {
        let needle = format!("\r\n{command}\r\n");
        let mut offsets = Vec::new();
        let mut start = 0;
        while let Some(index) = packed[start..].find(&needle) {
            offsets.push(start + index);
            start += index + needle.len();
        }
        offsets
    }

    fn bulk(value: &str) -> RedisRawValue {
        RedisRawValue::BulkString(value.as_bytes().to_vec())
    }

    fn scan_response(cursor: &str, keys: Vec<&str>) -> RedisRawValue {
        RedisRawValue::Array(vec![
            bulk(cursor),
            RedisRawValue::Array(
                keys.into_iter().map(|key| RedisRawValue::BulkString(key.as_bytes().to_vec())).collect(),
            ),
        ])
    }

    fn hscan_response(cursor: &str, pairs: Vec<(&str, &str)>) -> RedisRawValue {
        let entries = pairs.into_iter().flat_map(|(field, value)| [bulk(field), bulk(value)]).collect();
        RedisRawValue::Array(vec![bulk(cursor), RedisRawValue::Array(entries)])
    }

    fn hscan_response_owned(cursor: &str, pairs: Vec<(String, String)>) -> RedisRawValue {
        let entries = pairs.into_iter().flat_map(|(field, value)| [bulk(&field), bulk(&value)]).collect();
        RedisRawValue::Array(vec![bulk(cursor), RedisRawValue::Array(entries)])
    }

    fn int_scan_response_owned(cursor: &str, members: Vec<String>) -> RedisRawValue {
        RedisRawValue::Array(vec![
            bulk(cursor),
            RedisRawValue::Array(members.into_iter().map(|member| bulk(&member)).collect()),
        ])
    }

    fn httl_response(count: usize, ttl: i64) -> RedisRawValue {
        RedisRawValue::Array((0..count).map(|_| RedisRawValue::Int(ttl)).collect())
    }

    fn zrange_response(pairs: Vec<(&str, &str)>) -> RedisRawValue {
        RedisRawValue::Array(pairs.into_iter().flat_map(|(member, score)| [bulk(member), bulk(score)]).collect())
    }

    fn noperm(command: &str) -> redis::RedisError {
        redis::parse_redis_value(
            format!("-NOPERM this user has no permissions to run the '{command}' command\r\n").as_bytes(),
        )
        .unwrap()
        .extract_error()
        .unwrap_err()
    }

    #[test]
    fn parsed_server_errors_preserve_compatibility_classification() {
        let error =
            |response: &str| redis::parse_redis_value(response.as_bytes()).unwrap().extract_error().unwrap_err();
        let unknown_select = error("-ERR unknown command 'SELECT'\r\n");
        assert!(super::is_unavailable_db_zero_select(&unknown_select, 0));
        assert!(!super::is_unavailable_db_zero_select(&unknown_select, 1));
        assert!(super::is_unsupported_keepttl_error(&error("-ERR syntax error\r\n")));
        for response in [
            "-NOPERM unknown command SELECT syntax error\r\n",
            "-WRONGPASS syntax error\r\n",
            "-READONLY syntax error\r\n",
            "-WRONGTYPE syntax error\r\n",
        ] {
            let error = error(response);
            assert!(!super::is_unavailable_db_zero_select(&error, 0));
            assert!(!super::is_unsupported_keepttl_error(&error));
        }
        let denied_ping = noperm("ping").to_string();
        assert!(super::is_redis_command_denied_error(&denied_ping));
        assert!(!super::is_redis_auth_error(&denied_ping));
        assert!(super::is_redis_auth_error(&error("-WRONGPASS invalid username-password pair\r\n").to_string()));
        assert!(super::is_hash_field_update_acl_compatibility_error(&noperm("eval")));
        assert!(!super::is_hash_field_update_acl_compatibility_error(&noperm("unrelated")));
    }

    #[tokio::test]
    async fn connection_keeps_dbx_deadline_and_allows_slow_responses() {
        use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let address = listener.local_addr().unwrap();
        let server = tokio::spawn(async move {
            let (stream, _) = listener.accept().await.unwrap();
            let (reader, mut writer) = stream.into_split();
            let mut reader = BufReader::new(reader);
            // A valid handshake slower than redis-rs 1.x's new 1-second default.
            tokio::time::sleep(Duration::from_millis(1100)).await;
            loop {
                let mut line = String::new();
                if reader.read_line(&mut line).await.unwrap() == 0 {
                    break;
                }
                let count: usize = line.trim().strip_prefix('*').unwrap().parse().unwrap();
                let mut args = Vec::new();
                for _ in 0..count {
                    line.clear();
                    reader.read_line(&mut line).await.unwrap();
                    let len: usize = line.trim().strip_prefix('$').unwrap().parse().unwrap();
                    let mut arg = vec![0; len + 2];
                    reader.read_exact(&mut arg).await.unwrap();
                    arg.truncate(len);
                    args.push(arg);
                }
                if args[0] == b"GET" {
                    // Commands may legitimately exceed the new 500-ms default.
                    tokio::time::sleep(Duration::from_millis(650)).await;
                    writer.write_all(b"$3\r\n\x00\xffA\r\n").await.unwrap();
                    break;
                }
                writer.write_all(if args[0] == b"PING" { b"+PONG\r\n" } else { b"+OK\r\n" }).await.unwrap();
            }
        });
        let mut con = super::connect(&format!("redis://{address}"), Duration::from_secs(3)).await.unwrap();
        let value: Vec<u8> =
            tokio::time::timeout(Duration::from_secs(3), redis::cmd("GET").arg("slow").query_async(&mut con))
                .await
                .unwrap()
                .unwrap();
        assert_eq!(value, b"\x00\xffA");
        server.await.unwrap();

        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let error = super::connect(&format!("redis://{}", listener.local_addr().unwrap()), Duration::from_millis(30))
            .await
            .unwrap_err();
        assert!(error.contains("connection timed out"));
    }

    #[derive(Clone, Copy)]
    enum ClusterDelayStage {
        Setup,
        Slots,
        Ping,
    }

    // Unlike the sequential Sentinel/standalone mocks, cluster discovery opens
    // multiple sockets. Keep their tasks owned so aborting the server closes all
    // sockets, including a deliberately delayed response after client timeout.
    async fn cluster_timeout_mock(
        stage: ClusterDelayStage,
        delay: Duration,
    ) -> (std::net::SocketAddr, tokio::task::JoinHandle<()>) {
        use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let address = listener.local_addr().unwrap();
        let slots_seen = Arc::new(AtomicUsize::new(0));
        let pings_after_slots = Arc::new(AtomicUsize::new(0));
        let server = tokio::spawn(async move {
            let mut connections = tokio::task::JoinSet::new();
            loop {
                tokio::select! {
                    accepted = listener.accept() => {
                        let (stream, _) = accepted.unwrap();
                        let slots_seen = slots_seen.clone();
                        let pings_after_slots = pings_after_slots.clone();
                        connections.spawn(async move {
                            let (reader, mut writer) = stream.into_split();
                            let mut reader = BufReader::new(reader);
                            let mut first = true;
                            let mut ping_count = 0;
                            loop {
                                let mut line = String::new();
                                if reader.read_line(&mut line).await.unwrap_or(0) == 0 {
                                    break;
                                }
                                let count: usize = line.trim().strip_prefix('*').unwrap().parse().unwrap();
                                let mut args = Vec::new();
                                for _ in 0..count {
                                    line.clear();
                                    reader.read_line(&mut line).await.unwrap();
                                    let len: usize = line.trim().strip_prefix('$').unwrap().parse().unwrap();
                                    let mut arg = vec![0; len + 2];
                                    reader.read_exact(&mut arg).await.unwrap();
                                    arg.truncate(len);
                                    args.push(arg);
                                }
                                let is_slots = args[0] == b"CLUSTER" && args[1] == b"SLOTS";
                                if args[0] == b"PING" {
                                    ping_count += 1;
                                }
                                let should_delay = match stage {
                                    ClusterDelayStage::Setup => first,
                                    ClusterDelayStage::Slots => is_slots && slots_seen.load(Ordering::SeqCst) == 0,
                                    // With this one-node topology redis-rs sends PING
                                    // on connect, then checks the reused socket after
                                    // CLUSTER SLOTS. The third PING is the DBX probe.
                                    ClusterDelayStage::Ping => args[0] == b"PING"
                                        && ping_count > 2
                                        && slots_seen.load(Ordering::SeqCst) > 0
                                        && pings_after_slots.fetch_add(1, Ordering::SeqCst) == 0,
                                };
                                first = false;
                                if should_delay {
                                    tokio::time::sleep(delay).await;
                                }
                                let response = if is_slots {
                                    slots_seen.fetch_add(1, Ordering::SeqCst);
                                    format!("*1\r\n*3\r\n:0\r\n:16383\r\n*2\r\n$9\r\n127.0.0.1\r\n:{}\r\n", address.port())
                                } else if args[0] == b"PING" {
                                    "+PONG\r\n".to_string()
                                } else {
                                    "+OK\r\n".to_string()
                                };
                                if writer.write_all(response.as_bytes()).await.is_err() {
                                    break;
                                }
                            }
                        });
                    }
                    finished = connections.join_next(), if !connections.is_empty() => {
                        finished.unwrap().unwrap();
                    }
                }
            }
        });
        (address, server)
    }

    async fn cluster_connect_with_delay(
        stage: ClusterDelayStage,
        delay: Duration,
        timeout_secs: u64,
    ) -> Result<(), String> {
        let (address, server) = cluster_timeout_mock(stage, delay).await;
        let mut config = redis_test_connection_config();
        config.host = address.ip().to_string();
        config.port = address.port();
        config.password = "test-only".to_string();
        config.connect_timeout_secs = timeout_secs;
        let result = tokio::time::timeout(Duration::from_secs(20), super::connect_cluster(&config)).await;
        server.abort();
        let _ = server.await;
        result.expect("cluster regression exceeded its test deadline").map(|_| ())
    }

    #[tokio::test]
    async fn cluster_connect_honors_configured_handshake_timeout() {
        cluster_connect_with_delay(ClusterDelayStage::Setup, Duration::from_millis(1500), 30).await.unwrap();
    }

    #[tokio::test]
    async fn cluster_connect_honors_configured_initialization_timeout() {
        cluster_connect_with_delay(ClusterDelayStage::Slots, Duration::from_millis(5500), 30).await.unwrap();
    }

    #[tokio::test]
    async fn cluster_connect_honors_configured_ping_timeout() {
        cluster_connect_with_delay(ClusterDelayStage::Ping, Duration::from_millis(5500), 30).await.unwrap();
    }

    #[tokio::test]
    async fn cluster_connect_rejects_initialization_over_configured_timeout() {
        let error =
            cluster_connect_with_delay(ClusterDelayStage::Slots, Duration::from_millis(1500), 1).await.unwrap_err();
        assert_eq!(error, "Redis cluster connection timed out (1s)");
    }

    #[tokio::test]
    async fn cluster_connect_uses_effective_timeout_for_unset_and_oversized_values() {
        for timeout in [0, u64::MAX] {
            cluster_connect_with_delay(ClusterDelayStage::Setup, Duration::from_millis(1500), timeout).await.unwrap();
        }
    }

    #[tokio::test]
    async fn cluster_connect_rejects_ping_over_configured_timeout() {
        let error =
            cluster_connect_with_delay(ClusterDelayStage::Ping, Duration::from_millis(1500), 1).await.unwrap_err();
        assert_eq!(error, "Redis cluster ping timed out (1s)");
    }

    #[derive(Clone, Copy)]
    enum MetadataReply {
        Answer,
        Deny,
        /// Accept the command and keep the socket open without ever answering it.
        Silent,
    }

    /// Minimal RESP server for the standalone database-list probes: it answers the
    /// connection handshake and `PING`, and follows the script for the two metadata
    /// commands.
    async fn database_list_mock(
        config: MetadataReply,
        info: MetadataReply,
    ) -> (std::net::SocketAddr, tokio::task::JoinHandle<()>) {
        use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let address = listener.local_addr().unwrap();
        let server = tokio::spawn(async move {
            while let Ok((stream, _)) = listener.accept().await {
                let (reader, mut writer) = stream.into_split();
                let mut reader = BufReader::new(reader);
                loop {
                    let mut line = String::new();
                    if reader.read_line(&mut line).await.unwrap_or(0) == 0 {
                        break;
                    }
                    let count: usize = line.trim().strip_prefix('*').unwrap().parse().unwrap();
                    let mut args = Vec::new();
                    for _ in 0..count {
                        line.clear();
                        reader.read_line(&mut line).await.unwrap();
                        let len: usize = line.trim().strip_prefix('$').unwrap().parse().unwrap();
                        let mut arg = vec![0; len + 2];
                        reader.read_exact(&mut arg).await.unwrap();
                        arg.truncate(len);
                        args.push(arg);
                    }
                    let command = args[0].to_ascii_uppercase();
                    match command.as_slice() {
                        b"PING" => writer.write_all(b"+PONG\r\n").await.unwrap(),
                        b"CONFIG" => match config {
                            MetadataReply::Answer => {
                                writer.write_all(b"*2\r\n$9\r\ndatabases\r\n$1\r\n4\r\n").await.unwrap();
                            }
                            MetadataReply::Deny => {
                                writer
                                    .write_all(b"-NOPERM this user has no permissions to run the 'config' command\r\n")
                                    .await
                                    .unwrap();
                            }
                            MetadataReply::Silent => {
                                tokio::time::sleep(Duration::from_secs(30)).await;
                                break;
                            }
                        },
                        b"INFO" => match info {
                            MetadataReply::Answer => {
                                let keyspace = b"# Keyspace\r\ndb2:keys=5,expires=0,avg_ttl=0\r\n";
                                writer.write_all(format!("${}\r\n", keyspace.len()).as_bytes()).await.unwrap();
                                writer.write_all(keyspace).await.unwrap();
                                writer.write_all(b"\r\n").await.unwrap();
                            }
                            MetadataReply::Deny => {
                                writer
                                    .write_all(b"-NOPERM this user has no permissions to run the 'info' command\r\n")
                                    .await
                                    .unwrap();
                            }
                            MetadataReply::Silent => {
                                tokio::time::sleep(Duration::from_secs(30)).await;
                                break;
                            }
                        },
                        _ => writer.write_all(b"+OK\r\n").await.unwrap(),
                    }
                }
            }
        });
        (address, server)
    }

    #[tokio::test]
    async fn database_list_uses_the_configured_count_with_keyspace_counts() {
        let (address, server) = database_list_mock(MetadataReply::Answer, MetadataReply::Answer).await;
        let mut con = super::connect(&format!("redis://{address}"), Duration::from_secs(3)).await.unwrap();

        let databases = super::list_databases_with_timeout(&mut con, Duration::from_millis(200)).await.unwrap();

        assert_eq!(databases.len(), 4);
        assert_eq!(databases[2].keys, Some(5));
        assert_eq!(databases[0].keys, None);
        server.abort();
    }

    // 既有的降级路径:CONFIG 被改名/拒绝时用 DBX 默认值,键数量仍来自 INFO keyspace。
    #[tokio::test]
    async fn database_list_degrades_when_the_config_probe_is_denied() {
        let (address, server) = database_list_mock(MetadataReply::Deny, MetadataReply::Answer).await;
        let mut con = super::connect(&format!("redis://{address}"), Duration::from_secs(3)).await.unwrap();

        let databases = super::list_databases_with_timeout(&mut con, Duration::from_millis(200)).await.unwrap();

        assert_eq!(databases.len(), 16);
        assert_eq!(databases[2].keys, Some(5));
        server.abort();
    }

    // #12426:服务端/代理不回答 CONFIG 时返回超时错误,而不是让选择器一直等待。
    #[tokio::test]
    async fn database_list_reports_a_timeout_when_the_config_probe_stays_silent() {
        let (address, server) = database_list_mock(MetadataReply::Silent, MetadataReply::Answer).await;
        let mut con = super::connect(&format!("redis://{address}"), Duration::from_secs(3)).await.unwrap();

        let error = super::list_databases_with_timeout(&mut con, Duration::from_millis(200)).await.unwrap_err();

        assert!(error.contains("CONFIG GET databases"), "{error}");
        server.abort();
    }

    // #12426:INFO keyspace 一直不回答时返回超时错误,而不是无限等待。
    #[tokio::test]
    async fn database_list_reports_a_timeout_when_the_keyspace_probe_stays_silent() {
        let (address, server) = database_list_mock(MetadataReply::Answer, MetadataReply::Silent).await;
        let mut con = super::connect(&format!("redis://{address}"), Duration::from_secs(3)).await.unwrap();

        let error = super::list_databases_with_timeout(&mut con, Duration::from_millis(200)).await.unwrap_err();

        assert!(error.contains("INFO keyspace"), "{error}");
        server.abort();
    }

    struct SentinelMockReply {
        command: &'static str,
        response: Vec<u8>,
        delay: Duration,
    }

    impl SentinelMockReply {
        fn immediate(command: &'static str, response: &[u8]) -> Self {
            Self { command, response: response.to_vec(), delay: Duration::ZERO }
        }
    }

    async fn sentinel_mock(
        auth: Option<(&str, &str)>,
        scripts: Vec<Vec<SentinelMockReply>>,
    ) -> (std::net::SocketAddr, tokio::task::JoinHandle<()>) {
        use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let address = listener.local_addr().unwrap();
        let auth = auth.map(|(username, password)| {
            vec![b"AUTH".to_vec(), username.as_bytes().to_vec(), password.as_bytes().to_vec()]
        });
        let server = tokio::spawn(async move {
            for script in scripts {
                let (stream, _) = listener.accept().await.unwrap();
                let (reader, mut writer) = stream.into_split();
                let mut reader = BufReader::new(reader);
                let mut script = VecDeque::from(script);
                let mut authenticated = auth.is_none();
                while !script.is_empty() {
                    let mut line = String::new();
                    reader.read_line(&mut line).await.unwrap();
                    let count: usize = line.trim().strip_prefix('*').unwrap().parse().unwrap();
                    let mut args = Vec::new();
                    for _ in 0..count {
                        line.clear();
                        reader.read_line(&mut line).await.unwrap();
                        let len: usize = line.trim().strip_prefix('$').unwrap().parse().unwrap();
                        let mut arg = vec![0; len + 2];
                        reader.read_exact(&mut arg).await.unwrap();
                        arg.truncate(len);
                        args.push(arg);
                    }
                    match args[0].as_slice() {
                        b"AUTH" => {
                            assert_eq!(Some(&args), auth.as_ref());
                            authenticated = true;
                            writer.write_all(b"+OK\r\n").await.unwrap();
                        }
                        b"CLIENT" => writer.write_all(b"+OK\r\n").await.unwrap(),
                        _ => {
                            assert!(authenticated);
                            let reply = script.pop_front().unwrap();
                            assert_eq!(args[0], reply.command.as_bytes());
                            tokio::time::sleep(reply.delay).await;
                            if !reply.response.is_empty() {
                                writer.write_all(&reply.response).await.unwrap();
                            }
                            // An empty response intentionally drops the socket.
                        }
                    }
                }
            }
        });
        (address, server)
    }

    fn sentinel_masters_response(port: u16) -> Vec<u8> {
        let port = port.to_string();
        let fields = ["name", "dbx1271master", "ip", "127.0.0.1", "port", &port, "flags", "master"];
        let mut response = format!("*1\r\n*{}\r\n", fields.len());
        for field in fields {
            response.push_str(&format!("${}\r\n{}\r\n", field.len(), field));
        }
        response.into_bytes()
    }

    #[tokio::test]
    async fn sentinel_discovery_and_role_keep_dbx_deadline_and_separate_credentials() {
        let role = b"*3\r\n$6\r\nmaster\r\n:0\r\n*0\r\n";
        let (master, master_server) = sentinel_mock(
            Some(("master-user", "master-password")),
            vec![
                vec![SentinelMockReply { command: "ROLE", response: role.to_vec(), delay: Duration::from_millis(650) }],
                vec![SentinelMockReply::immediate("PING", b"+PONG\r\n")],
            ],
        )
        .await;
        let (sentinel, sentinel_server) = sentinel_mock(
            Some(("sentinel-user", "sentinel-password")),
            vec![vec![SentinelMockReply {
                command: "SENTINEL",
                response: sentinel_masters_response(master.port()),
                delay: Duration::from_millis(650),
            }]],
        )
        .await;
        let mut config = redis_test_connection_config();
        config.redis_sentinel_nodes = sentinel.to_string();
        config.redis_sentinel_master = "dbx1271master".to_string();
        config.redis_sentinel_username = "sentinel-user".to_string();
        config.redis_sentinel_password = "sentinel-password".to_string();
        config.username = "master-user".to_string();
        config.password = "master-password".to_string();
        super::connect_sentinel_with_timeout(&config, Duration::from_secs(5)).await.unwrap();
        sentinel_server.await.unwrap();
        master_server.await.unwrap();
    }

    #[tokio::test]
    async fn sentinel_lookup_outer_deadline_is_still_enforced() {
        // The open socket never sends a handshake response.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let mut config = redis_test_connection_config();
        config.redis_sentinel_nodes = listener.local_addr().unwrap().to_string();
        config.redis_sentinel_master = "dbx1271master".to_string();
        let error = super::connect_sentinel_with_timeout(&config, Duration::from_millis(30)).await.unwrap_err();
        assert!(error.contains("Redis Sentinel lookup timed out"));
    }

    #[test]
    fn sentinel_master_filter_preserves_service_flags_and_endpoint_validation() {
        let valid: HashMap<String, String> =
            [("name", "service"), ("ip", "127.0.0.1"), ("port", "6379"), ("flags", "master")]
                .into_iter()
                .map(|(key, value)| (key.to_string(), value.to_string()))
                .collect();
        assert_eq!(super::sentinel_eligible_master(&valid, "service").unwrap().port, 6379);
        assert!(super::sentinel_eligible_master(&valid, "missing").is_none());
        for (field, value) in [
            ("flags", "slave"),
            ("flags", "master,s_down"),
            ("flags", "master,o_down"),
            ("port", "bad"),
            ("port", "65536"),
        ] {
            let mut metadata = valid.clone();
            metadata.insert(field.to_string(), value.to_string());
            assert!(super::sentinel_eligible_master(&metadata, "service").is_none());
        }
        for field in ["name", "ip", "port", "flags"] {
            let mut metadata = valid.clone();
            metadata.remove(field);
            assert!(super::sentinel_eligible_master(&metadata, "service").is_none());
        }
    }

    #[test]
    fn sentinel_node_options_keep_tls_and_credentials_separate_from_master() {
        let mut config = redis_test_connection_config();
        config.redis_sentinel_nodes = "sentinel.example:26379".to_string();
        config.redis_sentinel_username = "sentinel-user".to_string();
        config.redis_sentinel_password = "sentinel-secret".to_string();
        config.username = "master-user".to_string();
        config.password = "master-secret".to_string();
        config.ssl = true;
        config.redis_sentinel_tls = false;
        let nodes = super::redis_sentinel_nodes(&config).unwrap();
        assert!(matches!(nodes[0].addr(), ConnectionAddr::Tcp(_, 26379)));
        assert_eq!(nodes[0].redis_settings().username(), Some("sentinel-user"));
        assert_eq!(nodes[0].redis_settings().password(), Some("sentinel-secret"));
        assert_eq!(nodes[0].redis_settings().db(), 0);

        config.ssl = false;
        config.redis_sentinel_tls = true;
        config.url_params = Some("tls_insecure=true".to_string());
        let nodes = super::redis_sentinel_nodes(&config).unwrap();
        assert!(matches!(nodes[0].addr(), ConnectionAddr::TcpTls { insecure: true, .. }));
        assert_eq!(nodes[0].redis_settings().username(), Some("sentinel-user"));
    }

    #[tokio::test]
    async fn sentinel_role_fallback_and_error_priority_match_previous_client() {
        let parsed_error =
            |response: &str| redis::parse_redis_value(response.as_bytes()).unwrap().extract_error().unwrap_err();
        let unknown = || parsed_error("-ERR unknown command 'ROLE'\r\n");
        let primary = RedisRawValue::Array(vec![bulk("master"), RedisRawValue::Int(0), RedisRawValue::Array(vec![])]);
        let replica = RedisRawValue::Array(vec![
            bulk("slave"),
            bulk("127.0.0.1"),
            RedisRawValue::Int(6379),
            bulk("connected"),
            RedisRawValue::Int(0),
        ]);
        let mut con = FakeRedisConnection::new(vec![primary]);
        assert!(super::sentinel_is_master(&mut con).await.unwrap());
        assert_eq!(con.command_count("INFO"), 0);
        let mut con = FakeRedisConnection::new(vec![replica]);
        assert!(!super::sentinel_is_master(&mut con).await.unwrap());
        assert_eq!(con.command_count("INFO"), 0);
        for role in ["master", "slave"] {
            let mut con = FakeRedisConnection::with_results(vec![
                Err(unknown()),
                Ok(bulk(&format!("# Replication\r\nrole:{role}\r\n"))),
            ]);
            assert_eq!(super::sentinel_is_master(&mut con).await.unwrap(), role == "master");
        }
        // The old client also accepts successful INFO after a denied ROLE.
        let mut con = FakeRedisConnection::with_results(vec![Err(noperm("role")), Ok(bulk("role:master\r\n"))]);
        assert!(super::sentinel_is_master(&mut con).await.unwrap());
        let mut con = FakeRedisConnection::with_results(vec![Err(unknown()), Err(noperm("info"))]);
        assert!(super::sentinel_is_master(&mut con).await.unwrap_err().detail().unwrap().contains("info"));
        let mut con = FakeRedisConnection::with_results(vec![Err(noperm("role")), Err(noperm("info"))]);
        assert!(super::sentinel_is_master(&mut con).await.unwrap_err().detail().unwrap().contains("role"));
        let mut con = FakeRedisConnection::with_results(vec![Err(unknown()), Ok(bulk("# no role\r\n"))]);
        assert!(super::sentinel_is_master(&mut con).await.unwrap_err().to_string().contains("Missing role"));
        let io = redis::RedisError::from(std::io::Error::new(std::io::ErrorKind::ConnectionReset, "reset"));
        let mut con = FakeRedisConnection::with_results(vec![Err(io), Err(noperm("info"))]);
        assert!(super::sentinel_is_master(&mut con).await.unwrap_err().is_io_error());
    }

    #[tokio::test]
    async fn sentinel_discovery_retries_io_once_and_tries_next_node_on_error() {
        let empty_masters = b"*0\r\n";
        let (first, first_server) = sentinel_mock(
            None,
            vec![
                vec![SentinelMockReply::immediate("SENTINEL", b"")],
                vec![SentinelMockReply::immediate("SENTINEL", b"-NOPERM sentinel denied\r\n")],
            ],
        )
        .await;
        let (second, second_server) =
            sentinel_mock(None, vec![vec![SentinelMockReply::immediate("SENTINEL", empty_masters)]]).await;
        let nodes = [first, second]
            .into_iter()
            .map(|node| connection_info("127.0.0.1", node.port(), false, false, "", "", 0).unwrap())
            .collect::<Vec<_>>();
        assert!(super::sentinel_masters(&nodes, None).await.unwrap().is_empty());
        first_server.await.unwrap();
        second_server.await.unwrap();
    }

    fn text_blob(value: &str) -> RedisBlob {
        redis_blob_from_bytes(value.as_bytes())
    }

    fn redis_value(redis_type: &str, data: RedisValueData) -> RedisValue {
        RedisValue {
            key_display: "test:key".to_string(),
            key_raw: redis_key_bytes_to_raw(b"test:key"),
            ttl: -1,
            redis_type: redis_type.to_string(),
            data,
        }
    }

    fn string_value(value: &str) -> RedisValue {
        redis_value(
            "string",
            RedisValueData::String {
                content: text_blob(value),
                total_bytes: Some(value.len() as u64),
                truncated: false,
            },
        )
    }

    fn hash_value(entries: &[(&str, &str)]) -> RedisValue {
        redis_value(
            "hash",
            RedisValueData::Hash {
                items: entries
                    .iter()
                    .map(|(field, value)| RedisHashItem {
                        field: text_blob(field),
                        value: text_blob(value),
                        field_ttl: None,
                    })
                    .collect(),
                total: entries.len() as u64,
                scan_cursor: None,
            },
        )
    }

    fn set_value(entries: &[&str]) -> RedisValue {
        redis_value(
            "set",
            RedisValueData::Set {
                items: entries.iter().map(|value| RedisSetItem { member: text_blob(value) }).collect(),
                total: entries.len() as u64,
                scan_cursor: None,
            },
        )
    }

    #[tokio::test]
    async fn db0_console_command_continues_when_select_is_unavailable() {
        let select_error = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "unknown command 'select', with args beginning with: '0'".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![Err(select_error), Ok(bulk("Ada"))]);

        let result = super::execute_console_command(&mut con, 0, "GET name", false).await.unwrap();

        assert_eq!(result.command, "GET");
        assert_eq!(result.value, serde_json::json!("Ada"));
        assert_eq!(con.command_count("SELECT"), 1);
        assert_eq!(con.command_count("GET"), 1);
    }

    #[tokio::test]
    async fn console_command_keeps_supported_db_zero_selection() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Okay, bulk("Ada")]);

        let result = super::execute_console_command(&mut con, 0, "GET name", false).await.unwrap();

        assert_eq!(result.value, serde_json::json!("Ada"));
        assert_eq!(con.command_count("SELECT"), 1);
        assert_eq!(con.command_count("GET"), 1);
    }

    #[tokio::test]
    async fn console_command_does_not_ignore_unavailable_select_for_nonzero_db() {
        let select_error = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "unknown command 'select', with args beginning with: '1'".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![Err(select_error), Ok(bulk("wrong db"))]);

        let error = super::execute_console_command(&mut con, 1, "GET name", false).await.unwrap_err();

        assert!(error.contains("unknown command"));
        assert_eq!(con.command_count("SELECT"), 1);
        assert_eq!(con.command_count("GET"), 0);
    }

    #[tokio::test]
    async fn console_command_propagates_non_compatibility_select_errors() {
        let errors = vec![
            redis::RedisError::from((
                redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
                "An error was signalled by the server",
                "invalid DB index".to_string(),
            )),
            noperm("SELECT"),
            redis::RedisError::from((redis::ErrorKind::AuthenticationFailed, "Authentication failed")),
            redis::RedisError::from((redis::ErrorKind::Parse, "Invalid response")),
            redis::RedisError::from(std::io::Error::new(std::io::ErrorKind::ConnectionReset, "connection reset")),
        ];

        for select_error in errors {
            let mut con = FakeRedisConnection::with_results(vec![Err(select_error), Ok(bulk("must not run"))]);

            assert!(super::execute_console_command(&mut con, 0, "GET name", false).await.is_err());
            assert_eq!(con.command_count("SELECT"), 1);
            assert_eq!(con.command_count("GET"), 0);
        }
    }

    #[tokio::test]
    async fn strict_database_selection_keeps_unavailable_select_error() {
        let select_error = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "unknown command 'select'".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![Err(select_error)]);

        assert!(super::select_db(&mut con, 0).await.is_err());
    }

    #[test]
    fn parses_stream_entries() {
        let raw = RedisRawValue::Array(vec![RedisRawValue::Array(vec![
            bulk("1714470000000-0"),
            RedisRawValue::Array(vec![bulk("event"), bulk("login"), bulk("user_id"), bulk("42")]),
        ])]);

        let parsed = parse_stream_entries(raw);

        assert_eq!(
            parsed,
            vec![RedisStreamEntry {
                id: "1714470000000-0".to_string(),
                fields: vec![
                    RedisStreamField { field: "event".to_string(), value: "login".to_string() },
                    RedisStreamField { field: "user_id".to_string(), value: "42".to_string() },
                ],
            }]
        );
    }

    #[test]
    fn skips_malformed_stream_entries() {
        let raw = RedisRawValue::Array(vec![
            RedisRawValue::Array(vec![bulk("1714470000000-0")]),
            RedisRawValue::Array(vec![
                bulk("1714470000001-0"),
                RedisRawValue::Array(vec![bulk("event"), bulk("logout")]),
            ]),
        ]);

        let parsed = parse_stream_entries(raw);

        assert_eq!(
            parsed,
            vec![RedisStreamEntry {
                id: "1714470000001-0".to_string(),
                fields: vec![RedisStreamField { field: "event".to_string(), value: "logout".to_string() }],
            }]
        );
    }

    #[test]
    fn parses_stream_groups_with_binary_names_and_compatible_optional_fields() {
        let raw = RedisRawValue::Array(vec![
            RedisRawValue::Array(vec![
                bulk("name"),
                RedisRawValue::BulkString(vec![0xFF, b'g']),
                bulk("consumers"),
                RedisRawValue::Int(2),
                bulk("pending"),
                bulk("3"),
                bulk("last-delivered-id"),
                bulk("1714470000000-0"),
                bulk("entries-read"),
                RedisRawValue::Int(11),
                bulk("lag"),
                RedisRawValue::Nil,
                bulk("future-field"),
                bulk("ignored"),
            ]),
            RedisRawValue::Array(vec![
                bulk("name"),
                bulk("legacy-group"),
                bulk("consumers"),
                RedisRawValue::Int(0),
                bulk("pending"),
                RedisRawValue::Int(0),
                bulk("last-delivered-id"),
                bulk("0-0"),
            ]),
        ]);

        let parsed = parse_stream_groups(raw);

        assert_eq!(parsed.len(), 2);
        assert_eq!(parsed[0].name, redis_blob_from_bytes(&[0xFF, b'g']));
        assert_eq!(
            parsed[0],
            RedisStreamGroup {
                name: redis_blob_from_bytes(&[0xFF, b'g']),
                consumers: 2,
                pending: 3,
                last_delivered_id: "1714470000000-0".to_string(),
                entries_read: Some(11),
                lag: None,
            }
        );
        assert_eq!(
            parsed[1],
            RedisStreamGroup {
                name: text_blob("legacy-group"),
                consumers: 0,
                pending: 0,
                last_delivered_id: "0-0".to_string(),
                entries_read: None,
                lag: None,
            }
        );
    }

    #[test]
    fn parses_stream_consumers_and_pending_entries() {
        let consumers = parse_stream_consumers(RedisRawValue::Array(vec![
            RedisRawValue::Array(vec![
                bulk("name"),
                bulk("worker-a"),
                bulk("pending"),
                RedisRawValue::Int(4),
                bulk("idle"),
                bulk("1200"),
                bulk("inactive"),
                RedisRawValue::Int(800),
            ]),
            RedisRawValue::Array(vec![
                bulk("name"),
                bulk("legacy-worker"),
                bulk("pending"),
                RedisRawValue::Int(0),
                bulk("idle"),
                RedisRawValue::Int(0),
            ]),
        ]));
        let pending = parse_stream_pending_entries(RedisRawValue::Array(vec![
            RedisRawValue::Array(vec![
                bulk("1714470000000-0"),
                RedisRawValue::BulkString(vec![0xFE, b'c']),
                RedisRawValue::Int(2_400),
                bulk("3"),
            ]),
            RedisRawValue::Array(vec![bulk("malformed")]),
        ]));

        assert_eq!(
            consumers,
            vec![
                RedisStreamConsumer { name: text_blob("worker-a"), pending: 4, idle_ms: 1_200, inactive_ms: Some(800) },
                RedisStreamConsumer { name: text_blob("legacy-worker"), pending: 0, idle_ms: 0, inactive_ms: None },
            ]
        );
        assert_eq!(
            pending,
            vec![RedisStreamPendingEntry {
                id: "1714470000000-0".to_string(),
                consumer: redis_blob_from_bytes(&[0xFE, b'c']),
                idle_ms: 2_400,
                deliveries: 3,
            }]
        );
    }

    #[test]
    fn serializes_stream_metrics_without_losing_javascript_precision() {
        let unsafe_value = super::JS_MAX_SAFE_INTEGER + 1;
        let group = RedisStreamGroup {
            name: text_blob("payments"),
            consumers: unsafe_value,
            pending: 2,
            last_delivered_id: "1714470000000-0".to_string(),
            entries_read: Some(unsafe_value),
            lag: None,
        };
        let consumer = RedisStreamConsumer {
            name: text_blob("worker-a"),
            pending: 2,
            idle_ms: unsafe_value,
            inactive_ms: Some(unsafe_value),
        };
        let entry = RedisStreamPendingEntry {
            id: "1714470000000-0".to_string(),
            consumer: text_blob("worker-a"),
            idle_ms: 2,
            deliveries: unsafe_value,
        };

        let group_json = serde_json::to_value(group).unwrap();
        let consumer_json = serde_json::to_value(consumer).unwrap();
        let entry_json = serde_json::to_value(entry).unwrap();

        assert_eq!(group_json["consumers"], unsafe_value.to_string());
        assert_eq!(group_json["pending"].as_u64(), Some(2));
        assert_eq!(group_json["entries_read"], unsafe_value.to_string());
        assert!(group_json.get("lag").is_none());
        assert_eq!(consumer_json["idle_ms"], unsafe_value.to_string());
        assert_eq!(consumer_json["inactive_ms"], unsafe_value.to_string());
        assert_eq!(entry_json["deliveries"], unsafe_value.to_string());
    }

    /// The `(start, end)` windows DBX requested with GETRANGE.
    fn getrange_windows(con: &FakeRedisConnection) -> Vec<(String, String)> {
        con.commands
            .iter()
            .filter(|packed| packed.contains("\r\nGETRANGE\r\n"))
            .map(|packed| {
                let parts: Vec<&str> = packed.split("\r\n").collect();
                let last = parts.len();
                (parts[last - 4].to_string(), parts[last - 2].to_string())
            })
            .collect()
    }

    #[tokio::test]
    async fn string_value_uses_a_bounded_range_for_small_values() {
        let mut con = FakeRedisConnection::new(vec![bulk("string"), RedisRawValue::Int(-1), bulk("hello")]);

        let value = super::get_value(&mut con, b"message").await.unwrap();

        let RedisValueData::String { content, total_bytes, truncated } = &value.data else {
            panic!("expected a String value");
        };
        assert_eq!(redis_blob_display_text(content), "hello");
        assert_eq!(*total_bytes, Some(5));
        assert!(!truncated);
        assert_eq!(con.command_count("GETRANGE"), 1);
        assert_eq!(con.command_count("GET"), 0);
        assert_eq!(con.command_count("STRLEN"), 0);
    }

    #[tokio::test]
    async fn string_value_range_stays_within_the_64kib_window_limit() {
        // A window never exceeds 64 KiB, so a configured preview above that is
        // fetched in chunks (issue #11792).
        let mut con = FakeRedisConnection::new(vec![bulk("string"), RedisRawValue::Int(-1), bulk("hello")]);

        super::get_value(&mut con, b"message").await.unwrap();

        let getrange =
            con.commands.iter().find(|packed| packed.contains("\r\nGETRANGE\r\n")).expect("GETRANGE is issued");
        assert!(getrange.contains(&format!("\r\n$5\r\n{}\r\n", super::STRING_PREVIEW_MAX_BYTES - 1)), "{getrange:?}");
        assert!(!getrange.contains(&format!("\r\n$5\r\n{}\r\n", super::STRING_PREVIEW_MAX_BYTES)), "{getrange:?}");
    }

    #[tokio::test]
    async fn string_value_falls_back_to_the_value_length_when_the_server_rejects_the_window() {
        // Issue #13114: TongRDS does not clamp a GETRANGE window that reaches
        // past the value the way Redis does: it answers "ERR 0-65536 is out of
        // bounds", which left the key detail empty for every string shorter
        // than the preview window. The read has to fall back to the exact
        // value length.
        let out_of_bounds = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "ERR",
            "0-65536 is out of bounds".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("string")),
            Ok(RedisRawValue::Int(-1)),
            Err(out_of_bounds),
            Ok(RedisRawValue::Int(3)),
            Ok(bulk("123")),
        ]);

        let value = super::get_value(&mut con, b"123").await.unwrap();

        let RedisValueData::String { content, total_bytes, truncated } = &value.data else {
            panic!("expected a String value");
        };
        assert_eq!(redis_blob_display_text(content), "123");
        assert_eq!(*total_bytes, Some(3));
        assert!(!truncated);
        // The retry asks for the value instead of the whole preview window.
        assert_eq!(
            getrange_windows(&con),
            vec![("0".to_string(), "65535".to_string()), ("0".to_string(), "2".to_string())]
        );
        assert_eq!(con.command_count("GETRANGE"), 2);
        assert_eq!(con.command_count("STRLEN"), 1);
    }

    #[tokio::test]
    async fn string_value_fails_fast_when_a_strict_server_also_refuses_strlen() {
        // The bounded fallback needs the value length. Without it the rejected
        // window cannot be narrowed, so the read fails instead of asking for
        // the same rejected window again.
        let out_of_bounds = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "ERR",
            "0-65536 is out of bounds".to_string(),
        ));
        let denied = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "ERR",
            "NOPERM this user has no permissions to run the 'strlen' command".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("string")),
            Ok(RedisRawValue::Int(-1)),
            Err(out_of_bounds),
            Err(denied),
        ]);

        let error = super::get_value(&mut con, b"message").await.unwrap_err();

        assert!(error.contains("out of bounds"), "{error}");
        // The error also says why the fallback could not run.
        assert!(error.contains("the value length could not be read"), "{error}");
        assert!(error.contains("strlen"), "{error}");
        // One rejected window and one length read; the rejected window is not
        // requested again.
        assert_eq!(con.command_count("GETRANGE"), 1);
        assert_eq!(con.command_count("STRLEN"), 1);
    }

    #[tokio::test]
    async fn string_value_reports_a_failed_length_read_after_the_value_shrinks() {
        // The value shrank between the length read and the window read, and the
        // fresh length read fails as well. The error has to say so instead of
        // surfacing the bare rejection.
        let out_of_bounds = || {
            redis::RedisError::from((
                redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
                "ERR",
                "0-100 is out of bounds".to_string(),
            ))
        };
        let denied = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "ERR",
            "NOPERM this user has no permissions to run the 'strlen' command".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("string")),
            Ok(RedisRawValue::Int(-1)),
            Err(out_of_bounds()),
            Ok(RedisRawValue::Int(100)),
            Err(out_of_bounds()),
            Err(denied),
        ]);

        let error = super::get_value(&mut con, b"message").await.unwrap_err();

        assert!(error.contains("out of bounds"), "{error}");
        assert!(error.contains("the value length could not be read"), "{error}");
        assert!(error.contains("strlen"), "{error}");
        // One rejected window, one bounded window and two length reads; the
        // rejected window is not requested again.
        assert_eq!(con.command_count("GETRANGE"), 2);
        assert_eq!(con.command_count("STRLEN"), 2);
    }

    #[tokio::test]
    async fn string_value_retries_when_the_value_shrinks() {
        // The value was 100 bytes when its length was read and 10 bytes when
        // the window was requested. The read is retried against the fresh
        // length instead of failing.
        let out_of_bounds = || {
            redis::RedisError::from((
                redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
                "ERR",
                "0-100 is out of bounds".to_string(),
            ))
        };
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("string")),
            Ok(RedisRawValue::Int(-1)),
            Err(out_of_bounds()),
            Ok(RedisRawValue::Int(100)),
            Err(out_of_bounds()),
            Ok(RedisRawValue::Int(10)),
            Ok(bulk("0123456789")),
        ]);

        let value = super::get_value(&mut con, b"message").await.unwrap();

        let RedisValueData::String { content, total_bytes, truncated } = &value.data else {
            panic!("expected a String value");
        };
        assert_eq!(redis_blob_display_text(content), "0123456789");
        assert_eq!(*total_bytes, Some(10));
        assert!(!truncated);
        assert_eq!(con.command_count("GETRANGE"), 3);
        assert_eq!(con.command_count("STRLEN"), 2);
    }

    #[tokio::test]
    async fn string_value_reports_other_errors_without_retrying() {
        let denied = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "ERR",
            "NOPERM this user has no permissions to run the 'getrange' command".to_string(),
        ));
        let mut con =
            FakeRedisConnection::with_results(vec![Ok(bulk("string")), Ok(RedisRawValue::Int(-1)), Err(denied)]);

        let error = super::get_value(&mut con, b"message").await.unwrap_err();

        assert!(error.contains("NOPERM"), "{error}");
        assert_eq!(con.command_count("GETRANGE"), 1);
        assert_eq!(con.command_count("STRLEN"), 0);
    }

    #[tokio::test]
    async fn string_value_at_the_preview_budget_is_not_flagged_truncated() {
        let payload = vec![b'a'; super::STRING_PREVIEW_MAX_BYTES];
        let mut con = FakeRedisConnection::new(vec![
            bulk("string"),
            RedisRawValue::Int(-1),
            RedisRawValue::BulkString(payload.clone()),
            RedisRawValue::Int(super::STRING_PREVIEW_MAX_BYTES as i64),
        ]);

        let value = super::get_value(&mut con, b"exact").await.unwrap();

        let RedisValueData::String { content, total_bytes, truncated } = &value.data else {
            panic!("expected a String value");
        };
        assert_eq!(*total_bytes, Some(super::STRING_PREVIEW_MAX_BYTES as u64));
        assert!(!truncated);
        let decoded = base64::engine::general_purpose::STANDARD.decode(&content.raw_base64).unwrap();
        assert_eq!(decoded.len(), super::STRING_PREVIEW_MAX_BYTES);
        assert_eq!(con.command_count("GETRANGE"), 1);
        assert_eq!(con.command_count("STRLEN"), 1);
    }

    #[tokio::test]
    async fn string_value_truncates_large_payloads_before_ipc_serialization() {
        let preview_with_sentinel = vec![0xFF; super::STRING_PREVIEW_MAX_BYTES + 1];
        let total_bytes = 45 * 1024 * 1024;
        let mut con = FakeRedisConnection::new(vec![
            bulk("string"),
            RedisRawValue::Int(-1),
            RedisRawValue::BulkString(preview_with_sentinel),
            RedisRawValue::Int(total_bytes as i64),
        ]);

        let value = super::get_value(&mut con, b"bf:ali_health_monitor").await.unwrap();

        let RedisValueData::String { content, total_bytes: reported_bytes, truncated } = &value.data else {
            panic!("expected a String value");
        };
        let preview = base64::engine::general_purpose::STANDARD.decode(&content.raw_base64).unwrap();
        assert_eq!(preview.len(), super::STRING_PREVIEW_MAX_BYTES);
        assert_eq!(*reported_bytes, Some(total_bytes));
        assert!(*truncated);
        assert_eq!(super::redis_search_value_size(&value), total_bytes);
        assert_eq!(con.command_count("GETRANGE"), 1);
        assert_eq!(con.command_count("GET"), 0);
        assert_eq!(con.command_count("STRLEN"), 1);
    }

    #[tokio::test]
    async fn value_preview_limit_controls_the_range_and_exact_boundary() {
        for limit in [1024, 256 * 1024, super::VALUE_PREVIEW_MAX_BYTES] {
            // A short read ends the value: the request spans min(limit, 64 KiB) and the
            // fake answers one byte less, so the total needs no STRLEN round trip.
            let span = limit.min(super::STRING_PREVIEW_MAX_BYTES);
            let size = span - 1;
            let mut con = FakeRedisConnection::new(vec![
                bulk("string"),
                RedisRawValue::Int(-1),
                RedisRawValue::BulkString(vec![b'x'; size]),
            ]);
            let value = super::get_value_scoped_with_preview_limit(
                &mut con,
                b"large",
                &super::RedisOperationScope::default(),
                limit,
            )
            .await
            .unwrap();
            let RedisValueData::String { content, total_bytes, truncated } = value.data else {
                panic!("expected string")
            };
            assert!(!truncated);
            assert_eq!(total_bytes, Some(size as u64));
            assert_eq!(content.raw_base64, base64::engine::general_purpose::STANDARD.encode(vec![b'x'; size]));
            let getrange =
                con.commands.iter().find(|packed| packed.contains("\r\nGETRANGE\r\n")).expect("GETRANGE is issued");
            assert!(getrange.contains(&format!("\r\n{}\r\n", span - 1)), "{getrange:?}");
            assert!(!getrange.contains(&format!("\r\n{}\r\n", span)), "{getrange:?}");
            assert_eq!(con.command_count("GETRANGE"), 1);
            assert_eq!(con.command_count("GET"), 0);
            assert_eq!(con.command_count("STRLEN"), 0);
        }
        // A configured limit above the 64 KiB window limit is fetched in 64 KiB chunks,
        // and filling the budget exactly asks STRLEN for the real size.
        let limit = 128 * 1024;
        let mut con = FakeRedisConnection::new(vec![
            bulk("string"),
            RedisRawValue::Int(-1),
            RedisRawValue::BulkString(vec![0xff; super::STRING_PREVIEW_MAX_BYTES]),
            RedisRawValue::BulkString(vec![0xff; super::STRING_PREVIEW_MAX_BYTES]),
            RedisRawValue::Int(200_000),
        ]);
        let value = super::get_value_scoped_with_preview_limit(
            &mut con,
            b"binary",
            &super::RedisOperationScope::default(),
            limit,
        )
        .await
        .unwrap();
        let RedisValueData::String { content, total_bytes, truncated } = value.data else { panic!("expected string") };
        assert!(truncated);
        assert_eq!(total_bytes, Some(200_000));
        assert_eq!(base64::engine::general_purpose::STANDARD.decode(content.raw_base64).unwrap().len(), limit);
        assert_eq!(con.command_count("GETRANGE"), 2);
        assert_eq!(con.command_count("STRLEN"), 1);
    }

    /// Live check for servers that reject a GETRANGE window that reaches past
    /// the value. TongRDS answers `ERR 0-65536 is out of bounds` there, which
    /// left the key detail empty, so the preview has to read the value and
    /// report its real size.
    ///
    /// Set `DBX_TEST_REDIS_STRING_KEY` to read an existing key instead of
    /// writing a temporary one.
    #[tokio::test]
    #[ignore = "requires a disposable Redis via DBX_TEST_REDIS_URL"]
    async fn string_preview_reads_the_value_on_strict_range_servers() {
        let url = std::env::var("DBX_TEST_REDIS_URL").expect("DBX_TEST_REDIS_URL");
        let existing = std::env::var("DBX_TEST_REDIS_STRING_KEY").ok();
        let key = existing.clone().unwrap_or_else(|| "dbx-string-preview-probe".to_string());
        let mut con = super::connect(&url, std::time::Duration::from_secs(5)).await.unwrap();
        if existing.is_none() {
            let _: () = redis::cmd("SET").arg(&key).arg("123").query_async(&mut con).await.unwrap();
        }
        let expected_len: i64 = redis::cmd("STRLEN").arg(&key).query_async(&mut con).await.unwrap();

        let value = super::get_value(&mut con, key.as_bytes()).await.unwrap();

        let RedisValueData::String { content, total_bytes, truncated } = value.data else {
            panic!("expected a String value");
        };
        assert_eq!(total_bytes, Some(expected_len as u64));
        assert!(!truncated);
        let decoded = base64::engine::general_purpose::STANDARD.decode(&content.raw_base64).unwrap();
        assert_eq!(decoded.len() as u64, expected_len as u64);
        if existing.is_none() {
            let _: u64 = redis::cmd("DEL").arg(&key).query_async(&mut con).await.unwrap();
        }
    }

    #[tokio::test]
    async fn value_preview_limit_rejects_invalid_sizes_before_redis_io() {
        for limit in [0, 1023, super::VALUE_PREVIEW_MAX_BYTES + 1, usize::MAX] {
            let mut con = FakeRedisConnection::new(vec![]);
            assert!(super::get_value_scoped_with_preview_limit(
                &mut con,
                b"key",
                &super::RedisOperationScope::default(),
                limit,
            )
            .await
            .is_err());
            assert!(con.commands.is_empty());
        }
    }

    #[tokio::test]
    async fn bitmap_preview_uses_the_configured_limit() {
        let mut con = FakeRedisConnection::new(vec![
            bulk("bitmap"),
            RedisRawValue::Int(-1),
            RedisRawValue::BulkString(vec![0x80; 4097]),
            RedisRawValue::Int(4097),
        ]);
        let value = super::get_value_scoped_with_preview_limit(
            &mut con,
            b"bitmap",
            &super::RedisOperationScope::default(),
            4096,
        )
        .await
        .unwrap();
        let RedisValueData::Bitmap { content, total_bytes, truncated, .. } = value.data else {
            panic!("expected bitmap")
        };
        assert!(truncated);
        assert_eq!(total_bytes, None);
        assert_eq!(base64::engine::general_purpose::STANDARD.decode(content.raw_base64).unwrap().len(), 4096);
    }

    #[test]
    fn collection_pages_stop_at_the_byte_budget_without_truncating_a_member() {
        fn hash_items(count: usize, value_bytes: usize) -> Vec<RedisHashItem> {
            (0..count)
                .map(|index| RedisHashItem {
                    field: text_blob(&format!("f{index}")),
                    value: text_blob(&"v".repeat(value_bytes)),
                    field_ttl: None,
                })
                .collect()
        }
        fn page_bytes(items: &[RedisHashItem]) -> usize {
            items.iter().map(super::hash_item_page_bytes).sum()
        }

        // Members are sized as a fraction of the budget; base64 inflates them by 4/3 on the wire,
        // so the assertions below are on the resulting page rather than on a hand-computed count.
        for divisor in [2, 3, 8] {
            let items = hash_items(200, super::COLLECTION_PAGE_MAX_BYTES / divisor);
            let page_len = super::budgeted_page_len(&items, 200, super::hash_item_page_bytes);
            assert!((1..200).contains(&page_len), "divisor {divisor}: page_len {page_len}");
            assert!(
                page_bytes(&items[..page_len]) <= super::COLLECTION_PAGE_MAX_BYTES,
                "divisor {divisor} over budget"
            );
            assert!(
                page_bytes(&items[..page_len + 1]) > super::COLLECTION_PAGE_MAX_BYTES,
                "divisor {divisor}: page ended earlier than the budget required"
            );
        }

        // Small members still fill a whole page, and a short input is returned whole.
        let small = hash_items(500, 1);
        assert_eq!(super::budgeted_page_len(&small, 200, super::hash_item_page_bytes), 200);
        assert_eq!(super::budgeted_page_len(&small[..5], 200, super::hash_item_page_bytes), 5);

        // A single member larger than the whole budget still loads, so paging cannot stall.
        let huge = hash_items(3, super::COLLECTION_PAGE_MAX_BYTES * 2);
        assert_eq!(super::budgeted_page_len(&huge, 200, super::hash_item_page_bytes), 1);

        assert_eq!(super::budgeted_page_len::<RedisHashItem>(&[], 200, super::hash_item_page_bytes), 0);
    }

    #[tokio::test]
    async fn hash_value_pages_compact_hscan_before_field_ttls() {
        let pairs = (0..512).map(|index| (format!("field:{index}"), format!("value:{index}"))).collect();
        let mut con = FakeRedisConnection::new(vec![
            bulk("hash"),
            RedisRawValue::Int(-1),
            RedisRawValue::Int(512),
            hscan_response_owned("0", pairs),
            httl_response(super::COLLECTION_PAGE_SIZE, -1),
            httl_response(super::COLLECTION_PAGE_SIZE, -1),
            httl_response(112, -1),
        ]);

        let value = super::get_value(&mut con, b"large-hash").await.unwrap();

        let RedisValueData::Hash { items, total, scan_cursor } = value.data else {
            panic!("expected a Hash value");
        };
        let cursor = scan_cursor.expect("overflow cursor");
        assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);
        assert_eq!(total, 512);
        assert_eq!(items.len(), super::COLLECTION_PAGE_SIZE);
        assert_eq!(redis_blob_display_text(&items[0].field), "field:0");
        assert_eq!(redis_blob_display_text(&items[199].field), "field:199");
        assert!(items.iter().all(|item| item.field_ttl == Some(-1)));
        assert_eq!(con.command_count("HSCAN"), 1);
        assert_eq!(con.command_count("HTTL"), 1);
        let httl_command = con.commands.iter().find(|command| command.contains("\r\nHTTL\r\n")).unwrap();
        assert!(httl_command.contains("\r\nFIELDS\r\n"));
        assert!(httl_command.contains("\r\n200\r\n"));
        assert!(!httl_command.contains("\r\nfield:200\r\n"));

        let second =
            super::load_more_collection(&mut con, b"large-hash", "hash", cursor, 200, None, None).await.unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = second else {
            panic!("expected a Hash page");
        };
        assert_eq!(scan_cursor, Some(cursor));
        assert_eq!(items.len(), 200);
        assert_eq!(redis_blob_display_text(&items[0].field), "field:200");
        assert_eq!(redis_blob_display_text(&items[199].field), "field:399");
        assert_eq!(con.command_count("HSCAN"), 1);
        assert_eq!(con.command_count("HTTL"), 2);

        let third =
            super::load_more_collection(&mut con, b"large-hash", "hash", cursor, 200, None, None).await.unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = third else {
            panic!("expected a Hash page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(items.len(), 112);
        assert_eq!(redis_blob_display_text(&items[0].field), "field:400");
        assert_eq!(redis_blob_display_text(&items[111].field), "field:511");
        assert_eq!(con.command_count("HSCAN"), 1);
        assert_eq!(con.command_count("HTTL"), 3);
    }

    #[tokio::test]
    async fn large_hash_value_stays_bounded_when_httl_is_unsupported() {
        let pairs = (0..512).map(|index| (format!("field:{index}"), format!("value:{index}"))).collect();
        let unsupported = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "unknown command 'HTTL'".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("hash")),
            Ok(RedisRawValue::Int(-1)),
            Ok(RedisRawValue::Int(512)),
            Ok(hscan_response_owned("0", pairs)),
            Err(unsupported),
        ]);

        let value = super::get_value(&mut con, b"large-hash-no-httl").await.unwrap();

        let RedisValueData::Hash { items, total, scan_cursor } = value.data else {
            panic!("expected a Hash value");
        };
        assert_eq!(total, 512);
        assert_eq!(items.len(), super::COLLECTION_PAGE_SIZE);
        assert!(scan_cursor.is_some());
        assert!(items.iter().all(|item| item.field_ttl.is_none()));
        assert_eq!(con.command_count("HSCAN"), 1);
        assert_eq!(con.command_count("HTTL"), 1);
    }

    #[tokio::test]
    async fn set_value_pages_compact_sscan_response() {
        let members = (0..512).map(|index| format!("member:{index}")).collect();
        let mut con = FakeRedisConnection::new(vec![
            bulk("set"),
            RedisRawValue::Int(-1),
            RedisRawValue::Int(512),
            int_scan_response_owned("0", members),
        ]);

        let value = super::get_value(&mut con, b"large-intset").await.unwrap();

        let RedisValueData::Set { items, total, scan_cursor } = value.data else {
            panic!("expected a Set value");
        };
        let cursor = scan_cursor.expect("overflow cursor");
        assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);
        assert_eq!(total, 512);
        assert_eq!(items.len(), super::COLLECTION_PAGE_SIZE);
        assert_eq!(redis_blob_display_text(&items[0].member), "member:0");
        assert_eq!(redis_blob_display_text(&items[199].member), "member:199");

        let second =
            super::load_more_collection(&mut con, b"large-intset", "set", cursor, 200, None, None).await.unwrap();
        let RedisCollectionPage::Set { items, scan_cursor } = second else {
            panic!("expected a Set page");
        };
        assert_eq!(scan_cursor, Some(cursor));
        assert_eq!(items.len(), 200);
        assert_eq!(redis_blob_display_text(&items[0].member), "member:200");
        assert_eq!(redis_blob_display_text(&items[199].member), "member:399");

        let third =
            super::load_more_collection(&mut con, b"large-intset", "set", cursor, 200, None, None).await.unwrap();
        let RedisCollectionPage::Set { items, scan_cursor } = third else {
            panic!("expected a Set page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(items.len(), 112);
        assert_eq!(redis_blob_display_text(&items[0].member), "member:400");
        assert_eq!(redis_blob_display_text(&items[111].member), "member:511");
        assert_eq!(con.command_count("SSCAN"), 1);
    }

    #[tokio::test]
    async fn stream_value_uses_xlen_for_its_total_size() {
        let entries = RedisRawValue::Array(vec![RedisRawValue::Array(vec![
            bulk("1714470000000-0"),
            RedisRawValue::Array(vec![bulk("event"), bulk("login")]),
        ])]);
        let mut con =
            FakeRedisConnection::new(vec![bulk("stream"), RedisRawValue::Int(-1), RedisRawValue::Int(177), entries]);

        let value = super::get_value(&mut con, b"orders").await.unwrap();

        let RedisValueData::Stream { entries, total, next_cursor } = &value.data else {
            panic!("expected a Stream value");
        };
        assert_eq!(*total, Some(177));
        assert_eq!(entries.len(), 1);
        assert!(next_cursor.is_none());
        assert_eq!(super::redis_search_value_size(&value), 177);
        assert_eq!(con.command_count("TYPE"), 1);
        assert_eq!(con.command_count("TTL"), 1);
        assert_eq!(con.command_count("XLEN"), 1);
        assert_eq!(con.command_count("XRANGE"), 1);
        assert_eq!(con.commands.len(), 2);
    }

    #[tokio::test]
    async fn stream_value_still_loads_when_xlen_is_not_permitted() {
        let entries = RedisRawValue::Array(vec![RedisRawValue::Array(vec![
            bulk("1714470000000-0"),
            RedisRawValue::Array(vec![bulk("event"), bulk("login")]),
        ])]);
        let xlen_denied = || {
            redis::make_extension_error(
                "NOPERM".to_string(),
                Some("this user has no permissions to run the 'xlen' command".to_string()),
            )
        };
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("stream")),
            Ok(RedisRawValue::Int(-1)),
            Err(xlen_denied()),
            Ok(RedisRawValue::Int(-1)),
            Err(xlen_denied()),
            Ok(entries),
        ]);

        let value = super::get_value(&mut con, b"orders").await.unwrap();

        let RedisValueData::Stream { entries, total, .. } = &value.data else {
            panic!("expected a Stream value");
        };
        assert_eq!(entries.len(), 1);
        assert_eq!(*total, None);
        assert_eq!(super::redis_search_value_size(&value), 1);
        assert!(serde_json::to_value(&value).unwrap()["data"].get("total").is_none());
        assert_eq!(con.command_count("XLEN"), 2);
        assert_eq!(con.command_count("XRANGE"), 2);
    }

    #[tokio::test]
    async fn stream_entry_first_page_exposes_a_cursor_when_more_entries_exist() {
        let entries = RedisRawValue::Array(
            (0..=50)
                .map(|index| {
                    RedisRawValue::Array(vec![
                        bulk(&format!("1714470000000-{index}")),
                        RedisRawValue::Array(vec![bulk("event"), bulk("login")]),
                    ])
                })
                .collect(),
        );
        let mut con = FakeRedisConnection::new(vec![entries]);

        let page = super::get_stream_entries_page(&mut con, b"orders", None).await.unwrap();

        assert_eq!(page.entries.len(), 50);
        assert_eq!(page.entries.first().map(|entry| entry.id.as_str()), Some("1714470000000-0"));
        assert_eq!(page.entries.last().map(|entry| entry.id.as_str()), Some("1714470000000-49"));
        assert_eq!(page.next_cursor.as_deref(), Some("1714470000000-49"));
        assert_eq!(con.command_count("XRANGE"), 1);
        assert!(con.commands[0].contains("\r\n-\r\n"));
        assert!(con.commands[0].contains("\r\n51\r\n"));
    }

    #[tokio::test]
    async fn stream_entry_pagination_reads_all_entries_across_sequential_pages() {
        let stream_entries = |start: u64, end: u64| {
            RedisRawValue::Array(
                (start..=end)
                    .map(|index| {
                        RedisRawValue::Array(vec![
                            bulk(&format!("1714470000000-{index}")),
                            RedisRawValue::Array(vec![bulk("event"), bulk("login")]),
                        ])
                    })
                    .collect(),
            )
        };
        let mut con =
            FakeRedisConnection::new(vec![stream_entries(0, 50), stream_entries(49, 100), stream_entries(99, 120)]);

        let first = super::get_stream_entries_page(&mut con, b"orders", None).await.unwrap();
        let second = super::get_stream_entries_page(&mut con, b"orders", first.next_cursor.as_deref()).await.unwrap();
        let third = super::get_stream_entries_page(&mut con, b"orders", second.next_cursor.as_deref()).await.unwrap();

        let ids = first
            .entries
            .iter()
            .chain(&second.entries)
            .chain(&third.entries)
            .map(|entry| entry.id.clone())
            .collect::<Vec<_>>();
        let expected = (0..=120).map(|index| format!("1714470000000-{index}")).collect::<Vec<_>>();

        assert_eq!(first.next_cursor.as_deref(), Some("1714470000000-49"));
        assert_eq!(second.next_cursor.as_deref(), Some("1714470000000-99"));
        assert_eq!(third.next_cursor, None);
        assert_eq!(ids, expected);
        assert_eq!(con.command_count("XRANGE"), 3);
    }

    #[tokio::test]
    async fn stream_entry_pagination_uses_a_lookahead_and_skips_the_duplicate_cursor() {
        let entries = RedisRawValue::Array(
            (17..=68)
                .map(|index| {
                    RedisRawValue::Array(vec![
                        bulk(&format!("1714470000000-{index}")),
                        RedisRawValue::Array(vec![bulk("event"), bulk("login")]),
                    ])
                })
                .collect(),
        );
        let mut con = FakeRedisConnection::new(vec![entries]);

        let page = super::get_stream_entries_page(&mut con, b"orders", Some("1714470000000-17")).await.unwrap();

        assert_eq!(page.entries.len(), 50);
        assert_eq!(page.entries.first().map(|entry| entry.id.as_str()), Some("1714470000000-18"));
        assert_eq!(page.entries.last().map(|entry| entry.id.as_str()), Some("1714470000000-67"));
        assert_eq!(page.next_cursor.as_deref(), Some("1714470000000-67"));
        assert_eq!(con.command_count("XRANGE"), 1);
        assert!(con.commands[0].contains("\r\n1714470000000-17\r\n"));
        assert!(!con.commands[0].contains("\r\n(1714470000000-17\r\n"));
        assert!(con.commands[0].contains("\r\n52\r\n"));
    }

    #[tokio::test]
    async fn stream_entry_pagination_keeps_the_first_entry_when_the_cursor_was_trimmed() {
        let entries = RedisRawValue::Array(
            (18..=68)
                .map(|index| {
                    RedisRawValue::Array(vec![
                        bulk(&format!("1714470000000-{index}")),
                        RedisRawValue::Array(vec![bulk("event"), bulk("login")]),
                    ])
                })
                .collect(),
        );
        let mut con = FakeRedisConnection::new(vec![entries]);

        let page = super::get_stream_entries_page(&mut con, b"orders", Some("1714470000000-17")).await.unwrap();

        assert_eq!(page.entries.len(), 50);
        assert_eq!(page.entries.first().map(|entry| entry.id.as_str()), Some("1714470000000-18"));
        assert_eq!(page.entries.last().map(|entry| entry.id.as_str()), Some("1714470000000-67"));
        assert_eq!(page.next_cursor.as_deref(), Some("1714470000000-67"));
    }

    #[tokio::test]
    async fn stream_monitoring_commands_are_read_only_and_pending_pagination_supports_redis_5() {
        let groups = RedisRawValue::Array(vec![RedisRawValue::Array(vec![
            bulk("name"),
            bulk("payments"),
            bulk("consumers"),
            RedisRawValue::Int(1),
            bulk("pending"),
            RedisRawValue::Int(101),
            bulk("last-delivered-id"),
            bulk("1714470000000-0"),
        ])]);
        let consumers = RedisRawValue::Array(vec![RedisRawValue::Array(vec![
            bulk("name"),
            bulk("worker-a"),
            bulk("pending"),
            RedisRawValue::Int(101),
            bulk("idle"),
            RedisRawValue::Int(10),
        ])]);
        let pending = RedisRawValue::Array(
            (17..=118)
                .map(|index| {
                    RedisRawValue::Array(vec![
                        bulk(&format!("1714470000000-{index}")),
                        bulk("worker-a"),
                        RedisRawValue::Int(index),
                        RedisRawValue::Int(1),
                    ])
                })
                .collect(),
        );
        let mut con = FakeRedisConnection::new(vec![groups, consumers, pending]);

        let groups = super::get_stream_groups(&mut con, b"orders").await.unwrap();
        let consumers = super::get_stream_consumers(&mut con, b"orders", b"payments").await.unwrap();
        let page = super::get_stream_pending_page(&mut con, b"orders", b"payments", Some("1714470000000-17"), None)
            .await
            .unwrap();

        assert_eq!(groups.len(), 1);
        assert_eq!(consumers.len(), 1);
        assert_eq!(page.entries.len(), 100);
        assert_eq!(page.entries.first().map(|entry| entry.id.as_str()), Some("1714470000000-18"));
        assert_eq!(page.entries.last().map(|entry| entry.id.as_str()), Some("1714470000000-117"));
        assert_eq!(page.next_cursor.as_deref(), Some("1714470000000-117"));
        assert_eq!(con.command_count("XINFO"), 2);
        assert_eq!(con.command_count("XPENDING"), 1);
        assert_eq!(con.command_count("XGROUP"), 0);
        assert_eq!(con.command_count("XACK"), 0);
        assert_eq!(con.command_count("XCLAIM"), 0);
        assert!(con.commands[0].contains("\r\nGROUPS\r\n"));
        assert!(con.commands[1].contains("\r\nCONSUMERS\r\n"));
        assert!(con.commands[2].contains("\r\n1714470000000-17\r\n"));
        assert!(!con.commands[2].contains("\r\n(1714470000000-17\r\n"));
        assert!(con.commands[2].contains("\r\n102\r\n"));
    }

    #[tokio::test]
    async fn stream_pending_pagination_keeps_the_first_entry_when_cursor_is_acknowledged() {
        let pending = RedisRawValue::Array(
            (18..=118)
                .map(|index| {
                    RedisRawValue::Array(vec![
                        bulk(&format!("1714470000000-{index}")),
                        bulk("worker-a"),
                        RedisRawValue::Int(index),
                        RedisRawValue::Int(1),
                    ])
                })
                .collect(),
        );
        let mut con = FakeRedisConnection::new(vec![pending]);

        let page = super::get_stream_pending_page(&mut con, b"orders", b"payments", Some("1714470000000-17"), None)
            .await
            .unwrap();

        assert_eq!(page.entries.len(), 100);
        assert_eq!(page.entries.first().map(|entry| entry.id.as_str()), Some("1714470000000-18"));
        assert_eq!(page.entries.last().map(|entry| entry.id.as_str()), Some("1714470000000-117"));
        assert_eq!(page.next_cursor.as_deref(), Some("1714470000000-117"));
        assert!(con.commands[0].contains("\r\n1714470000000-17\r\n"));
        assert!(!con.commands[0].contains("\r\n(1714470000000-17\r\n"));
        assert!(con.commands[0].contains("\r\n102\r\n"));
    }

    #[tokio::test]
    async fn stream_pending_filters_by_consumer_server_side() {
        let pending = RedisRawValue::Array(vec![RedisRawValue::Array(vec![
            bulk("1714470000000-0"),
            bulk("worker-a"),
            RedisRawValue::Int(2_400),
            RedisRawValue::Int(1),
        ])]);
        let mut con = FakeRedisConnection::new(vec![pending]);

        let page =
            super::get_stream_pending_page(&mut con, b"orders", b"payments", None, Some(b"worker-a")).await.unwrap();

        assert_eq!(page.entries.len(), 1);
        assert_eq!(con.command_count("XPENDING"), 1);
        assert!(con.commands[0].contains("\r\n-\r\n"));
        assert!(con.commands[0].contains("\r\n+\r\n"));
        assert!(con.commands[0].contains("\r\n101\r\n"));
        assert!(con.commands[0].contains("\r\nworker-a\r\n"));
    }

    #[test]
    fn parses_configured_database_count() {
        let value = RedisRawValue::Array(vec![
            RedisRawValue::BulkString(b"databases".to_vec()),
            RedisRawValue::BulkString(b"32".to_vec()),
        ]);

        assert_eq!(parse_database_count(value), Some(32));
    }

    #[test]
    fn formats_binary_keys_like_rdm() {
        let bytes = [0xAC, 0xED, 0x00, 0x05, b't', 0x00, b'A', b'\\'];

        assert_eq!(redis_key_bytes_to_display(&bytes), "\\xac\\xed\\x00\\x05t\\x00A\\\\");
    }

    #[test]
    fn preserves_utf8_keys_as_readable_text() {
        let bytes = "用户:配置".as_bytes();

        assert_eq!(redis_key_bytes_to_display(bytes), "用户:配置");
    }

    #[test]
    fn round_trips_raw_key_transport() {
        let bytes = b"\xAC\xED\x00\x05t\x00token";
        let encoded = redis_key_bytes_to_raw(bytes);

        assert_eq!(redis_key_raw_to_bytes(&encoded).unwrap(), bytes);
    }

    #[tokio::test]
    async fn set_string_uses_keepttl_when_no_ttl_is_specified() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Okay]);

        super::set_string(&mut con, b"session", "updated", None).await.unwrap();

        assert_eq!(con.commands.len(), 1);
        assert!(con.commands[0].contains("\r\nSET\r\n"));
        assert!(con.commands[0].contains("\r\nKEEPTTL\r\n"));
    }

    #[tokio::test]
    async fn set_string_with_explicit_no_expiry_uses_plain_set() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Okay]);

        super::set_string(&mut con, b"settings", "updated", Some(-1)).await.unwrap();

        assert_eq!(con.commands.len(), 1);
        assert!(con.commands[0].contains("\r\nSET\r\n"));
        assert!(!con.commands[0].contains("\r\nKEEPTTL\r\n"));
        assert!(!con.commands[0].contains("\r\nEXPIRE\r\n"));
    }

    #[tokio::test]
    async fn rename_key_uses_renamenx_without_overwriting_the_destination() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(1)]);

        super::rename_key(&mut con, b"session:old", b"session:new").await.unwrap();

        assert_eq!(con.commands.len(), 1);
        assert!(con.commands[0].contains("\r\nRENAMENX\r\n"));
        assert!(con.commands[0].contains("\r\nsession:old\r\n"));
        assert!(con.commands[0].contains("\r\nsession:new\r\n"));
    }

    #[tokio::test]
    async fn rename_key_reports_a_destination_conflict() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(0)]);

        let error = super::rename_key(&mut con, b"session:old", b"session:new").await.unwrap_err();

        assert_eq!(error, "Target key already exists");
    }

    #[tokio::test]
    async fn set_expire_at_uses_expireat_with_the_unix_timestamp() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(1)]);

        super::set_expire_at(&mut con, b"session", 1_735_689_600).await.unwrap();

        assert_eq!(con.commands.len(), 1);
        assert!(con.commands[0].contains("\r\nEXPIREAT\r\n"));
        assert!(con.commands[0].contains("\r\n1735689600\r\n"));
        assert_eq!(con.command_count("EVAL"), 0);
    }

    #[tokio::test]
    async fn set_expire_at_reports_when_the_key_disappears_before_expiration_is_applied() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(0)]);

        let error = super::set_expire_at(&mut con, b"session", 1_735_689_600).await.unwrap_err();

        assert!(error.contains("EXPIREAT was not applied"));
    }

    #[tokio::test]
    async fn set_ttl_reports_when_positive_expiration_is_not_applied() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(0)]);

        let error = super::set_ttl(&mut con, b"session", 60).await.unwrap_err();

        assert!(error.contains("EXPIRE was not applied"));
    }

    #[tokio::test]
    async fn persist_is_idempotent_for_an_already_persistent_key() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(0)]);

        super::set_ttl(&mut con, b"session", 0).await.unwrap();

        assert_eq!(con.commands.len(), 1);
        assert_eq!(con.command_count("PERSIST"), 1);
        assert_eq!(con.command_count("EXISTS"), 0);
        assert_eq!(con.command_count("EVAL"), 0);
    }

    #[tokio::test]
    async fn set_keys_expiry_expires_every_selected_key_in_one_pipeline() {
        let mut con =
            FakeRedisConnection::new(vec![RedisRawValue::Int(1), RedisRawValue::Int(1), RedisRawValue::Int(1)]);
        let keys = vec![b"key:a".to_vec(), b"key:b".to_vec(), b"key:c".to_vec()];

        let result = super::set_keys_expiry(&mut con, &keys, super::RedisKeysExpiry::Ttl(3_600)).await.unwrap();

        assert_eq!(result, super::RedisKeysExpiryResult { applied: 3, missing_key_raws: Vec::new() });
        // One pipeline for the whole selection, with one command per selected key.
        assert_eq!(con.commands.len(), 1);
        assert_eq!(con.commands[0].matches("\r\nEXPIRE\r\n").count(), 3);
        assert_eq!(con.commands[0].matches("\r\nEXPIREAT\r\n").count(), 0);
        assert_eq!(con.commands[0].matches("\r\nPERSIST\r\n").count(), 0);
        assert_eq!(con.commands[0].matches("\r\n3600\r\n").count(), 3);
    }

    #[tokio::test]
    async fn set_keys_expiry_reports_only_the_keys_that_disappeared() {
        let mut con =
            FakeRedisConnection::new(vec![RedisRawValue::Int(1), RedisRawValue::Int(0), RedisRawValue::Int(1)]);
        let keys = vec![b"key:a".to_vec(), b"key:b".to_vec(), b"key:c".to_vec()];

        let result = super::set_keys_expiry(&mut con, &keys, super::RedisKeysExpiry::At(1_735_689_600)).await.unwrap();

        assert_eq!(result.applied, 2);
        assert_eq!(result.missing_key_raws, vec![super::redis_key_bytes_to_raw(b"key:b")]);
        assert_eq!(con.commands[0].matches("\r\nEXPIREAT\r\n").count(), 3);
        assert!(con.commands[0].contains("\r\n1735689600\r\n"));
    }

    #[tokio::test]
    async fn set_keys_expiry_treats_persist_as_idempotent_for_every_key() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(0), RedisRawValue::Int(1)]);
        let keys = vec![b"key:a".to_vec(), b"key:b".to_vec()];

        let result = super::set_keys_expiry(&mut con, &keys, super::RedisKeysExpiry::from_ttl(-1)).await.unwrap();

        assert_eq!(result, super::RedisKeysExpiryResult { applied: 2, missing_key_raws: Vec::new() });
        assert_eq!(con.commands.len(), 1);
        assert_eq!(con.commands[0].matches("\r\nPERSIST\r\n").count(), 2);
        assert_eq!(con.commands[0].matches("\r\nEXPIRE\r\n").count(), 0);
    }

    #[tokio::test]
    async fn set_keys_expiry_keeps_ttl_zero_on_the_persist_path() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(1)]);

        let result =
            super::set_keys_expiry(&mut con, &[b"key:a".to_vec()], super::RedisKeysExpiry::from_ttl(0)).await.unwrap();

        assert_eq!(result.applied, 1);
        assert_eq!(con.command_count("PERSIST"), 1);
    }

    #[tokio::test]
    async fn set_keys_expiry_does_not_send_a_command_for_an_empty_selection() {
        let mut con = FakeRedisConnection::new(Vec::new());

        let result = super::set_keys_expiry(&mut con, &[], super::RedisKeysExpiry::Ttl(60)).await.unwrap();

        assert_eq!(result, super::RedisKeysExpiryResult::default());
        assert!(con.commands.is_empty());
    }

    #[tokio::test]
    async fn set_keys_expiry_fails_loudly_when_a_reply_is_missing() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(1)]);
        let keys = vec![b"key:a".to_vec(), b"key:b".to_vec()];

        let error = super::set_keys_expiry(&mut con, &keys, super::RedisKeysExpiry::Ttl(60)).await.unwrap_err();

        // A short or failed reply must not be reported as two successful keys.
        assert!(error.contains("EXPIRE did not return one reply per selected key"));
    }

    #[tokio::test]
    async fn set_string_falls_back_to_pttl_and_px_when_keepttl_is_unsupported() {
        let unsupported = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "syntax error".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![
            Err(unsupported),
            Ok(RedisRawValue::Int(4_200)),
            Ok(RedisRawValue::Okay),
        ]);

        super::set_string(&mut con, b"session", "updated", None).await.unwrap();

        assert_eq!(con.commands.len(), 3);
        assert!(con.commands[0].contains("\r\nKEEPTTL\r\n"));
        assert!(con.commands[1].contains("\r\nPTTL\r\n"));
        assert!(con.commands[2].contains("\r\nPX\r\n$4\r\n4200\r\n"));
    }

    #[tokio::test]
    async fn set_string_fallback_keeps_persistent_keys_persistent() {
        let unsupported = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "syntax error".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![
            Err(unsupported),
            Ok(RedisRawValue::Int(-1)),
            Ok(RedisRawValue::Okay),
        ]);

        super::set_string(&mut con, b"settings", "updated", None).await.unwrap();

        assert_eq!(con.commands.len(), 3);
        assert!(!con.commands[2].contains("\r\nPX\r\n"));
        assert!(!con.commands[2].contains("\r\nKEEPTTL\r\n"));
    }

    #[tokio::test]
    async fn set_string_does_not_fallback_for_unrelated_errors() {
        let read_only = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ReadOnly),
            "The server is read-only",
            "You can't write against a read only replica".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![Err(read_only)]);

        let error = super::set_string(&mut con, b"session", "updated", None).await.unwrap_err();

        assert!(error.contains("read-only"));
        assert_eq!(con.commands.len(), 1);
    }

    #[test]
    fn parses_scan_response_with_binary_keys() {
        let raw = RedisRawValue::Array(vec![
            RedisRawValue::BulkString(b"17".to_vec()),
            RedisRawValue::Array(vec![
                RedisRawValue::BulkString(vec![0xAC, 0xED, 0x00, 0x05, b't']),
                RedisRawValue::BulkString(b"plain:key".to_vec()),
            ]),
        ]);

        let (cursor, keys) = parse_scan_keys(raw).unwrap();

        assert_eq!(cursor, 17);
        assert_eq!(keys, vec![vec![0xAC, 0xED, 0x00, 0x05, b't'], b"plain:key".to_vec()]);
    }

    #[tokio::test]
    async fn scan_keys_batch_respects_iteration_limit_on_empty_cursor_pages() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Int(3001),
            scan_response("512", vec![]),
            scan_response("0", vec!["user:room:snapshot:200063:1"]),
        ]);

        let result = super::scan_keys_batch(&mut con, 0, "user:room:snapshot:200063:*", 1000, 1, false).await.unwrap();

        assert_eq!(result.cursor, 512);
        assert!(result.keys.is_empty());
        assert_eq!(con.command_count("SCAN"), 1);
    }

    #[tokio::test]
    async fn scan_keys_batch_can_skip_empty_cursor_pages_for_sparse_match() {
        let key = "user:room:snapshot:200063:1";
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Int(3001),
            scan_response("512", vec![]),
            scan_response("0", vec![key]),
        ]);

        let result = super::scan_keys_batch(&mut con, 0, "user:room:snapshot:200063:*", 1000, 2, false).await.unwrap();

        assert_eq!(result.cursor, 0);
        assert_eq!(result.total_keys, 3001);
        assert_eq!(result.keys.len(), 1);
        assert_eq!(result.keys[0].key_display, key);
        assert_eq!(result.keys[0].key_raw, redis_key_bytes_to_raw(key.as_bytes()));
        assert_eq!(con.command_count("SCAN"), 2);
    }

    #[tokio::test]
    async fn scan_keys_batch_batches_type_and_ttl_metadata() {
        // The fake connection answers a packed pipeline in the order the
        // commands were sent, so the replies follow the interleaved order
        // TYPE, TTL, TYPE, TTL.
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Int(2),
            scan_response("0", vec!["session:a", "cache:b"]),
            RedisRawValue::SimpleString("string".to_string()),
            RedisRawValue::Int(-1),
            RedisRawValue::SimpleString("hash".to_string()),
            RedisRawValue::Int(3600),
        ]);

        let result = super::scan_keys_batch(&mut con, 0, "*", 100, 1, true).await.unwrap();

        assert_eq!(result.keys.len(), 2);
        assert_eq!(result.keys[0].key_type, "string");
        assert_eq!(result.keys[0].ttl, -1);
        assert_eq!(result.keys[1].key_type, "hash");
        assert_eq!(result.keys[1].ttl, 3600);

        // One pipeline carries the metadata of the whole batch: two TYPE and
        // two TTL commands, interleaved in that very order.
        let metadata_pipelines: Vec<&String> =
            con.commands.iter().filter(|packed| packed.contains("\r\nTYPE\r\n")).collect();
        assert_eq!(metadata_pipelines.len(), 1);
        let packed = metadata_pipelines[0];
        let type_offsets = command_offsets(packed, "TYPE");
        let ttl_offsets = command_offsets(packed, "TTL");
        assert_eq!(type_offsets.len(), 2);
        assert_eq!(ttl_offsets.len(), 2);
        assert!(type_offsets[0] < ttl_offsets[0]);
        assert!(ttl_offsets[0] < type_offsets[1]);
        assert!(type_offsets[1] < ttl_offsets[1]);
    }

    #[tokio::test]
    async fn scan_keys_batch_splits_the_metadata_pipeline_into_bounded_chunks() {
        let chunk = super::SCAN_METADATA_PIPELINE_CHUNK;
        let key_count = chunk + 1;
        let key_names: Vec<String> = (0..key_count).map(|index| format!("key:{index}")).collect();
        let key_refs: Vec<&str> = key_names.iter().map(|name| name.as_str()).collect();

        let mut responses = vec![RedisRawValue::Int(key_count as i64), scan_response("0", key_refs)];
        // The first chunk answers with interleaved TYPE and TTL replies.
        for _ in 0..chunk {
            responses.push(RedisRawValue::SimpleString("string".to_string()));
            responses.push(RedisRawValue::Int(60));
        }
        // The tail chunk holds the single remaining key.
        responses.push(RedisRawValue::SimpleString("hash".to_string()));
        responses.push(RedisRawValue::Int(30));

        let mut con = FakeRedisConnection::new(responses);
        let result = super::scan_keys_batch(&mut con, 0, "*", 1000, 1, true).await.unwrap();

        assert_eq!(result.keys.len(), key_count);
        // Every key keeps its own metadata even though the pipeline was split.
        assert_eq!(result.keys[0].key_type, "string");
        assert_eq!(result.keys[0].ttl, 60);
        assert_eq!(result.keys[chunk - 1].key_type, "string");
        assert_eq!(result.keys[chunk - 1].ttl, 60);
        assert_eq!(result.keys[chunk].key_type, "hash");
        assert_eq!(result.keys[chunk].ttl, 30);

        // The metadata never travels in one oversized round trip: every packed
        // command carries at most one chunk worth of TYPE and TTL commands.
        let type_pipelines: Vec<&String> =
            con.commands.iter().filter(|packed| packed.contains("\r\nTYPE\r\n")).collect();
        assert_eq!(type_pipelines.len(), 2);
        assert_eq!(command_offsets(type_pipelines[0], "TYPE").len(), chunk);
        assert_eq!(command_offsets(type_pipelines[0], "TTL").len(), chunk);
        assert_eq!(command_offsets(type_pipelines[1], "TYPE").len(), 1);
        assert_eq!(command_offsets(type_pipelines[1], "TTL").len(), 1);
    }

    #[tokio::test]
    async fn scan_keys_batch_preserves_types_when_one_ttl_command_fails() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Int(2),
            scan_response("0", vec!["session:a", "cache:b"]),
            RedisRawValue::SimpleString("string".to_string()),
            redis::parse_redis_value(b"-NOPERM this user has no permissions to run the 'ttl' command\r\n").unwrap(),
            RedisRawValue::SimpleString("hash".to_string()),
            RedisRawValue::Int(3600),
        ]);

        let result = super::scan_keys_batch(&mut con, 0, "*", 100, 1, true).await.unwrap();

        assert_eq!(result.keys.len(), 2);
        assert_eq!(result.keys[0].key_type, "string");
        assert_eq!(result.keys[0].ttl, -2);
        assert_eq!(result.keys[1].key_type, "hash");
        assert_eq!(result.keys[1].ttl, 3600);
    }

    #[tokio::test]
    async fn scan_keys_batch_keeps_the_types_when_the_metadata_pipeline_fails_as_a_whole() {
        // The combined TYPE/TTL pipeline is refused as a whole, for example by
        // an ACL without the TTL permission. The types are asked for on their
        // own, so the chunk does not lose its badges with the expiry.
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(RedisRawValue::Int(2)),
            Ok(scan_response("0", vec!["session:a", "cache:b"])),
            Err(noperm("ttl")),
            Ok(RedisRawValue::SimpleString("string".to_string())),
            Ok(RedisRawValue::SimpleString("hash".to_string())),
        ]);

        let result = super::scan_keys_batch(&mut con, 0, "*", 100, 1, true).await.unwrap();

        assert_eq!(result.keys.len(), 2);
        assert_eq!(result.keys[0].key_type, "string");
        assert_eq!(result.keys[1].key_type, "hash");
        // The expiry stays unknown, so the browser fills it in afterwards.
        assert_eq!(result.keys[0].ttl, -2);
        assert_eq!(result.keys[1].ttl, -2);
    }

    #[tokio::test]
    async fn scan_keys_batch_skips_type_and_ttl_when_metadata_disabled() {
        // include_types=false 是“加载全部”的百万 key 链路,不能多发出任何 TYPE/TTL 命令
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(1), scan_response("0", vec!["cache:b"])]);

        let result = super::scan_keys_batch(&mut con, 0, "*", 100, 1, false).await.unwrap();

        assert_eq!(result.keys.len(), 1);
        assert_eq!(result.keys[0].key_type, "");
        assert_eq!(result.keys[0].ttl, -2);
        assert_eq!(con.command_count("TYPE"), 0);
        assert_eq!(con.command_count("TTL"), 0);
    }

    #[tokio::test]
    async fn key_metadata_batch_reads_type_and_ttl_for_the_given_keys() {
        // The fake connection answers a packed pipeline in the order the
        // commands were sent, so the replies follow the interleaved order
        // TYPE, TTL, TYPE, TTL.
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::SimpleString("string".to_string()),
            RedisRawValue::Int(3600),
            RedisRawValue::SimpleString("hash".to_string()),
            RedisRawValue::Int(-1),
        ]);

        let result = super::key_metadata_batch(&mut con, &[b"session:a".to_vec(), b"cache:b".to_vec()]).await.unwrap();

        assert_eq!(result.len(), 2);
        assert_eq!(result[0].key_raw, super::redis_key_bytes_to_raw(b"session:a"));
        assert_eq!(result[0].key_type, "string");
        assert_eq!(result[0].ttl, 3600);
        assert_eq!(result[1].key_type, "hash");
        assert_eq!(result[1].ttl, -1);
        // The whole batch travels in one pipeline: one TYPE and one TTL per key.
        assert_eq!(con.commands.len(), 1);
        let packed = &con.commands[0];
        let type_offsets = command_offsets(packed, "TYPE");
        let ttl_offsets = command_offsets(packed, "TTL");
        assert_eq!(type_offsets.len(), 2);
        assert_eq!(ttl_offsets.len(), 2);
        assert!(type_offsets[0] < ttl_offsets[0]);
        assert!(ttl_offsets[0] < type_offsets[1]);
        assert!(type_offsets[1] < ttl_offsets[1]);
    }

    #[tokio::test]
    async fn key_metadata_batch_splits_the_metadata_pipeline_into_bounded_chunks() {
        let chunk = super::SCAN_METADATA_PIPELINE_CHUNK;
        let key_count = chunk + 1;
        let keys: Vec<Vec<u8>> = (0..key_count).map(|index| format!("key:{index}").into_bytes()).collect();

        // Every key answers with its own type and its own expiry, so a reply
        // that drifted to another key would be visible in the result.
        let mut responses = Vec::with_capacity(key_count * 2);
        for index in 0..key_count {
            let key_type = if index % 2 == 0 { "string" } else { "hash" };
            responses.push(RedisRawValue::SimpleString(key_type.to_string()));
            responses.push(RedisRawValue::Int(index as i64));
        }

        let mut con = FakeRedisConnection::new(responses);
        let result = super::key_metadata_batch(&mut con, &keys).await.unwrap();

        assert_eq!(result.len(), key_count);
        for (index, metadata) in result.iter().enumerate() {
            let expected_type = if index % 2 == 0 { "string" } else { "hash" };
            assert_eq!(metadata.key_type, expected_type);
            assert_eq!(metadata.ttl, index as i64);
        }

        // The metadata never travels in one oversized round trip: every packed
        // command carries at most one chunk worth of TYPE and TTL commands.
        let type_pipelines: Vec<&String> =
            con.commands.iter().filter(|packed| packed.contains("\r\nTYPE\r\n")).collect();
        assert_eq!(type_pipelines.len(), 2);
        assert_eq!(command_offsets(type_pipelines[0], "TYPE").len(), chunk);
        assert_eq!(command_offsets(type_pipelines[0], "TTL").len(), chunk);
        assert_eq!(command_offsets(type_pipelines[1], "TYPE").len(), 1);
        assert_eq!(command_offsets(type_pipelines[1], "TTL").len(), 1);
    }

    #[tokio::test]
    async fn key_metadata_batch_answers_unknown_type_when_the_reply_cannot_be_parsed() {
        // A TYPE reply that is not a string cannot be read as a type: the key
        // stays listed with the same "unknown" badge the scan path uses.
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Nil, RedisRawValue::Int(60)]);

        let result = super::key_metadata_batch(&mut con, &[b"session:a".to_vec()]).await.unwrap();

        assert_eq!(result.len(), 1);
        assert_eq!(result[0].key_type, "unknown");
        assert_eq!(result[0].ttl, 60);
    }

    #[tokio::test]
    async fn key_metadata_batch_answers_unknown_expiry_for_a_vanished_key() {
        // "none" is a readable answer: the key does not exist any more, which
        // is not the same as an answer that cannot be parsed.
        let mut con =
            FakeRedisConnection::new(vec![RedisRawValue::SimpleString("none".to_string()), RedisRawValue::Int(-2)]);

        let result = super::key_metadata_batch(&mut con, &[b"gone".to_vec()]).await.unwrap();

        assert_eq!(result.len(), 1);
        assert_eq!(result[0].key_type, "none");
        assert_eq!(result[0].ttl, -2);
    }

    #[tokio::test]
    async fn key_metadata_batch_without_keys_issues_no_command() {
        let mut con = FakeRedisConnection::new(vec![]);

        let result = super::key_metadata_batch(&mut con, &[]).await.unwrap();

        assert!(result.is_empty());
        assert!(con.commands.is_empty());
    }

    #[tokio::test]
    async fn scan_keys_batch_exact_match_returns_ttl() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Int(1),
            RedisRawValue::Int(1),
            RedisRawValue::SimpleString("string".to_string()),
            RedisRawValue::Int(-1),
        ]);

        let result = super::scan_keys_batch(&mut con, 0, "session:a", 100, 1, true).await.unwrap();

        assert_eq!(result.keys.len(), 1);
        assert_eq!(result.keys[0].key_display, "session:a");
        assert_eq!(result.keys[0].key_type, "string");
        assert_eq!(result.keys[0].ttl, -1);
        assert_eq!(con.command_count("EXISTS"), 1);
        assert_eq!(con.command_count("TTL"), 1);
    }

    #[tokio::test]
    async fn cluster_key_batch_reuses_node_connections_across_scan_iterations() {
        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
        let masters = vec![
            RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 7001 },
            RedisNodeEndpoint { host: "node-c".to_string(), port: 7002 },
        ];
        let logs: Vec<_> = (0..masters.len()).map(|_| Arc::new(StdMutex::new(Vec::new()))).collect();
        let mut connections = HashMap::from([
            (
                masters[0].clone(),
                TrackedRedisConnection::new(
                    vec![RedisRawValue::Int(100), scan_response("7", vec![]), scan_response("0", vec![])],
                    logs[0].clone(),
                ),
            ),
            (
                masters[1].clone(),
                TrackedRedisConnection::new(vec![RedisRawValue::Int(200), scan_response("9", vec![])], logs[1].clone()),
            ),
            (
                masters[2].clone(),
                TrackedRedisConnection::new(
                    vec![RedisRawValue::Int(300), scan_response("0", vec!["membership:saas:base:token:match"])],
                    logs[2].clone(),
                ),
            ),
        ]);
        let connect_count = Arc::new(AtomicUsize::new(0));
        let connector_count = connect_count.clone();
        let topology_count = Arc::new(AtomicUsize::new(0));
        let discovery_count = topology_count.clone();
        let discovered_masters = masters.clone();

        let result = super::scan_cluster_keys_batch_with(
            &sessions,
            move || {
                discovery_count.fetch_add(1, Ordering::Relaxed);
                ready(Ok(discovered_masters.clone()))
            },
            move |endpoint| {
                connector_count.fetch_add(1, Ordering::Relaxed);
                ready(connections.remove(&endpoint).ok_or_else(|| format!("unexpected reconnect to {}", endpoint.host)))
            },
            0,
            "membership:saas:base:token:*",
            1000,
            4,
            false,
        )
        .await
        .unwrap();

        assert_eq!(result.total_keys, 600);
        assert_eq!(result.keys.len(), 1);
        assert!(result.cursor > 0);
        assert!(result.cursor <= super::MAX_SAFE_INTEGER_CURSOR);
        assert_eq!(topology_count.load(Ordering::Relaxed), 1);
        assert_eq!(connect_count.load(Ordering::Relaxed), 3);
        assert_eq!(logs.iter().map(|log| tracked_command_count(log, "DBSIZE")).sum::<usize>(), 3);
        assert_eq!(logs.iter().map(|log| tracked_command_count(log, "SCAN")).sum::<usize>(), 4);
        assert_eq!(sessions.lock().await.entries.len(), 1);
    }

    #[tokio::test]
    async fn cluster_key_batch_scans_later_masters_before_exhausting_the_first_master() {
        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
        let masters = vec![
            RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 7001 },
            RedisNodeEndpoint { host: "node-c".to_string(), port: 7002 },
        ];
        let logs: Vec<_> = (0..masters.len()).map(|_| Arc::new(StdMutex::new(Vec::new()))).collect();
        let mut connections = HashMap::from([
            (
                masters[0].clone(),
                TrackedRedisConnection::new(
                    vec![RedisRawValue::Int(200_000), scan_response("7", vec!["migration:visible:first"])],
                    logs[0].clone(),
                ),
            ),
            (
                masters[1].clone(),
                TrackedRedisConnection::new(vec![RedisRawValue::Int(0), scan_response("0", vec![])], logs[1].clone()),
            ),
            (
                masters[2].clone(),
                TrackedRedisConnection::new(
                    vec![RedisRawValue::Int(1), scan_response("0", vec!["migration:user:1:status"])],
                    logs[2].clone(),
                ),
            ),
        ]);
        let discovered_masters = masters.clone();

        let result = super::scan_cluster_keys_batch_with(
            &sessions,
            move || ready(Ok(discovered_masters.clone())),
            move |endpoint| {
                ready(connections.remove(&endpoint).ok_or_else(|| format!("unexpected reconnect to {}", endpoint.host)))
            },
            0,
            "*migration*",
            100,
            3,
            false,
        )
        .await
        .unwrap();

        assert_eq!(result.total_keys, 200_001);
        assert_eq!(
            result.keys.iter().map(|key| key.key_display.as_str()).collect::<Vec<_>>(),
            ["migration:visible:first", "migration:user:1:status",]
        );
        assert!(result.cursor > 0);
        assert_eq!(logs.iter().map(|log| tracked_command_count(log, "SCAN")).collect::<Vec<_>>(), [1, 1, 1]);
        let continued = sessions.lock().await.take(result.cursor).unwrap();
        assert_eq!(continued.node_cursors, [7, 0, 0]);
        assert_eq!(continued.node_complete, [false, true, true]);
        assert_eq!(continued.next_node_index, 0);
    }

    #[tokio::test]
    async fn cluster_key_batch_exact_match_reaches_the_owning_master() {
        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
        let masters = vec![
            RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 7001 },
            RedisNodeEndpoint { host: "node-c".to_string(), port: 7002 },
        ];
        let mut connections = HashMap::from([
            (
                masters[0].clone(),
                TrackedRedisConnection::new(
                    vec![RedisRawValue::Int(100), RedisRawValue::Int(0)],
                    Arc::new(StdMutex::new(Vec::new())),
                ),
            ),
            (
                masters[1].clone(),
                TrackedRedisConnection::new(
                    vec![RedisRawValue::Int(200), RedisRawValue::Int(0)],
                    Arc::new(StdMutex::new(Vec::new())),
                ),
            ),
            (
                masters[2].clone(),
                TrackedRedisConnection::new(
                    vec![
                        RedisRawValue::Int(1),
                        RedisRawValue::Int(1),
                        RedisRawValue::SimpleString("string".to_string()),
                        RedisRawValue::Int(-1),
                    ],
                    Arc::new(StdMutex::new(Vec::new())),
                ),
            ),
        ]);
        let discovered_masters = masters.clone();

        let result = super::scan_cluster_keys_batch_with(
            &sessions,
            move || ready(Ok(discovered_masters.clone())),
            move |endpoint| {
                ready(connections.remove(&endpoint).ok_or_else(|| format!("unexpected reconnect to {}", endpoint.host)))
            },
            0,
            "migration:user:1:status",
            100,
            3,
            true,
        )
        .await
        .unwrap();

        assert_eq!(result.cursor, 0);
        assert_eq!(result.total_keys, 301);
        assert_eq!(result.keys.len(), 1);
        assert_eq!(result.keys[0].key_display, "migration:user:1:status");
        assert_eq!(result.keys[0].key_type, "string");
        assert_eq!(result.keys[0].ttl, -1);
        assert!(sessions.lock().await.entries.is_empty());
    }

    #[tokio::test]
    async fn cluster_key_batch_continuation_skips_dbsize_and_advances_masters() {
        let pattern = "membership:saas:base:token:*";
        let masters = vec![
            RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 7001 },
            RedisNodeEndpoint { host: "node-c".to_string(), port: 7002 },
        ];
        let mut saved_session = super::RedisClusterKeyScanSession::new(masters.clone(), pattern);
        saved_session.node_complete[0] = true;
        saved_session.node_cursors[1] = 7;
        saved_session.next_node_index = 1;
        let mut saved_sessions = super::RedisClusterScanSessions::default();
        let cursor = saved_sessions.insert(None, saved_session);
        let sessions = tokio::sync::Mutex::new(saved_sessions);
        let logs: Vec<_> = (0..masters.len()).map(|_| Arc::new(StdMutex::new(Vec::new()))).collect();
        let mut connections = HashMap::from([
            (masters[1].clone(), TrackedRedisConnection::new(vec![scan_response("0", vec![])], logs[1].clone())),
            (
                masters[2].clone(),
                TrackedRedisConnection::new(
                    vec![scan_response("0", vec!["membership:saas:base:token:last"])],
                    logs[2].clone(),
                ),
            ),
        ]);
        let connect_count = Arc::new(AtomicUsize::new(0));
        let connector_count = connect_count.clone();
        let topology_count = Arc::new(AtomicUsize::new(0));
        let discovery_count = topology_count.clone();

        let result = super::scan_cluster_keys_batch_with(
            &sessions,
            move || {
                discovery_count.fetch_add(1, Ordering::Relaxed);
                ready(Err("continuation must not rediscover topology".to_string()))
            },
            move |endpoint| {
                connector_count.fetch_add(1, Ordering::Relaxed);
                ready(
                    connections.remove(&endpoint).ok_or_else(|| format!("unexpected connection to {}", endpoint.host)),
                )
            },
            cursor,
            pattern,
            1000,
            2,
            false,
        )
        .await
        .unwrap();

        assert_eq!(result.cursor, 0);
        assert_eq!(result.total_keys, 0);
        assert_eq!(result.keys.len(), 1);
        assert_eq!(topology_count.load(Ordering::Relaxed), 0);
        assert_eq!(connect_count.load(Ordering::Relaxed), 2);
        assert_eq!(logs.iter().map(|log| tracked_command_count(log, "DBSIZE")).sum::<usize>(), 0);
        assert_eq!(logs.iter().map(|log| tracked_command_count(log, "SCAN")).sum::<usize>(), 2);
        assert!(sessions.lock().await.entries.is_empty());
    }

    #[tokio::test]
    async fn cluster_key_batch_refreshes_healthy_cached_masters_before_scanning() {
        let pattern = "membership:saas:base:token:*";
        let cached_masters = [
            RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 7001 },
        ];
        let current_masters = [
            cached_masters[0].clone(),
            cached_masters[1].clone(),
            RedisNodeEndpoint { host: "node-c".to_string(), port: 7002 },
        ];
        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
        let logs: Vec<_> = (0..current_masters.len()).map(|_| Arc::new(StdMutex::new(Vec::new()))).collect();
        let mut connections = HashMap::from([
            (
                current_masters[0].clone(),
                TrackedRedisConnection::new(vec![RedisRawValue::Int(100), scan_response("0", vec![])], logs[0].clone()),
            ),
            (
                current_masters[1].clone(),
                TrackedRedisConnection::new(vec![RedisRawValue::Int(200), scan_response("0", vec![])], logs[1].clone()),
            ),
            (
                current_masters[2].clone(),
                TrackedRedisConnection::new(
                    vec![RedisRawValue::Int(300), scan_response("0", vec!["membership:saas:base:token:new-master"])],
                    logs[2].clone(),
                ),
            ),
        ]);
        let discovered_masters = vec![
            current_masters[2].clone(),
            current_masters[0].clone(),
            current_masters[1].clone(),
            current_masters[2].clone(),
        ];
        let topology_count = Arc::new(AtomicUsize::new(0));
        let discovery_count = topology_count.clone();

        let result = super::scan_cluster_keys_batch_with(
            &sessions,
            move || {
                discovery_count.fetch_add(1, Ordering::Relaxed);
                ready(Ok(discovered_masters.clone()))
            },
            move |endpoint| {
                ready(connections.remove(&endpoint).ok_or_else(|| format!("unexpected reconnect to {}", endpoint.host)))
            },
            0,
            pattern,
            1000,
            3,
            false,
        )
        .await
        .unwrap();

        assert_eq!(result.cursor, 0);
        assert_eq!(result.total_keys, 600);
        assert_eq!(result.keys.len(), 1);
        assert_eq!(result.keys[0].key_display, "membership:saas:base:token:new-master");
        assert_eq!(topology_count.load(Ordering::Relaxed), 1);
        assert_eq!(logs.iter().map(|log| tracked_command_count(log, "DBSIZE")).sum::<usize>(), 3);
        assert_eq!(logs.iter().map(|log| tracked_command_count(log, "SCAN")).sum::<usize>(), 3);
        assert!(sessions.lock().await.entries.is_empty());
    }

    #[test]
    fn cluster_scan_routes_discovered_advertised_endpoint_through_existing_mapping() {
        let advertised = RedisNodeEndpoint { host: "redis.internal".to_string(), port: 7000 };
        let forwarded = RedisNodeEndpoint { host: "127.0.0.1".to_string(), port: 17_000 };
        let pool = super::RedisClusterPool {
            connection: None,
            database_connections: Box::new(tokio::sync::Mutex::new(HashMap::new())),
            database_capability: Box::new(tokio::sync::Mutex::new(None)),
            seed_nodes: vec![advertised.clone()],
            seed_routes: Vec::new(),
            slot_ranges: Vec::new(),
            node_routes: vec![RedisNodeRoute { advertised: advertised.clone(), connect: forwarded.clone() }],
            tls: false,
            tls_insecure: false,
            tls_certificates: None,
            username: String::new(),
            password: String::new(),
            scan_sessions: Box::new(tokio::sync::Mutex::new(super::RedisClusterScanSessions::default())),
        };

        assert_eq!(super::mapped_cluster_endpoint(&pool, &advertised), forwarded);
    }

    #[tokio::test]
    async fn cluster_key_batch_continuation_uses_stable_node_identity_without_rediscovery() {
        let pattern = "membership:*";
        let masters = vec![
            RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 7001 },
            RedisNodeEndpoint { host: "node-c".to_string(), port: 7002 },
        ];
        let mut saved_session = super::RedisClusterKeyScanSession::new(masters.clone(), pattern);
        saved_session.node_complete[0] = true;
        saved_session.node_cursors[1] = 7;
        saved_session.next_node_index = 1;
        let mut saved_sessions = super::RedisClusterScanSessions::default();
        let cursor = saved_sessions.insert(None, saved_session);
        let sessions = tokio::sync::Mutex::new(saved_sessions);
        let commands = Arc::new(StdMutex::new(Vec::new()));
        let mut connections = HashMap::from([(
            masters[1].clone(),
            TrackedRedisConnection::new(vec![scan_response("9", vec!["membership:stable-node"])], commands.clone()),
        )]);

        let result = super::scan_cluster_keys_batch_with(
            &sessions,
            || ready(Err("continuation must not rediscover topology".to_string())),
            move |endpoint| {
                ready(
                    connections.remove(&endpoint).ok_or_else(|| format!("unexpected connection to {}", endpoint.host)),
                )
            },
            cursor,
            pattern,
            1,
            1,
            false,
        )
        .await
        .unwrap();

        assert_eq!(result.cursor, cursor);
        assert_eq!(result.total_keys, 0);
        assert_eq!(result.keys[0].key_display, "membership:stable-node");
        assert_eq!(tracked_command_count(&commands, "DBSIZE"), 0);
        assert_eq!(tracked_command_count(&commands, "SCAN"), 1);
        let continued = sessions.lock().await.take(cursor).unwrap();
        assert_eq!(continued.node_cursors[1], 9);
        assert_eq!(continued.next_node_index, 2);
    }

    #[tokio::test]
    async fn cluster_key_batch_continuation_restores_original_position_after_failure() {
        let pattern = "membership:*";
        let masters = vec![
            RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 },
            RedisNodeEndpoint { host: "node-b".to_string(), port: 7001 },
            RedisNodeEndpoint { host: "node-c".to_string(), port: 7002 },
        ];
        let mut saved_session = super::RedisClusterKeyScanSession::new(masters.clone(), pattern);
        saved_session.node_complete[0] = true;
        saved_session.node_cursors[1] = 7;
        saved_session.next_node_index = 1;
        let mut saved_sessions = super::RedisClusterScanSessions::default();
        let cursor = saved_sessions.insert(None, saved_session);
        let sessions = tokio::sync::Mutex::new(saved_sessions);
        let commands = Arc::new(StdMutex::new(Vec::new()));
        let connected_nodes = Arc::new(StdMutex::new(Vec::new()));
        let first_connected_nodes = connected_nodes.clone();
        let first_commands = commands.clone();
        let first_master = masters[1].clone();
        let failed_master = masters[2].clone();
        let mut first_connection = Some(TrackedRedisConnection::new(
            vec![scan_response("0", vec!["membership:before-failure"])],
            first_commands,
        ));

        let error = super::scan_cluster_keys_batch_with(
            &sessions,
            || ready(Err("continuation must not rediscover topology".to_string())),
            move |endpoint| {
                first_connected_nodes.lock().unwrap().push(endpoint.clone());
                ready(if endpoint == first_master {
                    first_connection.take().ok_or_else(|| "unexpected reconnect".to_string())
                } else if endpoint == failed_master {
                    Err("temporary node failure".to_string())
                } else {
                    Err(format!("unexpected connection to {}", endpoint.host))
                })
            },
            cursor,
            pattern,
            1000,
            2,
            false,
        )
        .await
        .unwrap_err();

        assert_eq!(error, "temporary node failure");
        let restored = sessions.lock().await.entries.get(&cursor).unwrap().clone();
        assert_eq!(restored.node_cursors[1], 7);
        assert_eq!(restored.next_node_index, 1);

        let retry_connected_nodes = connected_nodes.clone();
        let retry_commands = commands.clone();
        let retry_master = masters[1].clone();
        let mut retry_connection =
            Some(TrackedRedisConnection::new(vec![scan_response("9", vec!["membership:retried"])], retry_commands));
        let result = super::scan_cluster_keys_batch_with(
            &sessions,
            || ready(Err("continuation must not rediscover topology".to_string())),
            move |endpoint| {
                retry_connected_nodes.lock().unwrap().push(endpoint.clone());
                ready(if endpoint == retry_master {
                    retry_connection.take().ok_or_else(|| "unexpected reconnect".to_string())
                } else {
                    Err(format!("unexpected connection to {}", endpoint.host))
                })
            },
            cursor,
            pattern,
            1,
            1,
            false,
        )
        .await
        .unwrap();

        assert_eq!(result.cursor, cursor);
        assert_eq!(result.total_keys, 0);
        assert_eq!(result.keys[0].key_display, "membership:retried");
        assert_eq!(tracked_command_count(&commands, "DBSIZE"), 0);
        assert_eq!(tracked_command_count(&commands, "SCAN"), 2);
        assert!(commands.lock().unwrap()[1].contains("\r\n7\r\n"));
        assert_eq!(*connected_nodes.lock().unwrap(), vec![masters[1].clone(), masters[2].clone(), masters[1].clone()]);
        let continued = sessions.lock().await.take(cursor).unwrap();
        assert_eq!(continued.node_cursors[1], 9);
        assert_eq!(continued.next_node_index, 2);
    }

    #[tokio::test]
    async fn cluster_key_batch_rejects_an_unknown_continuation_cursor() {
        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());
        let topology_count = Arc::new(AtomicUsize::new(0));
        let discovery_count = topology_count.clone();
        let connect_count = Arc::new(AtomicUsize::new(0));
        let connector_count = connect_count.clone();

        let error = super::scan_cluster_keys_batch_with::<TrackedRedisConnection, _, _, _, _>(
            &sessions,
            move || {
                discovery_count.fetch_add(1, Ordering::Relaxed);
                ready(Err("continuation must not rediscover topology".to_string()))
            },
            move |_| {
                connector_count.fetch_add(1, Ordering::Relaxed);
                ready(Err("continuation must not connect".to_string()))
            },
            999,
            "membership:*",
            1000,
            1,
            false,
        )
        .await
        .unwrap_err();

        assert_eq!(error, super::INVALID_CLUSTER_SCAN_CURSOR_ERROR);
        assert_eq!(topology_count.load(Ordering::Relaxed), 0);
        assert_eq!(connect_count.load(Ordering::Relaxed), 0);
    }

    #[tokio::test]
    async fn cluster_key_batch_rejects_an_expired_continuation_cursor() {
        let master = RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 };
        let mut saved_sessions = super::RedisClusterScanSessions::default();
        let cursor = saved_sessions.insert(None, super::RedisClusterKeyScanSession::new(vec![master], "membership:*"));
        saved_sessions.entries.get_mut(&cursor).unwrap().last_used =
            std::time::Instant::now() - super::CLUSTER_SCAN_SESSION_TTL - std::time::Duration::from_secs(1);
        let sessions = tokio::sync::Mutex::new(saved_sessions);

        let error = super::scan_cluster_keys_batch_with::<TrackedRedisConnection, _, _, _, _>(
            &sessions,
            || ready(Err("continuation must not rediscover topology".to_string())),
            |_| ready(Err("continuation must not connect".to_string())),
            cursor,
            "membership:*",
            1000,
            1,
            false,
        )
        .await
        .unwrap_err();

        assert_eq!(error, super::INVALID_CLUSTER_SCAN_CURSOR_ERROR);
        assert!(sessions.lock().await.entries.is_empty());
    }

    #[tokio::test]
    async fn cluster_key_batch_reports_new_scan_topology_failure() {
        let sessions = tokio::sync::Mutex::new(super::RedisClusterScanSessions::default());

        let error = super::scan_cluster_keys_batch_with::<TrackedRedisConnection, _, _, _, _>(
            &sessions,
            || ready(Err("topology unavailable".to_string())),
            |_| ready(Err("scan connection must not be opened".to_string())),
            0,
            "membership:*",
            1000,
            1,
            false,
        )
        .await
        .unwrap_err();

        assert_eq!(error, "topology unavailable");
        assert!(sessions.lock().await.entries.is_empty());
    }

    #[test]
    fn cluster_scan_sessions_expire_and_remain_bounded() {
        let master = RedisNodeEndpoint { host: "node-a".to_string(), port: 7000 };
        let mut sessions = super::RedisClusterScanSessions::default();
        let expired_cursor = sessions.insert(None, super::RedisClusterKeyScanSession::new(vec![master.clone()], "*"));
        sessions.entries.get_mut(&expired_cursor).unwrap().last_used =
            std::time::Instant::now() - super::CLUSTER_SCAN_SESSION_TTL - std::time::Duration::from_secs(1);

        for index in 0..=super::CLUSTER_SCAN_SESSION_LIMIT {
            sessions
                .insert(None, super::RedisClusterKeyScanSession::new(vec![master.clone()], &format!("key:{index}:*")));
        }

        assert!(!sessions.entries.contains_key(&expired_cursor));
        assert_eq!(sessions.entries.len(), super::CLUSTER_SCAN_SESSION_LIMIT);
        assert!(sessions.entries.keys().all(|cursor| *cursor > 0 && *cursor <= super::MAX_SAFE_INTEGER_CURSOR));
    }

    // Keep the pre-optimization path as an independent semantic/benchmark oracle.
    fn hash_scan_before_filter(raw: RedisRawValue, query: Option<&str>) -> Result<(u64, Vec<RedisHashItem>), String> {
        let RedisRawValue::Array(parts) = raw else { return Err("Invalid SCAN response".to_string()) };
        if parts.len() != 2 {
            return Err("Invalid SCAN response".to_string());
        }
        let cursor = super::redis_value_to_string(parts[0].clone())
            .ok_or("Invalid cursor")?
            .parse::<u64>()
            .map_err(|_| "Invalid cursor".to_string())?;
        let RedisRawValue::Array(entries) = &parts[1] else { return Err("Invalid SCAN entries".to_string()) };
        let mut items = Vec::new();
        let mut iter = entries.iter();
        while let Some(field) = iter.next() {
            let Some(value) = iter.next() else { break };
            let field = redis_value_to_bytes(field.clone())
                .map(|bytes| redis_blob_from_bytes(&bytes))
                .ok_or_else(|| "Invalid hash field payload".to_string())?;
            let value = redis_value_to_bytes(value.clone())
                .map(|bytes| redis_blob_from_bytes(&bytes))
                .ok_or_else(|| "Invalid hash value payload".to_string())?;
            items.push(RedisHashItem { field, value, field_ttl: None });
        }
        if let Some(query) = query {
            items.retain(|item| {
                super::blob_matches_query(&item.field, query) || super::blob_matches_query(&item.value, query)
            });
        }
        Ok((cursor, items))
    }

    #[test]
    fn hash_raw_filter_preserves_unicode_binary_and_value_matching() {
        let mut pairs = vec![
            (b"Exact".to_vec(), b"".to_vec()),
            (b"other".to_vec(), b"contains eXaCt".to_vec()),
            ("用户:İΣ".as_bytes().to_vec(), "Straße Σσς".as_bytes().to_vec()),
            (b"slash\\field".to_vec(), b"utf8\\value".to_vec()),
            (b"binary\\\xff".to_vec(), b"\0\x80".to_vec()),
        ];
        pairs.extend((0..=255).map(|byte| (vec![b'f', byte], vec![byte, b'V'])));
        let entries = pairs
            .into_iter()
            .flat_map(|(field, value)| [RedisRawValue::BulkString(field), RedisRawValue::BulkString(value)])
            .collect();
        let raw = RedisRawValue::Array(vec![bulk("512"), RedisRawValue::Array(entries)]);
        for query in [
            None,
            Some(""),
            Some("exact"),
            Some("用户"),
            Some("i\u{307}"),
            Some("σ"),
            Some("ς"),
            Some("straße"),
            Some("\\"),
            Some("\\\\"),
            Some("\\xff"),
            Some("\\x00"),
            Some("v"),
            Some("absent"),
        ] {
            assert_eq!(
                super::parse_scan_hash_entries(raw.clone(), query),
                hash_scan_before_filter(raw.clone(), query),
                "query {query:?}"
            );
        }
    }

    #[test]
    fn hash_raw_filter_preserves_payload_validation() {
        for raw in [
            RedisRawValue::Nil,
            RedisRawValue::Array(vec![]),
            RedisRawValue::Array(vec![bulk("bad-cursor"), RedisRawValue::Array(vec![])]),
            RedisRawValue::Array(vec![bulk("0"), RedisRawValue::Nil]),
            RedisRawValue::Array(vec![bulk("0"), RedisRawValue::Array(vec![RedisRawValue::Nil, bulk("value")])]),
            RedisRawValue::Array(vec![bulk("0"), RedisRawValue::Array(vec![bulk("unmatched"), RedisRawValue::Nil])]),
            RedisRawValue::Array(vec![
                RedisRawValue::Int(17),
                RedisRawValue::Array(vec![RedisRawValue::Int(42), RedisRawValue::Boolean(true), bulk("unpaired")]),
            ]),
        ] {
            for query in [None, Some("absent"), Some("42")] {
                assert_eq!(
                    super::parse_scan_hash_entries(raw.clone(), query),
                    hash_scan_before_filter(raw.clone(), query)
                );
            }
        }
    }

    #[test]
    #[ignore = "manual CPU benchmark; run with --ignored --nocapture using an optimized test profile"]
    fn hash_raw_filter_benchmark() {
        use std::{hint::black_box, time::Instant};
        let payload = "payload:".to_string() + &"x".repeat(1016);
        let raw = hscan_response_owned(
            "0",
            (0..25_000)
                .map(|index| {
                    (if index < 4 { format!("needle:{index}") } else { format!("field:{index}") }, payload.clone())
                })
                .collect(),
        );
        for query in ["absent", "needle", "payload"] {
            let mut before = Vec::new();
            let mut after = Vec::new();
            for _ in 0..7 {
                let input = raw.clone();
                let start = Instant::now();
                let expected = black_box(hash_scan_before_filter(black_box(input), Some(query)).unwrap());
                before.push(start.elapsed().as_secs_f64() * 1000.0);
                let input = raw.clone();
                let start = Instant::now();
                let actual = black_box(super::parse_scan_hash_entries(black_box(input), Some(query)).unwrap());
                after.push(start.elapsed().as_secs_f64() * 1000.0);
                assert_eq!(actual, expected);
            }
            before.sort_by(f64::total_cmp);
            after.sort_by(f64::total_cmp);
            eprintln!("Hash CPU query={query} fields=25000 value_bytes=1024 median_before_ms={:.3} median_after_ms={:.3} speedup={:.2}", before[3], after[3], before[3] / after[3]);
        }
    }

    #[tokio::test]
    async fn hash_search_prioritizes_exact_fields_and_keeps_fuzzy_continuation() {
        let mut con = FakeRedisConnection::new(vec![
            bulk("old"),
            hscan_response("512", vec![("Exact", "new"), ("exact", "case variant"), ("other", "contains Exact")]),
            httl_response(3, -1),
            hscan_response("0", vec![("prefix:Exact", "tail")]),
            httl_response(1, -1),
        ]);
        let page = super::load_more_collection(&mut con, b"hash", "hash", 0, 200, Some("Exact"), None).await.unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = page else { panic!("expected hash") };
        assert_eq!(scan_cursor, Some(512));
        assert_eq!(items.len(), 3);
        assert_eq!(items[0].field, text_blob("Exact"));
        assert_eq!(items[0].value, text_blob("new"));
        assert_eq!(con.command_count("HGET"), 1);
        assert_eq!(con.command_count("HSCAN"), 1);
        assert!(con.commands[0].contains("\r\nExact\r\n"));
        let page = super::load_more_collection(&mut con, b"hash", "hash", 512, 200, Some("Exact"), None).await.unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = page else { panic!("expected hash") };
        assert_eq!(scan_cursor, None);
        assert_eq!(items[0].field, text_blob("prefix:Exact"));
        assert_eq!(con.command_count("HGET"), 1);
    }

    #[tokio::test]
    async fn hash_search_distinguishes_empty_exact_values_from_missing_fields() {
        let mut con = FakeRedisConnection::new(vec![bulk(""), hscan_response("100", vec![])]);
        let (cursor, items) = super::hscan_filtered_page_raw(&mut con, b"hash", 0, 200, "field").await.unwrap();
        assert_eq!(cursor, 100);
        assert_eq!(items.len(), 1);
        assert_eq!(items[0].value, text_blob(""));
        assert_eq!(con.command_count("HSCAN"), 1);
    }

    #[tokio::test]
    async fn hash_search_exact_seed_keeps_overflow_pages_and_refreshes_ttls() {
        let mut con = FakeRedisConnection::new(vec![
            bulk("old"),
            hscan_response("0", vec![("wanted", "new"), ("wanted:2", "two"), ("wanted:3", "three")]),
            httl_response(1, 100),
            httl_response(1, 90),
            httl_response(1, 80),
        ]);
        let first = super::load_more_collection(&mut con, b"exact-overflow-hash", "hash", 0, 1, Some("wanted"), None)
            .await
            .unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = first else { panic!("expected Hash") };
        let cursor = scan_cursor.unwrap();
        assert!(cursor >= super::COLLECTION_OVERFLOW_CURSOR_START);
        assert_eq!(items[0].value, text_blob("new"));
        assert_eq!(items[0].field_ttl, Some(100));
        let second =
            super::load_more_collection(&mut con, b"exact-overflow-hash", "hash", cursor, 1, Some("wanted"), None)
                .await
                .unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = second else { panic!("expected Hash") };
        assert_eq!(scan_cursor, Some(cursor));
        assert_eq!(items[0].field, text_blob("wanted:2"));
        assert_eq!(items[0].field_ttl, Some(90));
        let third =
            super::load_more_collection(&mut con, b"exact-overflow-hash", "hash", cursor, 1, Some("wanted"), None)
                .await
                .unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = third else { panic!("expected Hash") };
        assert_eq!(scan_cursor, None);
        assert_eq!(items[0].field, text_blob("wanted:3"));
        assert_eq!(items[0].field_ttl, Some(80));
        assert_eq!(con.command_count("HGET"), 1);
        assert_eq!(con.command_count("HSCAN"), 1);
    }

    #[tokio::test]
    async fn hash_search_optional_lookup_errors_fall_back_without_hiding_real_failures() {
        for error in [
            noperm("hget"),
            redis::RedisError::from((
                redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
                "ERR",
                "unknown command 'HGET'".to_string(),
            )),
        ] {
            let mut con =
                FakeRedisConnection::with_results(vec![Err(error), Ok(hscan_response("0", vec![("field", "wanted")]))]);
            let (_, items) = super::hscan_filtered_page_raw(&mut con, b"hash", 0, 200, "wanted").await.unwrap();
            assert_eq!(items.len(), 1);
        }
        for error in [
            redis::RedisError::from((redis::ErrorKind::Io, "disconnected")),
            redis::RedisError::from((redis::ErrorKind::AuthenticationFailed, "WRONGPASS")),
            redis::RedisError::from((redis::ErrorKind::UnexpectedReturnType, "WRONGTYPE")),
        ] {
            let mut con = FakeRedisConnection::with_results(vec![Err(error)]);
            assert!(super::hscan_filtered_page_raw(&mut con, b"hash", 0, 200, "wanted").await.is_err());
            assert_eq!(con.command_count("HSCAN"), 0);
        }
    }

    #[tokio::test]
    async fn hash_search_exact_lookup_keeps_binary_keys_and_unicode_queries() {
        let mut con = FakeRedisConnection::new(vec![bulk("value"), hscan_response("0", vec![])]);
        let (cursor, items) = super::hscan_filtered_page_raw(&mut con, b"hash\xff", 0, 200, "用户").await.unwrap();
        assert_eq!(cursor, 0);
        assert_eq!(items[0].field, text_blob("用户"));
    }

    // Exercise the production page/TTL/overflow path against a disposable server.
    async fn verify_large_hash_search_live<C>(con: &mut C) -> Result<(), String>
    where
        C: ConnectionLike + Send + Sync + Unpin,
    {
        let nonce = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();
        let key = format!("dbx-11491-{}-{nonce}", std::process::id());
        let query = "EC00100051EB02DD";
        let expected = [query.to_string(), query.to_lowercase(), format!("prefix:{query}"), "value-only".to_string()];
        let result = async {
            for start in (0..25_000).step_by(500) {
                let mut command = redis::cmd("HSET");
                command.arg(&key);
                for index in start..start + 500 {
                    command.arg(format!("filler:{index:05}")).arg("unrelated payload");
                }
                command.query_async::<u64>(con).await.map_err(|error| error.to_string())?;
                // Ensure even interrupted manual runs leave no persistent test data.
                redis::cmd("EXPIRE")
                    .arg(&key)
                    .arg(600)
                    .query_async::<bool>(con)
                    .await
                    .map_err(|error| error.to_string())?;
            }
            let mut command = redis::cmd("HSET");
            command.arg(&key);
            for field in &expected {
                command.arg(field).arg(if field == "value-only" { "contains Ec00100051eb02dd" } else { "" });
            }
            command.query_async::<u64>(con).await.map_err(|error| error.to_string())?;
            for search in [query, "ec00100051eb02dd", "00100051", "absent-11491"] {
                let mut cursor = 0;
                let mut found = HashMap::new();
                let mut requests = 0;
                loop {
                    let page =
                        super::load_more_collection(con, key.as_bytes(), "hash", cursor, 200, Some(search), None)
                            .await?;
                    let RedisCollectionPage::Hash { items, scan_cursor } = page else {
                        return Err("expected Hash page".to_string());
                    };
                    requests += 1;
                    if search == query && requests == 1 {
                        if items.first().map(|item| &item.field) != Some(&text_blob(query)) || scan_cursor.is_none() {
                            return Err("exact field was not prioritized with a continuation".to_string());
                        }
                        if items[0].value != text_blob("") {
                            return Err("empty value was lost".to_string());
                        }
                    }
                    for item in items {
                        found.insert(item.field.raw_base64.clone(), item);
                    }
                    let Some(next) = scan_cursor else { break };
                    cursor = next;
                    if requests > 200 {
                        return Err("scan did not finish".to_string());
                    }
                }
                let wanted: std::collections::HashSet<_> = if search == "absent-11491" {
                    Default::default()
                } else {
                    expected.iter().map(|field| text_blob(field).raw_base64).collect()
                };
                if found.keys().cloned().collect::<std::collections::HashSet<_>>() != wanted {
                    return Err(format!("incomplete search for {search}: {} matches", found.len()));
                }
                eprintln!("large Hash search {search}: {requests} pages, {} unique matches", found.len());
            }
            Ok(())
        }
        .await;
        let cleanup = redis::cmd("DEL").arg(&key).query_async::<u64>(con).await.map_err(|error| error.to_string());
        result.and(cleanup.map(|_| ()))
    }

    #[tokio::test]
    #[ignore = "requires disposable Redis via DBX_TEST_REDIS_URL"]
    async fn hash_search_large_hash_live() {
        let url = std::env::var("DBX_TEST_REDIS_URL").expect("DBX_TEST_REDIS_URL");
        let mut con = super::connect(&url, std::time::Duration::from_secs(5)).await.unwrap();
        verify_large_hash_search_live(&mut con).await.unwrap();
    }

    #[tokio::test]
    #[ignore = "requires disposable Cluster via DBX_TEST_REDIS_CLUSTER_PORT"]
    async fn hash_search_large_hash_cluster_live() {
        let mut config = redis_test_connection_config();
        config.host = "127.0.0.1".to_string();
        config.port =
            std::env::var("DBX_TEST_REDIS_CLUSTER_PORT").expect("DBX_TEST_REDIS_CLUSTER_PORT").parse().unwrap();
        let pool = super::connect_cluster(&config).await.unwrap();
        let mut con = super::cluster_key_connection(&pool, b"dbx-11491").await.unwrap();
        verify_large_hash_search_live(&mut con).await.unwrap();
    }

    #[tokio::test]
    async fn filtered_hash_load_more_matches_fields_and_keeps_scan_cursor() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Nil,
            hscan_response("512", vec![("user:1", "Ada")]),
            hscan_response("0", vec![("user:2", "Bob")]),
        ]);

        let result =
            super::load_more_collection(&mut con, b"hash-key", "hash", 0, 1, Some("user"), None).await.unwrap();

        let RedisCollectionPage::Hash { items, scan_cursor } = result else {
            panic!("expected hash collection page");
        };
        assert_eq!(scan_cursor, Some(512));
        assert_eq!(items, vec![RedisHashItem { field: text_blob("user:1"), value: text_blob("Ada"), field_ttl: None }]);
        assert_eq!(con.command_count("HSCAN"), 1);
        assert!(!con.commands.iter().any(|command| command.contains("\r\nMATCH\r\n")));
    }

    #[tokio::test]
    async fn filtered_hash_load_more_matches_values() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Nil,
            hscan_response("0", vec![("status", "Ada Lovelace"), ("name", "Bob")]),
        ]);

        let result =
            super::load_more_collection(&mut con, b"hash-key", "hash", 0, 20, Some("lovelace"), None).await.unwrap();

        let RedisCollectionPage::Hash { items, scan_cursor } = result else {
            panic!("expected hash collection page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(
            items,
            vec![RedisHashItem { field: text_blob("status"), value: text_blob("Ada Lovelace"), field_ttl: None }]
        );
        assert_eq!(con.command_count("HSCAN"), 1);
        assert!(!con.commands.iter().any(|command| command.contains("\r\nMATCH\r\n")));
    }

    #[tokio::test]
    async fn filtered_set_load_more_matches_members() {
        let mut con = FakeRedisConnection::new(vec![scan_response("0", vec!["Ada Lovelace", "Bob"])]);

        let result =
            super::load_more_collection(&mut con, b"set-key", "set", 0, 20, Some("lovelace"), None).await.unwrap();

        let RedisCollectionPage::Set { items, scan_cursor } = result else {
            panic!("expected set collection page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(items, vec![RedisSetItem { member: text_blob("Ada Lovelace") }]);
        assert_eq!(con.command_count("SSCAN"), 1);
        // Substring search cannot be expressed as an SSCAN glob, so no MATCH is sent.
        assert!(!con.commands.iter().any(|command| command.contains("\r\nMATCH\r\n")));
    }

    #[tokio::test]
    async fn filtered_set_load_more_keeps_scanning_until_the_page_fills() {
        let mut con =
            FakeRedisConnection::new(vec![scan_response("512", vec!["Bob"]), scan_response("0", vec!["Ada Lovelace"])]);

        let result =
            super::load_more_collection(&mut con, b"set-key", "set", 0, 20, Some("lovelace"), None).await.unwrap();

        let RedisCollectionPage::Set { items, scan_cursor } = result else {
            panic!("expected set collection page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(items, vec![RedisSetItem { member: text_blob("Ada Lovelace") }]);
        assert_eq!(con.command_count("SSCAN"), 2);
    }

    #[tokio::test]
    async fn filtered_set_load_more_caps_sparse_scan_iterations() {
        let responses = (1..=super::COLLECTION_FILTER_SCAN_MAX_ITERATIONS + 1)
            .map(|cursor| scan_response(&cursor.to_string(), vec![]))
            .collect();
        let mut con = FakeRedisConnection::new(responses);

        let result =
            super::load_more_collection(&mut con, b"set-key", "set", 0, 20, Some("missing"), None).await.unwrap();

        let RedisCollectionPage::Set { items, scan_cursor } = result else {
            panic!("expected set collection page");
        };
        assert_eq!(scan_cursor, Some(super::COLLECTION_FILTER_SCAN_MAX_ITERATIONS as u64));
        assert!(items.is_empty());
        assert_eq!(con.command_count("SSCAN"), super::COLLECTION_FILTER_SCAN_MAX_ITERATIONS);
    }

    #[tokio::test]
    async fn filtered_zset_load_more_matches_members_and_keeps_score_order() {
        let mut con = FakeRedisConnection::new(vec![zrange_response(vec![
            ("rank:alice", "1"),
            ("bob", "2"),
            ("rank:carol", "3"),
        ])]);

        let result =
            super::load_more_collection(&mut con, b"scores", "zset", 0, 20, Some("RANK:"), Some("asc")).await.unwrap();

        let RedisCollectionPage::Zset { items, scan_cursor } = result else {
            panic!("expected zset collection page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(
            items,
            vec![
                RedisZsetItem { score: "1".to_string(), member: text_blob("rank:alice") },
                RedisZsetItem { score: "3".to_string(), member: text_blob("rank:carol") },
            ]
        );
        // Ranked paging is kept so the score sort and the index cursor survive filtering.
        assert_eq!(con.command_count("ZRANGE"), 1);
        assert_eq!(con.command_count("ZSCAN"), 0);
    }

    #[tokio::test]
    async fn filtered_zset_load_more_honors_descending_pages() {
        let mut con = FakeRedisConnection::new(vec![zrange_response(vec![
            ("rank:carol", "3"),
            ("bob", "2"),
            ("rank:alice", "1"),
        ])]);

        let result =
            super::load_more_collection(&mut con, b"scores", "zset", 0, 20, Some("rank:"), Some("desc")).await.unwrap();

        let RedisCollectionPage::Zset { items, scan_cursor } = result else {
            panic!("expected zset collection page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(
            items,
            vec![
                RedisZsetItem { score: "3".to_string(), member: text_blob("rank:carol") },
                RedisZsetItem { score: "1".to_string(), member: text_blob("rank:alice") },
            ]
        );
        assert_eq!(con.command_count("ZREVRANGE"), 1);
        assert_eq!(con.command_count("ZRANGE"), 0);
    }

    #[tokio::test]
    async fn filtered_zset_load_more_advances_the_cursor_past_every_scanned_member() {
        let mut con = FakeRedisConnection::new(vec![
            zrange_response(vec![("bob", "2"), ("dave", "4"), ("erin", "5")]),
            zrange_response(vec![("rank:alice", "1"), ("rank:carol", "3"), ("grace", "7")]),
        ]);

        let result =
            super::load_more_collection(&mut con, b"scores", "zset", 0, 2, Some("rank:"), Some("asc")).await.unwrap();

        let RedisCollectionPage::Zset { items, scan_cursor } = result else {
            panic!("expected zset collection page");
        };
        assert_eq!(
            items,
            vec![
                RedisZsetItem { score: "1".to_string(), member: text_blob("rank:alice") },
                RedisZsetItem { score: "3".to_string(), member: text_blob("rank:carol") },
            ]
        );
        // Two windows of two were consumed, so resuming must not replay the first one.
        assert_eq!(scan_cursor, Some(4));
        assert_eq!(con.command_count("ZRANGE"), 2);
    }

    #[tokio::test]
    async fn filtered_list_load_more_preserves_original_indices() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Int(8),
            RedisRawValue::Array(vec![
                bulk("alpha"),
                bulk("beta"),
                bulk("gamma"),
                bulk("target-one"),
                bulk("delta"),
                bulk("epsilon"),
                bulk("zeta"),
                bulk("target-two"),
            ]),
        ]);

        let result =
            super::load_more_collection(&mut con, b"list-key", "list", 0, 20, Some("target-"), None).await.unwrap();

        let RedisCollectionPage::List { items, scan_cursor } = result else {
            panic!("expected list collection page");
        };
        assert_eq!(scan_cursor, None);
        // Indices must stay absolute: the viewer deletes list entries by index.
        assert_eq!(
            items,
            vec![
                RedisListItem { index: 3, value: text_blob("target-one") },
                RedisListItem { index: 7, value: text_blob("target-two") },
            ]
        );
        assert_eq!(con.command_count("LRANGE"), 1);
    }

    #[tokio::test]
    async fn filtered_list_load_more_still_walks_when_llen_is_not_permitted() {
        let mut con = FakeRedisConnection::with_results(vec![
            Err(noperm("llen")),
            Ok(RedisRawValue::Array(vec![bulk("target-one"), bulk("beta")])),
            Ok(RedisRawValue::Array(vec![])),
        ]);

        let result =
            super::load_more_collection(&mut con, b"list-key", "list", 0, 2, Some("target-"), None).await.unwrap();

        let RedisCollectionPage::List { items, scan_cursor } = result else {
            panic!("expected list collection page");
        };
        assert_eq!(items, vec![RedisListItem { index: 0, value: text_blob("target-one") }]);
        assert_eq!(scan_cursor, None);
        assert_eq!(con.command_count("LRANGE"), 2);
    }

    #[tokio::test]
    async fn filtered_list_load_more_stops_at_the_list_length() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Int(3),
            RedisRawValue::Array(vec![bulk("alpha"), bulk("beta")]),
            RedisRawValue::Array(vec![bulk("gamma")]),
        ]);

        let result =
            super::load_more_collection(&mut con, b"list-key", "list", 0, 2, Some("missing"), None).await.unwrap();

        let RedisCollectionPage::List { items, scan_cursor } = result else {
            panic!("expected list collection page");
        };
        assert!(items.is_empty());
        assert_eq!(scan_cursor, None);
        assert_eq!(con.command_count("LRANGE"), 2);
        assert_eq!(con.command_count("LLEN"), 1);
    }

    #[tokio::test]
    async fn binary_hash_ttl_discovery_avoids_unsafe_unknown_command_errors() {
        for (key, field) in
            [(b"hash".as_slice(), b"\x03kryo\xf3".as_slice()), (b"hash\xff", b"field"), (b"hash", b"field\r\n")]
        {
            let mut items = vec![RedisHashItem {
                field: redis_blob_from_bytes(field),
                value: redis_blob_from_bytes(b"\x01value\xff"),
                field_ttl: None,
            }];
            let original = items.clone();
            let mut con = FakeRedisConnection::new(vec![RedisRawValue::Array(vec![RedisRawValue::Nil])]);
            super::attach_hash_field_ttls(&mut con, key, &mut items).await.unwrap();
            assert_eq!(items, original);
            assert_eq!(con.command_count("COMMAND"), 1);
            assert_eq!(con.commands.len(), 1);
            assert!(!con.commands[0].contains("\r\nFIELDS\r\n"));
            assert!(con.responses.is_empty());

            let mut con = FakeRedisConnection::new(vec![
                RedisRawValue::Array(vec![RedisRawValue::Array(vec![bulk("httl")])]),
                httl_response(1, 42),
            ]);
            super::attach_hash_field_ttls(&mut con, key, &mut items).await.unwrap();
            assert_eq!(items[0].field_ttl, Some(42));
            assert_eq!(con.commands.len(), 2);
            assert!(con.commands[1].contains("\r\nFIELDS\r\n"));
            assert!(con.responses.is_empty());
        }
    }

    #[tokio::test]
    async fn binary_hash_command_discovery_only_suppresses_optional_errors() {
        let mut items = vec![RedisHashItem {
            field: redis_blob_from_bytes(b"\x03kryo\xf3"),
            value: text_blob("value"),
            field_ttl: None,
        }];
        let mut con = FakeRedisConnection::with_results(vec![Err(noperm("command"))]);
        super::attach_hash_field_ttls(&mut con, b"hash", &mut items).await.unwrap();
        assert_eq!(con.commands.len(), 1);
        assert_eq!(items[0].field_ttl, None);

        let mut con = FakeRedisConnection::with_results(vec![Err(redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "server error",
            "unrelated discovery failure".to_string(),
        )))]);
        assert!(super::attach_hash_field_ttls(&mut con, b"hash", &mut items)
            .await
            .unwrap_err()
            .contains("unrelated discovery failure"));
    }

    #[tokio::test]
    async fn hash_load_more_attaches_field_ttl_when_supported() {
        let mut con = FakeRedisConnection::new(vec![
            hscan_response("0", vec![("session", "Ada")]),
            RedisRawValue::Array(vec![RedisRawValue::Int(42)]),
        ]);

        let result = super::load_more_collection(&mut con, b"hash-key", "hash", 0, 20, None, None).await.unwrap();

        let RedisCollectionPage::Hash { items, scan_cursor } = result else {
            panic!("expected hash collection page");
        };
        assert_eq!(scan_cursor, None);
        assert_eq!(items[0].field_ttl, Some(42));
        assert_eq!(con.command_count("HTTL"), 1);
    }

    #[tokio::test]
    async fn hash_load_more_keeps_persistent_field_ttl() {
        let mut con = FakeRedisConnection::new(vec![
            hscan_response("0", vec![("session", "Ada")]),
            RedisRawValue::Array(vec![RedisRawValue::Int(-1)]),
        ]);

        let result = super::load_more_collection(&mut con, b"hash-key", "hash", 0, 20, None, None).await.unwrap();

        let RedisCollectionPage::Hash { items, .. } = result else {
            panic!("expected hash collection page");
        };
        assert_eq!(items[0].field_ttl, Some(-1));
    }

    #[tokio::test]
    async fn hash_load_more_degrades_when_field_ttl_is_unsupported() {
        let unsupported = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "unknown command 'HTTL'".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(hscan_response("0", vec![("session", "Ada")])),
            Err(unsupported),
        ]);

        let result = super::load_more_collection(&mut con, b"hash-key", "hash", 0, 20, None, None).await.unwrap();

        let RedisCollectionPage::Hash { items, .. } = result else {
            panic!("expected hash collection page");
        };
        assert_eq!(items[0].field_ttl, None);
    }

    #[tokio::test]
    async fn hash_set_preserves_existing_field_ttl() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Array(vec![RedisRawValue::Int(42)]),
            RedisRawValue::Okay,
            RedisRawValue::Array(vec![RedisRawValue::Int(1)]),
        ]);

        super::hash_set(&mut con, b"hash-key", "session", "Grace", None).await.unwrap();

        assert_eq!(con.command_count("HTTL"), 1);
        assert_eq!(con.command_count("HSET"), 1);
        assert_eq!(con.command_count("HEXPIRE"), 1);
    }

    fn legacy_hash_expiry_error() -> redis::RedisError {
        redis::parse_redis_value(
            b"-ERR Invalid argument: hash field expiration is not supported by legacy hash encoding\r\n",
        )
        .unwrap()
        .extract_error()
        .unwrap_err()
    }

    #[tokio::test]
    async fn legacy_hash_value_keeps_bounded_pages_and_key_ttl() {
        let pairs = (0..201).map(|index| (format!("f{index}"), format!("v{index}"))).collect();
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("hash")),
            Ok(RedisRawValue::Int(73)),
            Ok(RedisRawValue::Int(201)),
            Ok(hscan_response_owned("0", pairs)),
            Err(legacy_hash_expiry_error()),
            Err(legacy_hash_expiry_error()),
        ]);

        let value = super::get_value(&mut con, b"legacy-paged-hash").await.unwrap();
        assert_eq!(value.ttl, 73);
        let RedisValueData::Hash { items, total, scan_cursor } = value.data else {
            panic!("expected hash");
        };
        assert_eq!(total, 201);
        assert_eq!(items.len(), 200);
        assert!(items.iter().all(|item| item.field_ttl.is_none()));
        assert_eq!(items[199].field, text_blob("f199"));
        let page =
            super::load_more_collection(&mut con, b"legacy-paged-hash", "hash", scan_cursor.unwrap(), 200, None, None)
                .await
                .unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = page else {
            panic!("expected hash page");
        };
        assert_eq!(items, vec![RedisHashItem { field: text_blob("f200"), value: text_blob("v200"), field_ttl: None }]);
        assert_eq!(scan_cursor, None);
        assert_eq!(con.command_count("HSCAN"), 1);
        assert_eq!(con.command_count("HTTL"), 2);
        assert!(con.commands[4].contains("\r\n200\r\n"));
        assert!(!con.commands[4].contains("\r\nf200\r\n"));
        assert!(con.responses.is_empty());
    }

    #[tokio::test]
    async fn legacy_hash_load_more_does_not_disable_ttl_for_other_hashes() {
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(hscan_response("17", vec![("field", "value")])),
            Err(legacy_hash_expiry_error()),
            Ok(hscan_response("0", vec![("field", "value")])),
            Ok(httl_response(1, 42)),
        ]);
        for (key, cursor, expected_ttl) in [(b"legacy".as_slice(), Some(17), None), (b"modern", None, Some(42))] {
            let page = super::load_more_collection(&mut con, key, "hash", 0, 1, None, None).await.unwrap();
            let RedisCollectionPage::Hash { items, scan_cursor } = page else {
                panic!("expected hash page");
            };
            assert_eq!(scan_cursor, cursor);
            assert_eq!(
                items,
                vec![RedisHashItem { field: text_blob("field"), value: text_blob("value"), field_ttl: expected_ttl }]
            );
        }
        assert_eq!(con.command_count("HTTL"), 2);
        assert!(con.responses.is_empty());
    }

    #[tokio::test]
    async fn legacy_hash_set_does_not_disable_ttl_for_other_hashes() {
        let mut con = FakeRedisConnection::with_results(vec![
            Err(legacy_hash_expiry_error()),
            Ok(RedisRawValue::Okay),
            Ok(httl_response(1, 42)),
            Ok(RedisRawValue::Okay),
            Ok(httl_response(1, 1)),
        ]);
        super::hash_set(&mut con, b"legacy", "field", "value", None).await.unwrap();
        super::hash_set(&mut con, b"modern", "field", "value", None).await.unwrap();
        assert_eq!(con.command_count("HTTL"), 2);
        assert_eq!(con.command_count("HSET"), 2);
        assert_eq!(con.command_count("HEXPIRE"), 1);
        assert_eq!(con.command_count("EXPIRE"), 0);
        assert!(con.commands[4].contains("\r\nmodern\r\n$2\r\n42\r\n"));
        assert!(con.responses.is_empty());
    }

    #[tokio::test]
    async fn hash_ttl_discovery_keeps_unrelated_errors_fatal() {
        for detail in [
            "operation not supported",
            "Invalid argument: hash field expiration is not supported by another encoding",
            "WRONGTYPE Operation against a key holding the wrong kind of value",
            "Invalid argument: hash field expiration is not supported by legacy hash encoding: extra failure",
        ] {
            let error = || {
                redis::RedisError::from((
                    redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
                    "server error",
                    detail.to_string(),
                ))
            };
            let mut con = FakeRedisConnection::with_results(vec![Err(error())]);
            assert!(super::hash_set(&mut con, b"hash", "field", "value", None).await.unwrap_err().contains(detail));
            assert_eq!(con.command_count("HSET"), 0);
            let mut con =
                FakeRedisConnection::with_results(vec![Ok(hscan_response("0", vec![("f", "v")])), Err(error())]);
            assert!(super::load_more_collection(&mut con, b"hash", "hash", 0, 1, None, None)
                .await
                .unwrap_err()
                .contains(detail));
        }
        let disconnected =
            || redis::RedisError::from(std::io::Error::new(std::io::ErrorKind::ConnectionReset, "connection reset"));
        let mut con = FakeRedisConnection::with_results(vec![Err(disconnected())]);
        assert!(super::hash_set(&mut con, b"hash", "field", "value", None).await.is_err());
        assert_eq!(con.command_count("HSET"), 0);
        let mut con =
            FakeRedisConnection::with_results(vec![Ok(hscan_response("0", vec![("f", "v")])), Err(disconnected())]);
        assert!(super::load_more_collection(&mut con, b"hash", "hash", 0, 1, None, None).await.is_err());
    }

    #[tokio::test]
    async fn legacy_hash_explicit_expiry_errors_remain_visible() {
        let mut con = FakeRedisConnection::with_results(vec![
            Err(legacy_hash_expiry_error()),
            Err(legacy_hash_expiry_error()),
            Err(legacy_hash_expiry_error()),
        ]);
        assert!(super::set_hash_field_ttl(&mut con, b"hash", "field", 60).await.is_err());
        assert!(super::set_hash_field_ttl(&mut con, b"hash", "field", -1).await.is_err());
        assert!(super::set_hash_field_expire_at(&mut con, b"hash", "field", 1_735_689_600).await.is_err());
        assert_eq!(con.command_count("HEXPIRE"), 1);
        assert_eq!(con.command_count("HPERSIST"), 1);
        assert_eq!(con.command_count("HEXPIREAT"), 1);
    }

    #[tokio::test]
    async fn hash_set_keeps_explicit_key_ttl_and_missing_field_behavior() {
        for ttl in [Some(60), Some(0), Some(-1)] {
            let mut con = FakeRedisConnection::new(vec![RedisRawValue::Okay, RedisRawValue::Okay]);
            super::hash_set(&mut con, b"hash", "field", "value", ttl).await.unwrap();
            assert_eq!(con.command_count("HTTL"), 0);
            assert_eq!(con.command_count("HSET"), 1);
            assert_eq!(con.command_count("EXPIRE"), usize::from(ttl == Some(60)));
        }
        for response in [httl_response(1, -2), httl_response(1, -1), httl_response(0, -2)] {
            let mut con = FakeRedisConnection::new(vec![response, RedisRawValue::Okay]);
            super::hash_set(&mut con, b"hash", "field", "value", None).await.unwrap();
            assert_eq!(con.command_count("HSET"), 1);
            assert_eq!(con.command_count("HEXPIRE"), 0);
        }
        let mut con = FakeRedisConnection::new(vec![hscan_response("0", vec![])]);
        let page = super::load_more_collection(&mut con, b"hash", "hash", 0, 1, None, None).await.unwrap();
        assert!(matches!(page, RedisCollectionPage::Hash { items, scan_cursor: None } if items.is_empty()));
        assert_eq!(con.command_count("HTTL"), 0);
    }

    #[tokio::test]
    async fn legacy_hash_update_handles_encoding_only_in_discovery() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(2)]);
        super::hash_field_update(&mut con, b"hash", "old", "new", "value").await.unwrap();
        assert_eq!(con.commands.len(), 1);
        assert_eq!(con.command_count("EVAL"), 1);
        let script = &con.commands[0];
        let discovery =
            script.split("local ttl_reply =").nth(1).unwrap().split("local function restore_source").next().unwrap();
        assert!(discovery.contains("hash field expiration is not supported by legacy hash encoding"));
        let writes = script.split("local function restore_source").nth(1).unwrap();
        assert!(!writes.contains("legacy hash encoding"));
    }

    #[tokio::test]
    async fn legacy_hash_pages_keep_byte_and_sparse_scan_limits() {
        let value = "v".repeat(super::COLLECTION_PAGE_MAX_BYTES / 2);
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(hscan_response("0", vec![("first", &value), ("second", &value)])),
            Err(legacy_hash_expiry_error()),
            Err(legacy_hash_expiry_error()),
        ]);
        let mut cursor = 0;
        for field in ["first", "second"] {
            let page = super::load_more_collection(&mut con, b"legacy-byte-limit", "hash", cursor, 200, None, None)
                .await
                .unwrap();
            let RedisCollectionPage::Hash { items, scan_cursor } = page else {
                panic!("expected hash page");
            };
            assert_eq!(items.len(), 1);
            assert_eq!(items[0].field, text_blob(field));
            assert_eq!(items[0].value, text_blob(&value));
            assert!(items[0].field_ttl.is_none());
            assert!(super::hash_item_page_bytes(&items[0]) <= super::COLLECTION_PAGE_MAX_BYTES);
            cursor = scan_cursor.unwrap_or(0);
        }
        assert_eq!(cursor, 0);
        assert_eq!(con.command_count("HSCAN"), 1);
        assert_eq!(con.command_count("HTTL"), 2);

        let mut responses = (1..=super::COLLECTION_FILTER_SCAN_MAX_ITERATIONS)
            .map(|cursor| Ok(hscan_response(&cursor.to_string(), vec![("field", "unmatched")])))
            .collect::<Vec<_>>();
        *responses.last_mut().unwrap() = Ok(hscan_response("10", vec![("field", "wanted")]));
        responses.push(Err(legacy_hash_expiry_error()));
        responses.insert(0, Ok(RedisRawValue::Nil));
        let mut con = FakeRedisConnection::with_results(responses);
        let page =
            super::load_more_collection(&mut con, b"legacy-sparse", "hash", 0, 20, Some("wanted"), None).await.unwrap();
        let RedisCollectionPage::Hash { items, scan_cursor } = page else {
            panic!("expected hash page");
        };
        assert_eq!(items.len(), 1);
        assert_eq!(items[0].value, text_blob("wanted"));
        assert!(items[0].field_ttl.is_none());
        assert_eq!(scan_cursor, Some(10));
        assert_eq!(con.command_count("HSCAN"), 10);
        assert_eq!(con.command_count("HTTL"), 1);
    }

    #[tokio::test]
    async fn hash_ttl_discovery_preserves_rust_permission_fallback() {
        let mut con = FakeRedisConnection::with_results(vec![
            Err(noperm("httl")),
            Ok(RedisRawValue::Okay),
            Ok(hscan_response("0", vec![("f", "v")])),
            Err(noperm("httl")),
        ]);
        super::hash_set(&mut con, b"hash", "field", "value", None).await.unwrap();
        let page = super::load_more_collection(&mut con, b"hash", "hash", 0, 1, None, None).await.unwrap();
        assert!(matches!(page, RedisCollectionPage::Hash { items, .. } if items[0].field_ttl.is_none()));
        assert_eq!(con.command_count("HTTL"), 2);
        assert_eq!(con.command_count("HSET"), 1);
    }

    #[tokio::test]
    async fn legacy_hash_fallback_keeps_write_and_scan_errors_visible() {
        let mut con = FakeRedisConnection::with_results(vec![Err(legacy_hash_expiry_error()), Err(noperm("hset"))]);
        assert!(super::hash_set(&mut con, b"hash", "field", "value", None).await.is_err());
        assert_eq!(con.command_count("HSET"), 1);
        assert_eq!(con.commands.len(), 2);
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(httl_response(1, 42)),
            Ok(RedisRawValue::Okay),
            Err(legacy_hash_expiry_error()),
        ]);
        assert!(super::hash_set(&mut con, b"hash", "field", "value", None).await.is_err());
        assert_eq!(con.command_count("HEXPIRE"), 1);
        let mut con = FakeRedisConnection::with_results(vec![
            Ok(bulk("hash")),
            Ok(RedisRawValue::Int(-1)),
            Ok(RedisRawValue::Int(1)),
            Err(noperm("hscan")),
        ]);
        assert!(super::get_value(&mut con, b"hash").await.is_err());
        assert_eq!(con.command_count("HTTL"), 0);
    }

    #[tokio::test]
    #[ignore = "requires disposable Redis via DBX_TEST_REDIS_URL; injects Kvrocks HTTL replies into production Lua"]
    async fn hash_field_update_lua_legacy_encoding_regression() {
        let mut trace = FakeRedisConnection::new(vec![RedisRawValue::Int(2)]);
        super::hash_field_update(&mut trace, b"hash", "old", "new", "after").await.unwrap();
        let RedisRawValue::Array(args) = redis::parse_redis_value(trace.commands[0].as_bytes()).unwrap() else {
            panic!("expected EVAL arguments");
        };
        let script = String::from_utf8(redis_value_to_bytes(args[1].clone()).unwrap()).unwrap();
        let probe = "redis.pcall('HTTL', key, 'FIELDS', 1, old_field)";
        assert_eq!(script.matches(probe).count(), 1);
        let url = std::env::var("DBX_TEST_REDIS_URL").expect("DBX_TEST_REDIS_URL");
        let mut con = super::connect(&url, std::time::Duration::from_secs(5)).await.unwrap();
        let nonce = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();
        let key = format!("dbx-10948-{}-{nonce}", std::process::id());
        for (reply, success) in [
            ("Invalid argument: hash field expiration is not supported by legacy hash encoding", true),
            ("ERR Invalid argument: hash field expiration is not supported by legacy hash encoding", true),
            ("NOPERM no permission to run HTTL", false),
            ("WRONGTYPE Operation against a key holding the wrong kind of value", false),
            ("ERR operation not supported", false),
            (
                "ERR Invalid argument: hash field expiration is not supported by legacy hash encoding: extra failure",
                false,
            ),
        ] {
            let injected = script.replace(probe, &format!("{{err = '{reply}'}}"));
            for destination in ["old", "new"] {
                redis::cmd("DEL").arg(&key).query_async::<()>(&mut con).await.unwrap();
                redis::cmd("HSET")
                    .arg(&key)
                    .arg("old")
                    .arg("before")
                    .arg("keeper")
                    .arg("keep")
                    .query_async::<()>(&mut con)
                    .await
                    .unwrap();
                redis::cmd("EXPIRE").arg(&key).arg(60).query_async::<()>(&mut con).await.unwrap();
                let result: i64 = redis::cmd("EVAL")
                    .arg(&injected)
                    .arg(1)
                    .arg(&key)
                    .arg("old")
                    .arg(destination)
                    .arg("after")
                    .query_async(&mut con)
                    .await
                    .unwrap();
                assert_eq!(
                    result,
                    if success {
                        if destination == "old" {
                            1
                        } else {
                            2
                        }
                    } else {
                        -3
                    },
                    "{reply}"
                );
                let fields: HashMap<String, String> =
                    redis::cmd("HGETALL").arg(&key).query_async(&mut con).await.unwrap();
                let expected = if success { (destination, "after") } else { ("old", "before") };
                assert_eq!(
                    fields,
                    HashMap::from([
                        (expected.0.to_string(), expected.1.to_string()),
                        ("keeper".to_string(), "keep".to_string()),
                    ])
                );
                let ttl: i64 = redis::cmd("TTL").arg(&key).query_async(&mut con).await.unwrap();
                assert!((1..=60).contains(&ttl));
            }
        }
        redis::cmd("DEL").arg(&key).query_async::<()>(&mut con).await.unwrap();
    }

    #[tokio::test]
    async fn hash_set_degrades_when_field_ttl_is_rejected_as_unknown_redis_command() {
        let unsupported = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "unknown redis command HTTL".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![Err(unsupported), Ok(RedisRawValue::Okay)]);

        super::hash_set(&mut con, b"hash-key", "session", "Grace", None).await.unwrap();

        assert_eq!(con.command_count("HTTL"), 1);
        assert_eq!(con.command_count("HSET"), 1);
        assert_eq!(con.command_count("HEXPIRE"), 0);
    }

    #[tokio::test]
    async fn hash_field_update_uses_one_atomic_script_and_carries_field_ttl() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(2)]);

        super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap();

        assert_eq!(con.command_count("EVAL"), 1);
        // HSET/HDEL/HTTL/HEXPIRE are script body text, not independent
        // requests.  This guards the atomic path and its TTL handling.
        assert_eq!(con.command_count("HSET"), 0);
        assert_eq!(con.command_count("HDEL"), 0);
        assert!(con.commands[0].contains("redis.call('HEXISTS'"));
        assert!(con.commands[0].contains("redis.pcall('HTTL'"));
        assert!(con.commands[0].contains("redis.pcall('HEXPIRE'"));
        assert!(con.commands[0].contains("redis.pcall('HDEL'"));
        assert!(con.commands[0].contains("local delete_probe"));
        assert!(con.commands[0].contains("if source_ttl == 0 then"));
        // Regression guard for #7584: Redis < 7.4 answers the HTTL/HEXPIRE
        // probe with "Unknown Redis command called from [Lua] script", which
        // has to be recognised as an unsupported-command reply so the update
        // degrades instead of returning -3.
        assert!(con.commands[0].contains("'unknown redis command'"));
    }

    /// End-to-end regression for #7584 against a real Redis < 7.4.
    ///
    /// Set `DBX_TEST_REDIS_URL` to a Redis that predates hash-field expiry
    /// (for example `redis://127.0.0.1:6379` backed by Redis 7.2 or 6.2).
    /// The HTTL probe inside the Lua script fails there, and before the fix
    /// the mismatched error wording made both value-only edits and renames
    /// return "failed before completion". This exercises the actual
    /// `hash_field_update` path so the Lua matcher runs on the server.
    #[tokio::test]
    #[ignore = "requires a Redis without hash-field expiry via DBX_TEST_REDIS_URL"]
    async fn hash_field_update_degrades_on_redis_without_hash_field_ttl() {
        let url = std::env::var("DBX_TEST_REDIS_URL").expect("DBX_TEST_REDIS_URL");
        let mut con = super::connect(&url, std::time::Duration::from_secs(5)).await.unwrap();

        let key = b"dbx-7584-regression";
        redis::cmd("DEL").arg(&key[..]).query_async::<()>(&mut con).await.unwrap();
        redis::cmd("HSET").arg(&key[..]).arg("old_field").arg("value1").query_async::<()>(&mut con).await.unwrap();

        // Confirm this server takes the exact unsupported-command path that
        // triggered the regression rather than merely accepting HTTL.
        let unsupported_detail: String = redis::cmd("EVAL")
            .arg(
                "local reply = redis.pcall('HTTL', KEYS[1], 'FIELDS', 1, ARGV[1]); \
                 if type(reply) == 'table' and reply.err ~= nil then return reply.err end; \
                 return 'supported'",
            )
            .arg(1)
            .arg(&key[..])
            .arg("old_field")
            .query_async(&mut con)
            .await
            .unwrap();
        assert!(
            unsupported_detail.to_ascii_lowercase().contains("unknown redis command called from"),
            "expected Redis without hash-field expiry, got: {unsupported_detail}"
        );

        // Value-only edit must still succeed even though HTTL is unsupported.
        super::hash_field_update(&mut con, key, "old_field", "old_field", "value2").await.unwrap();
        let current: String = redis::cmd("HGET").arg(&key[..]).arg("old_field").query_async(&mut con).await.unwrap();
        assert_eq!(current, "value2");

        // Field rename must also succeed and leave only the new field behind.
        super::hash_field_update(&mut con, key, "old_field", "new_field", "value3").await.unwrap();
        let renamed: String = redis::cmd("HGET").arg(&key[..]).arg("new_field").query_async(&mut con).await.unwrap();
        assert_eq!(renamed, "value3");
        let old_exists: i64 = redis::cmd("HEXISTS").arg(&key[..]).arg("old_field").query_async(&mut con).await.unwrap();
        assert_eq!(old_exists, 0);

        redis::cmd("DEL").arg(&key[..]).query_async::<()>(&mut con).await.unwrap();
    }

    #[tokio::test]
    async fn hash_field_update_rejects_destination_collisions_without_follow_up_commands() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(-1)]);

        let error = super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap_err();

        assert!(error.contains("new name already exists"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.commands.len(), 1);
    }

    #[tokio::test]
    async fn hash_field_update_reports_a_missing_source_field() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(0)]);

        let error = super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap_err();

        assert!(error.contains("no longer exists"));
        assert_eq!(con.command_count("EVAL"), 1);
    }

    #[tokio::test]
    async fn hash_field_update_supports_value_only_edits_without_renaming() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(1)]);

        super::hash_field_update(&mut con, b"hash-key", "session", "session", "Grace").await.unwrap();

        assert_eq!(con.command_count("EVAL"), 1);
        assert!(con.commands[0].contains("if old_field == new_field then"));
    }

    #[tokio::test]
    async fn hash_field_update_keeps_failures_inside_the_atomic_operation() {
        let failure = redis::make_extension_error("ERR".to_string(), Some("script command failed".to_string()));
        let mut con = FakeRedisConnection::with_results(vec![Err(failure)]);

        let error = super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap_err();

        assert!(error.contains("script command failed"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.command_count("HSET"), 0);
        assert_eq!(con.command_count("HDEL"), 0);
    }

    #[tokio::test]
    async fn hash_field_update_falls_back_when_cluster_rejects_field_ttl_script() {
        let rejection = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "bad lua script for redis cluster, redis.call/pcall unknown redis command HTTL".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![Err(rejection), Ok(RedisRawValue::Int(1))]);

        super::hash_field_update(&mut con, b"hash-key", "session", "session", "Grace").await.unwrap();

        assert_eq!(con.command_count("EVAL"), 2);
        assert!(con.commands[0].contains("redis.pcall('HTTL'"));
        assert!(!con.commands[1].contains("redis.pcall('HTTL'"));
        assert!(!con.commands[1].contains("redis.pcall('HEXPIRE'"));
        assert!(con.commands[1].contains("redis.call('HSET'") || con.commands[1].contains("redis.pcall('HSET'"));
    }

    #[tokio::test]
    async fn hash_field_update_falls_back_for_renames_when_cluster_rejects_field_ttl_script() {
        let rejection = redis::RedisError::from((
            redis::ErrorKind::Server(redis::ServerErrorKind::ResponseError),
            "An error was signalled by the server",
            "bad lua script for redis cluster, redis.call/pcall unknown redis command HTTL".to_string(),
        ));
        let mut con = FakeRedisConnection::with_results(vec![Err(rejection), Ok(RedisRawValue::Int(2))]);

        super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap();

        assert_eq!(con.command_count("EVAL"), 2);
        assert!(!con.commands[1].contains("redis.pcall('HTTL'"));
        assert!(!con.commands[1].contains("redis.pcall('HEXPIRE'"));
        assert!(con.commands[1].contains("old_field ~= new_field"));
        assert!(con.commands[1].contains("redis.pcall('HDEL', key, old_field)"));
    }

    #[tokio::test]
    async fn hash_field_update_reports_restricted_eval_access_without_fallback() {
        let mut con = FakeRedisConnection::with_results(vec![Err(noperm("eval"))]);

        let error = super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap_err();

        assert!(error.contains("EVAL and hash command permissions"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.commands.len(), 1);
    }

    #[tokio::test]
    async fn hash_field_update_does_not_restore_a_source_that_disappeared_before_hdel() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(2)]);

        super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap();

        let script = &con.commands[0];
        let delete_branch = script.find("if tonumber(deleted) ~= 1 then").expect("HDEL result branch");
        let branch = &script[delete_branch..];
        assert!(branch.contains("redis.pcall('HDEL', key, new_field)"));
        assert!(branch.contains("return 0"));
        assert!(!branch.contains("restore_source()"));
    }

    #[tokio::test]
    async fn concurrent_hash_field_updates_use_serialized_evals_and_reject_the_loser() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(2), RedisRawValue::Int(0)]);

        super::hash_field_update(&mut con, b"hash-key", "session", "account", "Grace").await.unwrap();
        let error = super::hash_field_update(&mut con, b"hash-key", "session", "profile", "Grace").await.unwrap_err();

        assert!(error.contains("no longer exists"));
        assert_eq!(con.command_count("EVAL"), 2);
        assert_eq!(con.commands.len(), 2);
    }

    #[tokio::test]
    async fn hash_field_expiry_commands_accept_expected_results() {
        let mut con = FakeRedisConnection::new(vec![
            RedisRawValue::Array(vec![RedisRawValue::Int(1)]),
            RedisRawValue::Array(vec![RedisRawValue::Int(-1)]),
            RedisRawValue::Array(vec![RedisRawValue::Int(1)]),
        ]);

        super::set_hash_field_ttl(&mut con, b"hash-key", "session", 60).await.unwrap();
        super::set_hash_field_ttl(&mut con, b"hash-key", "session", -1).await.unwrap();
        super::set_hash_field_expire_at(&mut con, b"hash-key", "session", 1_735_689_600).await.unwrap();

        assert_eq!(con.command_count("HEXPIRE"), 1);
        assert_eq!(con.command_count("HPERSIST"), 1);
        assert_eq!(con.command_count("HEXPIREAT"), 1);
    }

    #[tokio::test]
    async fn filtered_hash_load_more_caps_sparse_scan_iterations() {
        let responses = (1..=super::COLLECTION_FILTER_SCAN_MAX_ITERATIONS + 1)
            .map(|cursor| hscan_response(&cursor.to_string(), vec![]))
            .collect::<Vec<_>>();
        let mut responses = responses;
        responses.insert(0, RedisRawValue::Nil);
        let mut con = FakeRedisConnection::new(responses);

        let result =
            super::load_more_collection(&mut con, b"hash-key", "hash", 0, 20, Some("missing"), None).await.unwrap();

        let RedisCollectionPage::Hash { items, scan_cursor } = result else {
            panic!("expected hash collection page");
        };
        assert_eq!(scan_cursor, Some(super::COLLECTION_FILTER_SCAN_MAX_ITERATIONS as u64));
        assert!(items.is_empty());
        assert_eq!(con.command_count("HSCAN"), super::COLLECTION_FILTER_SCAN_MAX_ITERATIONS);
    }

    #[tokio::test]
    async fn zset_update_passes_expected_score_to_the_atomic_script() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(1)]);

        let used_acl_compatibility =
            super::zset_update(&mut con, b"scores", "alice", "10", "alice", "20").await.unwrap();

        assert!(!used_acl_compatibility);
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.command_count("ZADD"), 0);
        assert!(con.commands[0].contains("\r\n$2\r\n10\r\n"));
        assert!(con.commands[0].contains("\r\n$2\r\n20\r\n"));
    }

    #[tokio::test]
    async fn zset_update_rejects_a_second_writer_with_a_stale_score() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(-2)]);

        let error = super::zset_update(&mut con, b"scores", "alice", "10", "alice", "30").await.unwrap_err();

        assert!(error.contains("score changed"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.commands.len(), 1);
    }

    #[tokio::test]
    async fn zset_update_rejects_a_second_writer_renaming_a_member_with_a_stale_score() {
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Int(-2)]);

        let error = super::zset_update(&mut con, b"scores", "alice", "10", "alicia", "20").await.unwrap_err();

        assert!(error.contains("score changed"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.command_count("ZADD"), 0);
        assert_eq!(con.command_count("ZREM"), 0);
        assert_eq!(con.commands.len(), 1);
    }

    #[tokio::test]
    async fn zset_update_rejects_restricted_acl_score_edits_without_writing() {
        let mut con = FakeRedisConnection::with_results(vec![Err(noperm("eval"))]);

        let error = super::zset_update(&mut con, b"scores", "alice", "10", "alice", "20").await.unwrap_err();

        assert!(error.contains("EVAL and ZSCORE permissions"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.command_count("ZADD"), 0);
        assert_eq!(con.command_count("ZREM"), 0);
        assert_eq!(con.commands.len(), 1);
    }

    #[tokio::test]
    async fn zset_update_rejects_restricted_acl_renames_without_writing() {
        let mut con = FakeRedisConnection::with_results(vec![Err(noperm("zscore"))]);

        let error = super::zset_update(&mut con, b"scores", "alice", "10", "alicia", "20").await.unwrap_err();

        assert!(error.contains("EVAL and ZSCORE permissions"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.command_count("ZADD"), 0);
        assert_eq!(con.command_count("ZREM"), 0);
        assert_eq!(con.commands.len(), 1);
    }

    #[tokio::test]
    async fn zset_update_does_not_fallback_for_unrelated_acl_errors() {
        let mut con = FakeRedisConnection::with_results(vec![Err(noperm("zrem"))]);

        let error = super::zset_update(&mut con, b"scores", "alice", "10", "alicia", "20").await.unwrap_err();

        assert!(error.to_ascii_uppercase().contains("NOPERM"));
        assert_eq!(con.command_count("EVAL"), 1);
        assert_eq!(con.commands.len(), 1);
    }

    #[tokio::test]
    async fn zset_load_more_uses_ranked_ascending_pages() {
        let mut con =
            FakeRedisConnection::new(vec![zrange_response(vec![("alice", "1"), ("bob", "2"), ("carol", "3")])]);

        let result = super::load_more_collection(&mut con, b"scores", "zset", 0, 2, None, Some("asc")).await.unwrap();

        let RedisCollectionPage::Zset { items, scan_cursor } = result else {
            panic!("expected zset collection page");
        };
        assert_eq!(
            items,
            vec![
                RedisZsetItem { score: "1".to_string(), member: text_blob("alice") },
                RedisZsetItem { score: "2".to_string(), member: text_blob("bob") },
            ]
        );
        assert_eq!(scan_cursor, Some(2));
        assert_eq!(con.command_count("ZRANGE"), 1);
        assert_eq!(con.command_count("ZREVRANGE"), 0);
        assert_eq!(con.command_count("ZSCAN"), 0);
    }

    #[tokio::test]
    async fn zset_load_more_uses_ranked_descending_pages() {
        let mut con =
            FakeRedisConnection::new(vec![zrange_response(vec![("carol", "3"), ("bob", "2"), ("alice", "1")])]);

        let result = super::load_more_collection(&mut con, b"scores", "zset", 0, 2, None, Some("desc")).await.unwrap();

        let RedisCollectionPage::Zset { items, scan_cursor } = result else {
            panic!("expected zset collection page");
        };
        assert_eq!(
            items,
            vec![
                RedisZsetItem { score: "3".to_string(), member: text_blob("carol") },
                RedisZsetItem { score: "2".to_string(), member: text_blob("bob") },
            ]
        );
        assert_eq!(scan_cursor, Some(2));
        assert_eq!(con.command_count("ZRANGE"), 0);
        assert_eq!(con.command_count("ZREVRANGE"), 1);
        assert_eq!(con.command_count("ZSCAN"), 0);
    }

    #[test]
    fn does_not_treat_utf8_with_backslashes_as_binary() {
        let raw = RedisRawValue::BulkString(br#"C:\Users\path"#.to_vec());

        let blob = redis_value_to_bytes(raw).map(|bytes| redis_blob_from_bytes(&bytes)).unwrap();
        assert_eq!(blob.encoding, RedisBlobEncoding::Utf8);
    }

    #[test]
    fn preserves_non_ascii_utf8_as_utf8() {
        let raw = RedisRawValue::BulkString("你好,redis".as_bytes().to_vec());

        let blob = redis_value_to_bytes(raw).map(|bytes| redis_blob_from_bytes(&bytes)).unwrap();
        assert_eq!(blob.encoding, RedisBlobEncoding::Utf8);
    }

    #[test]
    fn parses_command_text_with_quotes_and_escapes() {
        let argv = parse_command_argv(r#"SET "user:1" "Ada \"Lovelace\"""#).unwrap();
        assert_eq!(argv, vec![b"SET".to_vec(), b"user:1".to_vec(), b"Ada \"Lovelace\"".to_vec()]);

        let argv = parse_command_argv(r#"DEL "cache\\session""#).unwrap();
        assert_eq!(argv, vec![b"DEL".to_vec(), b"cache\\session".to_vec()]);

        let argv = parse_command_argv(r#"DEL "bin\x00key\xff""#).unwrap();
        assert_eq!(argv, vec![b"DEL".to_vec(), b"bin\0key\xff".to_vec()]);
        // Note: raw byte 0xff is preserved as a single byte 0xff, NOT UTF-8 encoded U+00FF (0xc3, 0xbf)
        assert_eq!(argv[1], vec![b'b', b'i', b'n', 0x00, b'k', b'e', b'y', 0xff]);
    }

    #[test]
    fn parses_empty_quoted_arguments() {
        let argv = parse_command_argv(r#"SET "" """#).unwrap();

        assert_eq!(argv, vec![b"SET".to_vec(), b"".to_vec(), b"".to_vec()]);
    }

    #[test]
    fn parses_quoted_and_escaped_command_names_before_classification() {
        for command_text in [r#""JSON.SET" user:1 $ {}"#, r#"JSON\.SET user:1 $ {}"#] {
            let argv = parse_command_argv(command_text).unwrap();
            let cmd = String::from_utf8_lossy(&argv[0]).to_ascii_uppercase();
            assert_eq!(classify_command(&cmd), RedisCommandSafety::Write);
        }
    }

    #[test]
    fn rejects_empty_command_text() {
        for command_text in ["   ", "\"\""] {
            assert_eq!(parse_command_argv(command_text).unwrap_err(), "Redis command is empty");
        }
    }

    #[tokio::test]
    async fn raw_command_execution_preserves_binary_bytes_and_isolates_similar_text_keys() {
        use std::collections::HashSet;

        struct TargetIsolatingConnection {
            keys: HashSet<Vec<u8>>,
            captured_commands: Vec<Vec<u8>>,
        }

        impl ConnectionLike for TargetIsolatingConnection {
            fn req_packed_command<'a>(&'a mut self, cmd: &'a Cmd) -> RedisFuture<'a, RedisRawValue> {
                let packed = cmd.get_packed_command();
                self.captured_commands.push(packed.clone());
                // Parse RESP array: *<count>\r\n$<len>\r\n<arg>\r\n...
                if packed.starts_with(b"*") {
                    let mut pos = 0;
                    if let Some(crlf) = packed[pos..].windows(2).position(|w| w == b"\r\n") {
                        pos += crlf + 2;
                        let mut args = Vec::new();
                        while pos < packed.len() {
                            if packed[pos] == b'$' {
                                if let Some(len_end) = packed[pos..].windows(2).position(|w| w == b"\r\n") {
                                    let len_str = std::str::from_utf8(&packed[pos + 1..pos + len_end]).unwrap();
                                    let arg_len: usize = len_str.parse().unwrap();
                                    let start = pos + len_end + 2;
                                    let end = start + arg_len;
                                    args.push(packed[start..end].to_vec());
                                    pos = end + 2;
                                } else {
                                    break;
                                }
                            } else {
                                break;
                            }
                        }
                        if args.first().is_some_and(|c| c.eq_ignore_ascii_case(b"DEL")) {
                            for k in &args[1..] {
                                self.keys.remove(k);
                            }
                        }
                    }
                }
                Box::pin(async move { Ok(RedisRawValue::Int(1)) })
            }

            fn req_packed_commands<'a>(
                &'a mut self,
                cmd: &'a Pipeline,
                _offset: usize,
                count: usize,
            ) -> RedisFuture<'a, Vec<RedisRawValue>> {
                self.captured_commands.push(cmd.get_packed_pipeline());
                Box::pin(async move { Ok(vec![RedisRawValue::Int(1); count]) })
            }

            fn get_db(&self) -> i64 {
                0
            }
        }

        let key_ff = vec![0xff];
        let key_utf8_y_diaeresis = "ÿ".as_bytes().to_vec(); // [0xc3, 0xbf]
        let key_80 = vec![0x80];
        let key_c2_80 = vec![0xc2, 0x80]; // U+0080 in UTF-8
        let key_nul = b"bin\x00key".to_vec();
        let key_zero = b"bin0key".to_vec();
        let key_zhong_n = vec![0xe4, 0xb8, 0xad, 0x5c, 0x6e]; // "中\n" in bytes
        let key_zhong_nl = vec![0xe4, 0xb8, 0xad, 0x0a]; // "中<newline>" in bytes

        let mut con = TargetIsolatingConnection {
            keys: HashSet::from([
                key_ff.clone(),
                key_utf8_y_diaeresis.clone(),
                key_80.clone(),
                key_c2_80.clone(),
                key_nul.clone(),
                key_zero.clone(),
                key_zhong_n.clone(),
                key_zhong_nl.clone(),
            ]),
            captured_commands: Vec::new(),
        };

        // 1. Delete binary 0xff key: DEL "\xff"
        super::execute_command(&mut con, r#"DEL "\xff""#, true).await.unwrap();
        // Verify wire bytes: bulk string length must be $1, containing single byte 0xff
        let last_cmd = con.captured_commands.last().unwrap();
        assert!(last_cmd.ends_with(b"$1\r\n\xff\r\n"), "must send raw byte 0xff with length 1");
        assert!(!con.keys.contains(&key_ff), "0xff key must be deleted");
        assert!(con.keys.contains(&key_utf8_y_diaeresis), "UTF-8 'ÿ' key [0xc3, 0xbf] must NOT be deleted");

        // 2. Delete UTF-8 'ÿ' key: DEL "ÿ"
        super::execute_command(&mut con, r#"DEL "ÿ""#, true).await.unwrap();
        let last_cmd = con.captured_commands.last().unwrap();
        assert!(last_cmd.ends_with(b"$2\r\n\xc3\xbf\r\n"), "must send UTF-8 bytes for 'ÿ' with length 2");
        assert!(!con.keys.contains(&key_utf8_y_diaeresis), "UTF-8 'ÿ' key must now be deleted");

        // 3. Delete binary 0x80 key: DEL "\x80"
        super::execute_command(&mut con, r#"DEL "\x80""#, true).await.unwrap();
        let last_cmd = con.captured_commands.last().unwrap();
        assert!(last_cmd.ends_with(b"$1\r\n\x80\r\n"), "must send raw byte 0x80 with length 1");
        assert!(!con.keys.contains(&key_80), "0x80 key must be deleted");
        assert!(con.keys.contains(&key_c2_80), "[0xc2, 0x80] key must NOT be deleted");

        // 4. Delete binary NUL key: DEL "bin\x00key"
        super::execute_command(&mut con, r#"DEL "bin\x00key""#, true).await.unwrap();
        let last_cmd = con.captured_commands.last().unwrap();
        assert!(last_cmd.ends_with(b"$7\r\nbin\x00key\r\n"), "must send raw NUL byte inside key");
        assert!(!con.keys.contains(&key_nul), "NUL key must be deleted");
        assert!(con.keys.contains(&key_zero), "bin0key must NOT be deleted");

        // 5. Delete "中\n" (bytes: e4 b8 ad 5c 6e): DEL "中\\n"
        super::execute_command(&mut con, r#"DEL "中\\n""#, true).await.unwrap();
        let last_cmd = con.captured_commands.last().unwrap();
        assert!(last_cmd.ends_with(b"$5\r\n\xe4\xb8\xad\\n\r\n"), "must send exact bytes for 中\\n");
        assert!(!con.keys.contains(&key_zhong_n), "中\\n key must be deleted");
        assert!(con.keys.contains(&key_zhong_nl), "中<newline> key must NOT be deleted");
    }

    #[tokio::test]
    async fn raw_command_execution_fails_closed_before_sending_invalid_or_unknown_commands() {
        let mut con = FakeRedisConnection::new(Vec::new());

        let unknown = super::execute_command(&mut con, "VENDOR.WRITE key value", false).await.unwrap_err();
        assert!(unknown.contains("blocked for safety"));

        let malformed = super::execute_command(&mut con, r#"GET "unterminated"#, true).await.unwrap_err();
        assert_eq!(malformed, "Redis command has an unterminated quote");
        assert!(con.commands.is_empty());
    }

    #[test]
    fn matches_redis_values_case_insensitively() {
        assert!(redis_value_matches_query(&string_value("Hello Redis"), "redis"));
        assert!(redis_value_matches_query(&hash_value(&[("field", "Ada Lovelace")]), "lovelace"));
        assert!(!redis_value_matches_query(&string_value("Hello Redis"), ""));
        assert!(!redis_value_matches_query(&string_value("Hello Redis"), "mysql"));
    }

    #[test]
    fn matches_redis_keys_case_insensitively() {
        assert!(redis_key_matches_query("User:42:Profile", "User:42:Profile", "profile"));
        assert!(redis_key_matches_query("binary key", "ff75736572", "FF75"));
        assert!(!redis_key_matches_query("User:42:Profile", "User:42:Profile", ""));
        assert!(!redis_key_matches_query("User:42:Profile", "User:42:Profile", "order"));
    }

    #[test]
    fn sparse_key_scan_continues_after_empty_iterations() {
        assert!(super::should_continue_key_scan(0, 1000, 8, 50));
    }

    #[test]
    fn key_scan_stops_when_result_page_is_full() {
        assert!(!super::should_continue_key_scan(1000, 1000, 3, 50));
        assert!(!super::should_continue_key_scan(1200, 1000, 3, 50));
    }

    #[test]
    fn key_scan_respects_iteration_budget() {
        assert!(!super::should_continue_key_scan(0, 1000, 50, 50));
        assert!(!super::should_continue_key_scan(0, 0, 1, 1));
    }

    #[test]
    fn matches_hash_field_name_in_value_search() {
        let hash_value = hash_value(&[("name", "Alice"), ("email", "[email protected]")]);
        assert!(redis_value_matches_query(&hash_value, "name"));
        assert!(redis_value_matches_query(&hash_value, "email"));
    }

    #[test]
    fn matches_hash_field_value_in_value_search() {
        let hash_value = hash_value(&[("name", "Alice"), ("email", "[email protected]")]);
        assert!(redis_value_matches_query(&hash_value, "alice"));
        assert!(redis_value_matches_query(&hash_value, "example"));
    }

    #[test]
    fn empty_hash_does_not_match() {
        let empty_hash = hash_value(&[]);
        assert!(!redis_value_matches_query(&empty_hash, "anything"));
    }

    #[test]
    fn non_hash_array_unaffected() {
        let set_value = set_value(&["member1", "member2", "hello"]);
        assert!(redis_value_matches_query(&set_value, "member1"));
        assert!(redis_value_matches_query(&set_value, "hello"));
        assert!(!redis_value_matches_query(&set_value, "nonexistent"));
    }

    #[test]
    fn classifies_safe_confirmed_and_blocked_commands() {
        assert_eq!(classify_command("GET"), RedisCommandSafety::Allowed);
        assert_eq!(classify_command("JSON.GET"), RedisCommandSafety::Allowed);
        assert_eq!(classify_command("set"), RedisCommandSafety::Write);
        assert_eq!(classify_command("hset"), RedisCommandSafety::Write);
        assert_eq!(classify_command("JSON.SET"), RedisCommandSafety::Write);
        assert_eq!(classify_command("GETEX"), RedisCommandSafety::Write);
        assert_eq!(classify_command("XREADGROUP"), RedisCommandSafety::Write);
        assert_eq!(classify_command("del"), RedisCommandSafety::Confirm);
        assert_eq!(classify_command("flushdb"), RedisCommandSafety::Blocked);
        assert_eq!(classify_command("JSON.DEL"), RedisCommandSafety::Confirm);
        assert_eq!(classify_command("JSON.FORGET"), RedisCommandSafety::Confirm);
        assert_eq!(classify_command("JSON.CLEAR"), RedisCommandSafety::Confirm);
        assert_eq!(classify_command("KEYS"), RedisCommandSafety::Blocked);
        assert_eq!(classify_command("flushall"), RedisCommandSafety::Blocked);
        assert_eq!(classify_command("eval"), RedisCommandSafety::Blocked);
        assert_eq!(classify_command("FCALL"), RedisCommandSafety::Blocked);
        assert_eq!(classify_command("XGROUP"), RedisCommandSafety::Blocked);
        assert_eq!(classify_command("VENDOR.WRITE"), RedisCommandSafety::Blocked);
    }

    // Regression for review feedback: an unknown command (e.g. FCALL) inside a
    // multi-statement batch must still raise the batch to Blocked regardless
    // of its position, so "DEL victim\nFCALL wipe 0" cannot execute the
    // destructive command after the frontend scan would otherwise have
    // stopped the run.
    #[test]
    fn classify_command_batch_blocks_on_any_unknown_member() {
        for batch in [
            // destructive first, unknown second
            ["DEL victim", "FCALL wipe 0"],
            // unknown first, destructive second
            ["FCALL wipe 0", "DEL victim"],
        ] {
            let mut highest = RedisCommandSafety::Allowed;
            for cmd in batch.iter() {
                let safety = classify_command(cmd);
                if matches!(safety, RedisCommandSafety::Blocked) {
                    highest = safety;
                    break;
                }
                if matches!(safety, RedisCommandSafety::Confirm) && !matches!(highest, RedisCommandSafety::Blocked) {
                    highest = safety;
                }
            }
            assert!(
                matches!(highest, RedisCommandSafety::Blocked),
                "batch {batch:?} must be Blocked because it contains FCALL, got {highest:?}"
            );
        }
    }

    #[test]
    fn converts_command_results_to_json() {
        let raw = RedisRawValue::Array(vec![
            RedisRawValue::SimpleString("OK".to_string()),
            RedisRawValue::Int(2),
            RedisRawValue::Nil,
        ]);

        assert_eq!(redis_command_raw_to_json(raw), serde_json::json!(["OK", 2, null]));
    }

    #[test]
    fn converts_command_unsafe_int64_to_string_for_js() {
        let raw = RedisRawValue::Int(2_326_645_729_978_441_729);

        assert_eq!(redis_command_raw_to_json(raw), serde_json::json!("2326645729978441729"));
    }

    #[test]
    fn converts_bulkstring_json_with_unsafe_int64_for_js() {
        let raw = RedisRawValue::BulkString(br#"{"uid":2321205972557213697,"name":"test"}"#.to_vec());

        assert_eq!(redis_command_raw_to_json(raw), serde_json::json!({"uid": "2321205972557213697", "name": "test"}));
    }

    #[test]
    fn keeps_plain_bulkstring_as_is() {
        let raw = RedisRawValue::BulkString(b"hello world".to_vec());
        assert_eq!(redis_command_raw_to_json(raw), serde_json::json!("hello world"));
    }

    #[test]
    fn keeps_string_like_number_as_string() {
        let raw = RedisRawValue::BulkString(b"42".to_vec());
        assert_eq!(redis_command_raw_to_json(raw), serde_json::json!("42"));
    }

    #[test]
    fn recognizes_redis_json_module_key_types() {
        assert!(is_redis_json_type("ReJSON-RL"));
        assert!(is_redis_json_type("json"));
        assert!(!is_redis_json_type("string"));
    }

    #[test]
    fn parses_redis_sentinel_endpoints_with_default_ports() {
        assert_eq!(parse_redis_endpoint("sentinel.local:26380", 26379).unwrap(), ("sentinel.local".to_string(), 26380));
        assert_eq!(
            parse_redis_endpoint("redis://user:[email protected]:26380/0", 26379).unwrap(),
            ("sentinel.local".to_string(), 26380)
        );
        assert_eq!(parse_redis_endpoint("sentinel.local", 26379).unwrap(), ("sentinel.local".to_string(), 26379));
        assert_eq!(parse_redis_endpoint("[::1]:26380", 26379).unwrap(), ("::1".to_string(), 26380));
        assert_eq!(parse_redis_endpoint("::1", 26379).unwrap(), ("::1".to_string(), 26379));
    }

    #[test]
    fn parses_redis_sentinel_master_lookup_response() {
        let raw = RedisRawValue::Array(vec![bulk("10.0.0.8"), bulk("6379")]);

        assert_eq!(
            redis_sentinel_master_endpoint(raw).unwrap(),
            RedisNodeEndpoint { host: "10.0.0.8".to_string(), port: 6379 }
        );
    }

    #[test]
    fn rejects_invalid_redis_sentinel_master_lookup_response() {
        let raw = RedisRawValue::Array(vec![bulk("10.0.0.8")]);

        assert_eq!(
            redis_sentinel_master_endpoint(raw).unwrap_err(),
            "Redis Sentinel master lookup returned an invalid endpoint"
        );
    }

    #[test]
    fn redis_connection_info_marks_tls_as_insecure_when_requested() {
        let info = connection_info("cache.example.com", 6379, true, true, "default", "secret", 0).unwrap();

        assert!(matches!(info.addr(), ConnectionAddr::TcpTls { insecure: true, .. }));
    }

    #[test]
    fn redis_connection_info_preserves_acl_username_and_password() {
        let info = connection_info("cache.example.com", 6379, false, false, "app-user", "secret", 0).unwrap();

        assert_eq!(info.redis_settings().username(), Some("app-user"));
        assert_eq!(info.redis_settings().password(), Some("secret"));
    }

    #[test]
    fn redis_command_denied_errors_are_not_auth_errors() {
        // Issue #9394: a managed Redis account that may connect but may not run PING.
        let noperm = "NOPERM User noping has no permissions to run the 'ping' command";
        assert!(is_redis_command_denied_error(noperm));
        assert!(is_redis_command_denied_error("ERR unknown command 'PING'"));
        assert!(is_redis_command_denied_error("ERR command 'PING' not supported"));
        assert!(is_redis_command_denied_error("command 'PING' not support for your account"));
        assert!(!is_redis_command_denied_error("WRONGPASS invalid username-password pair"));

        // The liveness probe must report a denied PING as plain wording, otherwise the credential
        // fallback in `connect_standalone` retries with a bogus candidate and the user sees a
        // misleading "password authentication failed" instead of the real cause.
        let ping_failure = "Redis ping failed: NOPERM User noping has no permissions to run the 'ping' command";
        assert!(!is_redis_auth_error(ping_failure));
        assert!(is_redis_auth_error("Redis connection failed: WRONGPASS invalid username-password pair"));
    }

    #[test]
    fn redis_auth_candidates_try_username_at_password_fallback() {
        let candidates = redis_auth_candidates("app-user", "secret");

        assert_eq!(
            candidates,
            vec![
                RedisAuthCandidate { username: "app-user".to_string(), password: "secret".to_string() },
                RedisAuthCandidate { username: String::new(), password: "app-user@secret".to_string() },
            ]
        );
    }

    #[test]
    fn standalone_connection_infos_cover_no_auth_acl_fallback_tls_and_database() {
        let mut config = redis_test_connection_config();
        let no_auth = standalone_connection_infos(&config, "127.0.0.1", 6379).unwrap();
        assert_eq!(no_auth.len(), 1);
        assert_eq!(no_auth[0].redis_settings().username(), None);
        assert_eq!(no_auth[0].redis_settings().password(), None);
        assert_eq!(no_auth[0].redis_settings().db(), 0);

        config.username = "app-user".to_string();
        config.password = "secret".to_string();
        config.database = Some("4".to_string());
        config.ssl = true;
        config.url_params = Some("tls_insecure=true".to_string());
        let infos = standalone_connection_infos(&config, "cache.example.com", 6380).unwrap();

        assert_eq!(infos.len(), 2);
        assert!(matches!(infos[0].addr(), ConnectionAddr::TcpTls { port: 6380, insecure: true, .. }));
        assert_eq!(infos[0].redis_settings().username(), Some("app-user"));
        assert_eq!(infos[0].redis_settings().password(), Some("secret"));
        assert_eq!(infos[0].redis_settings().db(), 4);
        assert_eq!(infos[1].redis_settings().username(), None);
        assert_eq!(infos[1].redis_settings().password(), Some("app-user@secret"));
        assert_eq!(infos[1].redis_settings().db(), 4);
    }

    #[test]
    fn redis_database_index_uses_numeric_database_only() {
        let mut config = redis_test_connection_config();
        config.database = Some("4".to_string());

        assert_eq!(redis_database_index(&config), 4);
        config.database = Some("not-a-number".to_string());
        assert_eq!(redis_database_index(&config), 0);
    }

    #[tokio::test]
    #[ignore = "requires disposable standalone/Sentinel/TLS fixtures via DBX_TEST_REDIS_*_PORT"]
    async fn redis_client_migration_live_connections() {
        use futures_util::StreamExt;
        // Match the application entrypoints when workspace builds enable both rustls providers.
        let _ = rustls::crypto::aws_lc_rs::default_provider().install_default();
        let port = |name| std::env::var(name).unwrap().parse::<u16>().unwrap();
        let timeout = Duration::from_secs(5);
        let mut config = redis_test_connection_config();
        config.host = "127.0.0.1".to_string();
        config.port = port("DBX_TEST_REDIS_PORT");
        let mut con = super::connect_standalone(&config, &config.host, config.port, timeout).await.unwrap();
        let mut pubsub = super::connect_pubsub(&config, &config.host, config.port, timeout).await.unwrap();
        let channel = format!("dbx1271:migration:{}", std::process::id());
        pubsub.subscribe(&channel).await.unwrap();
        let payload = b"\x00\xffmigration";
        redis::cmd("PUBLISH").arg(&channel).arg(payload).query_async::<usize>(&mut con).await.unwrap();
        let message = tokio::time::timeout(timeout, pubsub.on_message().next()).await.unwrap().unwrap();
        assert_eq!(message.get_payload_bytes(), payload);
        pubsub.unsubscribe(&channel).await.unwrap();
        drop(pubsub);

        let mut monitor = super::connect_monitor(&config, &config.host, config.port, timeout).await.unwrap();
        redis::cmd("PING").arg(&channel).query_async::<String>(&mut con).await.unwrap();
        let mut stream = monitor.on_message::<String>();
        tokio::time::timeout(timeout, async {
            loop {
                let message = stream.next().await.unwrap();
                if message.contains(&channel) {
                    assert!(message.contains("PING"));
                    break;
                }
            }
        })
        .await
        .unwrap();
        drop(stream);
        drop(monitor);

        config.redis_sentinel_nodes = format!("127.0.0.1:{}", port("DBX_TEST_REDIS_SENTINEL_PORT"));
        config.redis_sentinel_master = "dbx1271master".to_string();
        let mut master = super::connect_sentinel(&config).await.unwrap();
        assert_eq!(redis::cmd("PING").query_async::<String>(&mut master).await.unwrap(), "PONG");
        let role: RedisRawValue = redis::cmd("ROLE").query_async(&mut master).await.unwrap();
        let RedisRawValue::Array(role) = role else { panic!("expected ROLE array") };
        assert_eq!(role[0], bulk("master"));

        config.ssl = true;
        let tls_port = port("DBX_TEST_REDIS_TLS_PORT");
        assert!(super::connect_standalone(&config, &config.host, tls_port, timeout).await.is_err());
        config.url_params = Some("tls_insecure=true".to_string());
        let mut tls = super::connect_standalone(&config, &config.host, tls_port, timeout).await.unwrap();
        assert_eq!(redis::cmd("PING").query_async::<String>(&mut tls).await.unwrap(), "PONG");
    }

    #[test]
    fn redis_tls_certificates_are_loaded_from_configured_paths() {
        let dir = std::env::temp_dir().join(format!("dbx-redis-tls-{}-{}", std::process::id(), "load"));
        std::fs::create_dir_all(&dir).unwrap();
        let ca = dir.join("ca.pem");
        let cert = dir.join("client.pem");
        let key = dir.join("client-key.pem");
        std::fs::write(&ca, b"ca").unwrap();
        std::fs::write(&cert, b"cert").unwrap();
        std::fs::write(&key, b"key").unwrap();

        let mut config = redis_test_connection_config();
        assert!(super::load_redis_tls_certificates(&config).unwrap().is_none());

        config.ca_cert_path = ca.to_string_lossy().to_string();
        config.client_cert_path = cert.to_string_lossy().to_string();
        config.client_key_path = key.to_string_lossy().to_string();
        // Sentinel nodes can enable TLS without enabling it for the data connection.
        assert!(load_redis_tls_certificates(&config).unwrap().is_some());
        config.ssl = true;
        let certificates = load_redis_tls_certificates(&config).unwrap().unwrap();
        assert_eq!(certificates.root_cert.as_deref(), Some(b"ca".as_slice()));
        let client_tls = certificates.client_tls.unwrap();
        assert_eq!(client_tls.client_cert, b"cert");
        assert_eq!(client_tls.client_key, b"key");

        std::fs::remove_dir_all(&dir).unwrap();
    }

    #[test]
    fn redis_tls_certificates_require_both_client_files() {
        let mut config = redis_test_connection_config();
        config.ssl = true;
        config.client_cert_path = "/tmp/only-cert.pem".to_string();
        let error = load_redis_tls_certificates(&config).err().expect("expected certificate error");
        assert!(error.contains("configured together"), "{error}");
    }

    #[test]
    fn redis_tls_certificates_report_unreadable_files() {
        let mut config = redis_test_connection_config();
        config.ssl = true;
        config.ca_cert_path = "/tmp/dbx-missing-ca-certificate.pem".to_string();
        let error = load_redis_tls_certificates(&config).err().expect("expected certificate error");
        assert!(error.contains("Failed to read Redis TLS CA certificate"), "{error}");
        assert!(error.contains("/tmp/dbx-missing-ca-certificate.pem"), "{error}");
    }

    fn redis_test_connection_config() -> ConnectionConfig {
        ConnectionConfig {
            oracle_oci_nls_lang: None,
            oracle_oci_tns_admin: None,
            docs_notes_path: None,
            id: "redis".to_string(),
            name: "Redis".to_string(),
            note: String::new(),
            db_type: dbx_types::models::connection::DatabaseType::Redis,
            driver_profile: None,
            driver_label: None,
            url_params: None,
            agent_java_options: Vec::new(),
            host: "cache.example.com".to_string(),
            port: 6379,
            username: String::new(),
            password: String::new(),
            database: None,
            default_schema: None,
            visible_databases: None,
            visible_database_patterns: None,
            visible_schemas: None,
            show_system_schemas: false,
            sidebar_auto_load_all_tables: false,
            show_database_links: None,
            show_native_jobs: None,
            show_user_admin: None,
            attached_databases: Vec::new(),
            init_script: None,
            color: None,
            transport_layers: Vec::new(),
            connect_timeout_secs: dbx_types::models::connection::default_connect_timeout_secs(),
            query_timeout_secs: dbx_types::models::connection::default_query_timeout_secs(),
            idle_timeout_secs: dbx_types::models::connection::default_idle_timeout_secs(),
            manual_transaction_timeout_secs: dbx_types::models::connection::default_manual_transaction_timeout_secs(),
            idle_disconnect_secs: dbx_types::models::connection::default_idle_disconnect_secs(),
            keepalive_interval_secs: dbx_types::models::connection::default_keepalive_interval_secs(),
            ssl: false,
            ca_cert_path: String::new(),
            client_cert_path: String::new(),
            client_key_path: String::new(),
            sysdba: false,
            oracle_connection_type: None,
            connection_string: None,
            redis_connection_mode: None,
            redis_sentinel_master: String::new(),
            redis_sentinel_nodes: String::new(),
            redis_sentinel_username: String::new(),
            redis_sentinel_password: String::new(),
            redis_sentinel_tls: false,
            redis_cluster_nodes: String::new(),
            redis_key_separator: dbx_types::models::connection::default_redis_key_separator(),
            redis_scan_page_size: None,
            redis_database_aliases: Default::default(),
            redis_key_templates: Vec::new(),
            redis_key_filter: None,
            redis_key_grouping: None,
            etcd_endpoints: String::new(),
            gbase_server: String::new(),
            informix_server: String::new(),
            external_config: None,
            plugin_id: None,
            plugin_connection_provider: None,
            plugin_connection_type: None,
            connection_secrets: HashMap::new(),
            jdbc_driver_class: None,
            jdbc_driver_paths: Vec::new(),
            one_time: false,
            save_password: true,
            read_only: false,
            is_production: false,
            production_databases: vec![],
            production_badge_scope: None,
            database_info: None,
        }
    }

    #[test]
    fn encodes_and_decodes_cluster_scan_cursor() {
        let encoded = encode_cluster_cursor(12, 3456).unwrap();

        assert_eq!(decode_cluster_cursor(encoded), (12, 3456));
        assert_eq!(decode_cluster_cursor(0), (0, 0));
    }

    #[test]
    fn parses_cluster_slots_master_nodes() {
        let raw = RedisRawValue::Array(vec![
            RedisRawValue::Array(vec![
                RedisRawValue::Int(0),
                RedisRawValue::Int(5460),
                RedisRawValue::Array(vec![
                    RedisRawValue::BulkString(b"10.0.0.1".to_vec()),
                    RedisRawValue::Int(7000),
                    RedisRawValue::BulkString(b"node-a".to_vec()),
                ]),
            ]),
            RedisRawValue::Array(vec![
                RedisRawValue::Int(5461),
                RedisRawValue::Int(10922),
                RedisRawValue::Array(vec![
                    RedisRawValue::BulkString(b"10.0.0.2".to_vec()),
                    RedisRawValue::Int(7001),
                    RedisRawValue::BulkString(b"node-b".to_vec()),
                ]),
            ]),
        ]);

        assert_eq!(
            parse_cluster_slots(raw, "127.0.0.1").unwrap(),
            vec![
                RedisClusterSlotRange {
                    start: 0,
                    end: 5460,
                    master: RedisNodeEndpoint { host: "10.0.0.1".to_string(), port: 7000 },
                },
                RedisClusterSlotRange {
                    start: 5461,
                    end: 10922,
                    master: RedisNodeEndpoint { host: "10.0.0.2".to_string(), port: 7001 },
                },
            ]
        );
    }

    #[test]
    fn calculates_redis_cluster_hash_tag_slots() {
        assert_eq!(redis_cluster_slot(b"issue1246:{user}:a"), redis_cluster_slot(b"issue1246:{user}:b"));
        assert_ne!(redis_cluster_slot(b"issue1246:{user}:a"), redis_cluster_slot(b"issue1246:{other}:a"));
    }

    #[test]
    fn preserves_raw_redis_json_text_without_parsing_numbers_for_js() {
        let raw_text =
            r#"{"id":2326645729978441729,"fraction":0.123456789012345678901234,"scientific":1.234567890123456789e20}"#;

        assert_eq!(super::redis_json_raw_to_text(bulk(raw_text)).unwrap(), raw_text);
        assert_eq!(super::redis_json_raw_to_text(RedisRawValue::Nil).unwrap_err(), "RedisJSON key no longer exists");
        assert!(super::redis_json_raw_to_text(RedisRawValue::BulkString(vec![0xff])).is_err());
    }

    #[tokio::test]
    async fn returns_lossless_value_text_for_native_redis_json_values() {
        let value_text = r#"{"id":2326645729978441729,"fraction":0.123456789012345678901234,"name":"Ada"}"#;
        let mut con = FakeRedisConnection::new(vec![bulk("ReJSON-RL"), RedisRawValue::Int(-1), bulk(value_text)]);

        let value = super::get_value(&mut con, b"json:key").await.unwrap();
        let response = serde_json::to_value(&value).unwrap();
        let RedisValueData::Json { value: returned } = value.data else {
            panic!("expected RedisJSON value");
        };
        assert_eq!(returned, value_text);
        assert_eq!(con.command_count("JSON.GET"), 1);

        assert_eq!(response["data"]["value"], value_text);
        assert!(response["data"].get("raw_text").is_none());
    }

    #[tokio::test]
    async fn rejects_a_native_redis_json_key_deleted_after_type_lookup() {
        let mut con = FakeRedisConnection::new(vec![bulk("ReJSON-RL"), RedisRawValue::Int(-1), RedisRawValue::Nil]);

        let error = super::get_value(&mut con, b"json:key").await.unwrap_err();

        assert_eq!(error, "RedisJSON key no longer exists");
    }

    #[tokio::test]
    async fn redis_json_set_keeps_lossless_numeric_literals_in_the_command() {
        let raw_text = r#"{"id":2326645729978441729,"fraction":0.123456789012345678901234}"#;
        let mut con = FakeRedisConnection::new(vec![RedisRawValue::Okay]);

        super::json_set(&mut con, b"json:key", raw_text, None).await.unwrap();

        assert_eq!(con.command_count("JSON.SET"), 1);
        assert!(con.commands[0].contains(raw_text));
    }

    #[test]
    fn uses_lightweight_redis_json_placeholder_for_key_scan_preview() {
        assert_eq!(redis_key_value_preview("ReJSON-RL"), "{...}");
        assert_eq!(redis_key_value_preview("string"), "");
    }
}