aria2-core 0.3.8

aria2-rust core download engine: multi-protocol segmented downloads, rate limiting, configuration, session persistence, and BitTorrent seeding
Documentation
//! FTP connection pool for connection reuse and performance optimization.
//!
//! This module provides a connection pool for FTP control connections that:
//! - Reuses existing connections to avoid repeated authentication
//! - Implements LRU eviction strategy when pool is full
//! - Supports concurrent access from multiple download tasks
//! - Provides health checking for stale connections
//!
//! # Performance Benefits
//!
//! Connection pooling provides 40-60% speed improvement by:
//! - Eliminating 10-second connection establishment overhead
//! - Avoiding repeated authentication handshakes
//! - Reducing TCP connection setup latency
//!
//! # Example
//!
//! ```rust,no_run
//! use aria2_core::ftp::connection_pool::FtpConnectionPool;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let pool = FtpConnectionPool::new(10); // Max 10 connections
//!     
//!     // Check if a connection is available
//!     let has = pool.has_connection("ftp.example.com", 21, "user").await;
//!     println!("Has connection: {}", has);
//!     
//!     // Get pool stats
//!     let stats = pool.stats().await;
//!     println!("Current pool size: {}", stats.current_size);
//!     
//!     // Cleanup stale connections
//!     pool.cleanup_stale().await;
//!     
//!     Ok(())
//! }
//! ```

mod operations;
mod stats;

#[cfg(test)]
mod tests;

use std::collections::HashMap;
use std::sync::Arc;
use std::time::Duration;

use tokio::io::BufReader;
use tokio::net::TcpStream;
use tokio::sync::Mutex;

use crate::ftp::connection::FtpMode;

/// Connection key for identifying unique FTP server connections.
///
/// The key format matches C++ `createSockPoolKey`:
/// `username@host(port)` -- when `base_working_dir` differs,
/// connections are pooled separately so CWD traversal can be skipped
/// on reuse when the base directory matches.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ConnectionKey {
    /// Server hostname
    pub host: String,
    /// Server port
    pub port: u16,
    /// Username for authentication
    pub username: String,
    /// Password for authentication (stored for reconnection if needed)
    pub password: String,
    /// Base working directory from PWD command (used for CWD skip optimization).
    /// Matches C++ `FtpConnection::getBaseWorkingDir()` stored in
    /// `SocketPoolEntry::options_`.
    pub base_working_dir: String,
}

impl ConnectionKey {
    /// Create a new connection key.
    pub fn new(
        host: &str,
        port: u16,
        username: &str,
        password: &str,
        base_working_dir: &str,
    ) -> Self {
        Self {
            host: host.to_string(),
            port,
            username: username.to_string(),
            password: password.to_string(),
            base_working_dir: base_working_dir.to_string(),
        }
    }

    /// Create a connection key with default base_working_dir ("/").
    pub fn new_simple(host: &str, port: u16, username: &str, password: &str) -> Self {
        Self::new(host, port, username, password, "/")
    }

    /// Format the key in C++ `createSockPoolKey` style for logging.
    pub fn to_pool_key_string(&self) -> String {
        if self.username.is_empty() {
            format!("{}({})", self.host, self.port)
        } else {
            format!("{}@{}({})", self.username, self.host, self.port)
        }
    }
}

/// Raw pooled FTP control stream.
///
/// Wraps a TCP stream from a successfully negotiated FTP control connection.
/// When a connection is returned to the pool after a download completes (226),
/// the control stream is stored here for reuse by subsequent downloads that
/// can skip authentication and CWD traversal.
#[derive(Debug)]
pub struct RawControlStream {
    /// The buffered control stream
    pub reader: BufReader<TcpStream>,
    /// When this connection was created
    pub created_at: std::time::Instant,
    /// When this connection was last used
    pub last_used: std::time::Instant,
    /// Number of times this connection has been reused
    pub reuse_count: u64,
}

impl RawControlStream {
    /// Create a new raw control stream wrapper.
    pub fn new(stream: TcpStream, _read_timeout: Duration) -> Self {
        let now = std::time::Instant::now();
        Self {
            reader: BufReader::new(stream),
            created_at: now,
            last_used: now,
            reuse_count: 0,
        }
    }

    /// Mark this connection as used (update last_used timestamp).
    pub fn mark_used(&mut self) {
        self.last_used = std::time::Instant::now();
        self.reuse_count += 1;
    }

    /// Get the age of this connection.
    pub fn age(&self) -> Duration {
        self.created_at.elapsed()
    }

    /// Get how long this connection has been idle.
    pub fn idle_time(&self) -> Duration {
        self.last_used.elapsed()
    }

    /// Check if this connection is still healthy.
    pub fn is_healthy(&self, max_idle_time: Duration) -> bool {
        self.last_used.elapsed() < max_idle_time
    }

    /// Consume and return the inner TCP stream.
    pub fn into_inner(self) -> TcpStream {
        self.reader.into_inner()
    }

    /// Consume and return the buffered reader.
    pub fn into_buf_reader(self) -> BufReader<TcpStream> {
        self.reader
    }
}

