Crate connection_pool 

Connection Pool

A flexible, high-performance, generic async connection pool for Rust with background cleanup and comprehensive logging.

✨ Features

• 🚀 High Performance: Background cleanup eliminates connection acquisition latency
• 🔧 Fully Generic: Support for any connection type (TCP, Database, HTTP, etc.)
• ⚡ Async/Await Native: Built on tokio with modern async Rust patterns
• 🛡️ Thread Safe: Concurrent connection sharing with proper synchronization
• 🧹 Smart Cleanup: Configurable background task for expired connection removal
• 📊 Rich Logging: Comprehensive observability with configurable log levels
• 🔄 Auto-Return: RAII-based automatic connection return to pool
• ⏱️ Timeout Control: Configurable timeouts for connection creation
• 🎯 Type Safe: Compile-time guarantees with zero-cost abstractions
• 🧩 Extensible: Custom connection types and validation logic via the ConnectionManager trait
• 🌐 Versatile: Suitable for TCP, database, and any custom connection pooling

Quick Start

Add connection-pool to your Cargo.toml:

[dependencies]
connection-pool = "0.2"
tokio = { version = "1.47", features = ["full"] }

Then you can use the connection pool in your application:

// 1. Define your ConnectionManager
use connection_pool::{ConnectionManager, ConnectionPool};
use std::future::Future;
use std::pin::Pin;
use tokio::net::TcpStream;

#[derive(Clone)]
pub struct TcpConnectionManager {
    pub address: std::net::SocketAddr,
}

impl ConnectionManager for TcpConnectionManager {
    type Connection = TcpStream;
    type Error = std::io::Error;
    type CreateFut = Pin<Box<dyn Future<Output = Result<TcpStream, Self::Error>> + Send>>;
    type ValidFut<'a> = Pin<Box<dyn Future<Output = bool> + Send + 'a>>;

    fn create_connection(&self) -> Self::CreateFut {
        let addr = self.address;
        Box::pin(async move { TcpStream::connect(addr).await })
    }

    fn is_valid<'a>(&'a self, conn: &'a mut Self::Connection) -> Self::ValidFut<'a> {
        Box::pin(async move {
            // Lightweight socket check only; for real liveness use a protocol heartbeat.
            conn.peer_addr().is_ok()
        })
    }
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // 2. Create a connection pool
    let manager = TcpConnectionManager { address: "127.0.0.1:8080".parse().unwrap() };
    let pool = ConnectionPool::new(
        Some(10), // max pool size
        None,     // default idle timeout
        None,     // default connection timeout
        None,     // default cleanup config
        manager,
    );

    // 3. Acquire and use a connection
    let mut conn = pool.clone().get_connection().await.unwrap();
    use tokio::io::AsyncWriteExt;
    conn.write_all(b"hello").await.unwrap();
    Ok(())
}

peer_addr() is only a cheap socket-level check. It can tell you whether the stream still exists locally, but it does not prove that the remote service is actually healthy or ready to speak your protocol.

If you need stronger validation, add an application-level heartbeat such as ping/pong, and make is_valid send and verify that message instead of touching the data stream with a read.

Advanced Usage

• You can pool any connection type (e.g. database, API client) by implementing the ConnectionManager trait.
• For TCP, prefer a protocol-level health check when you need to prove the peer is responsive.
• See examples/db_example.rs for a custom type example.

Testing

cargo test

🎛️ Configuration Options

Parameter	Description	Default
max_size	Maximum number of connections	10
max_idle_time	Connection idle timeout	5 minutes
connection_timeout	Connection creation timeout	10 seconds
cleanup_interval	Background cleanup interval	30 seconds
MAX_IDLE_KEEP	Maximum number of idle connections kept (≤ max_size)	8

max_size still governs concurrency (via the semaphore); MAX_IDLE_KEEP only bounds how many idle connections are retained for reuse. Keeping the full max_size idle made the pool validate dozens of idle connections and churn under load, so the idle reserve is deliberately small.

🏗️ Architecture

The connection pool is now based on a single ConnectionManager abstraction:

┌──────────────────────────────────────────────┐
│           ConnectionPool<M: Manager>         │
├──────────────────────────────────────────────┤
│  • Holds a user-defined ConnectionManager    │
│  • Manages a queue of pooled connections     │
│  • Semaphore for max concurrent connections  │
│  • Background cleanup for idle connections   │
└──────────────────────────────────────────────┘
                │
      ┌─────────┴─────────┐
      │                   │
┌─────▼─────┐   ┌─────────▼────────┐
│ Semaphore │   │ Background Task  │
│ (Limits   │   │ (Cleans up idle  │
│  max conn)│   │  connections)    │
└───────────┘   └──────────────────┘
      │
┌─────▼────────────┐
│ Connection Queue │
│ (VecDeque)       │
└──────────────────┘
      │
┌─────▼────────────┐
│  PooledStream    │
│  (RAII wrapper   │
│   auto-returns)  │
└──────────────────┘

Key Components

• Semaphore: Controls maximum concurrent connections
• Background Cleanup: Async task for removing expired connections
• Connection Queue: FIFO queue of available connections
• RAII Wrapper: PooledStream for automatic connection return

🧪 Testing

Run the examples to see the pool in action:

# Basic TCP example
cargo run --example echo_example

# Database connection example
cargo run --example db_example

# Background cleanup demonstration
cargo run --example background_cleanup_example

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Documentation
• Crates.io
• Repository

Structs

CleanupConfig

Configuration for background cleanup task

ConnectionPool

Connection pool

ManagedConnection

Pooled managed stream, provided for the outer world usage

TcpConnectionManager

Example implementation for TcpStream

Enums

PoolError

Connection pool errors

Constants

MAX_IDLE_KEEP

Maximum number of idle connections kept in the pool, regardless of max_size. Bounding the idle reserve prevents the pool from hoarding dozens of idle tunnels after a burst (which then all get validated with a 3s Ping and discarded -> “Connection validation failed” churn).

Traits

ConnectionManager

Manager responsible for creating new ConnectionManager::Connections or checking existing ones.

Type Aliases

TcpConnectionPool

Convenience type aliases for TCP connections

TcpManagedConnection

Managed TCP stream