/// Pooled FTP connection with metadata.
///
/// Stores a raw FTP control stream along with connection metadata.
/// The `base_working_dir` from `ConnectionKey` allows subsequent downloads
/// to determine whether CWD traversal can be skipped.
pub struct PooledConnection {
    /// The raw control stream (post-authentication, post-CWD)
    pub control: RawControlStream,
    /// Connection key for identification
    pub key: ConnectionKey,
    /// Connection mode (passive/active)
    pub mode: FtpMode,
    /// Read timeout for I/O operations on this connection
    pub read_timeout: Duration,
}

impl std::fmt::Debug for PooledConnection {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PooledConnection")
            .field("key", &self.key)
            .field("mode", &self.mode)
            .field("read_timeout", &self.read_timeout)
            .field("age", &self.control.age())
            .field("idle_time", &self.control.idle_time())
            .field("reuse_count", &self.control.reuse_count)
            .finish_non_exhaustive()
    }
}

impl PooledConnection {
    /// Create a new pooled connection from a raw control stream.
    pub fn new(
        stream: TcpStream,
        key: ConnectionKey,
        mode: FtpMode,
        read_timeout: Duration,
    ) -> Self {
        Self {
            control: RawControlStream::new(stream, read_timeout),
            key,
            mode,
            read_timeout,
        }
    }

    /// Check if this connection is still healthy.
    pub fn is_healthy(&self, max_idle_time: Duration) -> bool {
        self.control.is_healthy(max_idle_time)
    }

    /// Get the age of this connection.
    pub fn age(&self) -> Duration {
        self.control.age()
    }

    /// Get how long this connection has been idle.
    pub fn idle_time(&self) -> Duration {
        self.control.idle_time()
    }

    /// Mark this connection as used (update last_used timestamp).
    pub fn mark_used(&mut self) {
        self.control.mark_used();
    }

    /// Get the base working directory for this pooled connection.
    pub fn base_working_dir(&self) -> &str {
        &self.key.base_working_dir
    }
}

/// LRU entry for tracking access order
#[derive(Debug, Clone)]
pub(crate) struct LruEntry {
    pub(crate) key: ConnectionKey,
    pub(crate) last_access: std::time::Instant,
}

/// FTP connection pool configuration
#[derive(Debug, Clone)]
pub struct PoolConfig {
    /// Maximum number of connections in the pool
    pub max_connections: usize,
    /// Maximum idle time before a connection is considered stale
    pub max_idle_time: Duration,
    /// Maximum age of a connection before it's evicted
    pub max_connection_age: Duration,
    /// Connection timeout for new connections
    pub connect_timeout: Duration,
    /// Read timeout for operations
    pub read_timeout: Duration,
}

impl Default for PoolConfig {
    fn default() -> Self {
        Self {
            max_connections: crate::constants::FTP_POOL_DEFAULT_MAX_CONNECTIONS,
            max_idle_time: Duration::from_secs(
                crate::constants::FTP_POOL_DEFAULT_MAX_IDLE_TIME_SECS,
            ),
            max_connection_age: Duration::from_secs(
                crate::constants::FTP_POOL_DEFAULT_MAX_CONNECTION_AGE_SECS,
            ),
            connect_timeout: Duration::from_secs(
                crate::constants::FTP_POOL_DEFAULT_CONNECT_TIMEOUT_SECS,
            ),
            read_timeout: Duration::from_secs(crate::constants::FTP_POOL_DEFAULT_READ_TIMEOUT_SECS),
        }
    }
}

/// Thread-safe FTP connection pool with LRU eviction
pub struct FtpConnectionPool {
    /// Connection storage
    pub(crate) connections: Arc<Mutex<HashMap<ConnectionKey, PooledConnection>>>,
    /// LRU tracking (ordered by last access time)
    pub(crate) lru_order: Arc<Mutex<Vec<LruEntry>>>,
    /// Pool configuration
    pub(crate) config: PoolConfig,
    /// Statistics
    pub(crate) stats: Arc<Mutex<PoolStats>>,
}

impl FtpConnectionPool {
    /// Remove stale idle connections and return the number removed.
    pub async fn cleanup_stale_count(&self) -> usize {
        let before = self.size().await;
        self.cleanup_stale().await;
        before.saturating_sub(self.size().await)
    }

    /// Create a new connection pool with default configuration
    pub fn new(max_connections: usize) -> Self {
        let config = PoolConfig {
            max_connections,
            ..Default::default()
        };
        Self::with_config(config)
    }

    /// Create a new connection pool with custom configuration
    pub fn with_config(config: PoolConfig) -> Self {
        Self {
            connections: Arc::new(Mutex::new(HashMap::new())),
            lru_order: Arc::new(Mutex::new(Vec::new())),
            config,
            stats: Arc::new(Mutex::new(PoolStats::default())),
        }
    }
}

/// Create a new FTP connection pool with default configuration.
///
/// Use this to create an injectable pool instance instead of relying on a global singleton.
/// The pool should be created once during engine initialization and passed down via dependency injection.
pub fn create_pool(max_connections: usize) -> Arc<FtpConnectionPool> {
    Arc::new(FtpConnectionPool::new(max_connections))
}

/// Create a custom FTP connection pool with specific configuration.
pub fn create_custom_pool(config: PoolConfig) -> Arc<FtpConnectionPool> {
    Arc::new(FtpConnectionPool::with_config(config))
}

// Re-export sibling module items so the public API is unchanged.
pub use stats::PoolStats;