domain-status 0.2.1

Concurrent URL status checker that captures comprehensive metadata in SQLite.
Documentation
//! Database connection pool management.
//!
//! This module initializes and configures the `SQLite` connection pool with:
//! - WAL mode enabled for concurrent access
//! - Connection limits and timeouts
//! - Automatic database file creation (via `spawn_blocking` to avoid blocking tokio runtime)

use std::fs::OpenOptions;
use std::io::ErrorKind;
use std::str::FromStr;
use std::sync::Arc;
use std::time::Duration;

use log::{error, info};
use sqlx::sqlite::{SqliteConnectOptions, SqlitePoolOptions};
use sqlx::{Pool, Sqlite};

use crate::error_handling::DatabaseError;
use crate::utils::{ensure_parent_dir_secure, IoErrorContext};

/// Type alias for database connection pool.
/// Used throughout the codebase for consistency.
pub type DbPool = Arc<Pool<Sqlite>>;

/// Ceiling for scan-time pool connections. `SQLite` has one writer; WAL only
/// helps readers. `--max-concurrency` can be `10_000` and must not open that many
/// connections.
pub(crate) const SQLITE_POOL_CONNECTION_CAP: u32 = 32;

/// Floor so a scan with concurrency 1 still has a writer plus a reader slot.
pub(crate) const SQLITE_POOL_CONNECTION_FLOOR: u32 = 2;

/// Map scan `--max-concurrency` to `SqlitePoolOptions::max_connections`.
#[must_use]
pub(crate) fn sqlite_pool_size(max_concurrency: usize) -> u32 {
    u32::try_from(max_concurrency)
        .unwrap_or(SQLITE_POOL_CONNECTION_CAP)
        .clamp(SQLITE_POOL_CONNECTION_FLOOR, SQLITE_POOL_CONNECTION_CAP)
}

/// Initializes and returns a database connection pool with an explicit path.
///
/// Creates the database file if it doesn't exist and enables WAL mode
/// for better concurrent access.
///
/// Scan callers pass a capped `max_connections` (`sqlite_pool_size`), not 1:1
/// with `--max-concurrency`.
///
/// # Examples
///
/// ```no_run
/// use domain_status::init_db_pool_with_path;
/// use std::path::Path;
///
/// # #[tokio::main]
/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let pool = init_db_pool_with_path(Path::new("./domain_status.db"), 30).await?;
/// assert!(!pool.is_closed());
/// # Ok(())
/// # }
/// ```
///
/// # Errors
/// Returns `Err` when the database file cannot be created or the connection pool cannot be initialized.
pub async fn init_db_pool_with_path(
    db_path: &std::path::Path,
    max_connections: u32,
) -> Result<DbPool, DatabaseError> {
    let db_path_str = db_path.to_string_lossy().to_string();

    // Ensure parent directory exists with secure permissions (0o700 on Unix) before creating DB file.
    ensure_parent_dir_secure(db_path).map_err(|e| DatabaseError::FileCreationError {
        context: format!(
            "Failed to create database directory for {}",
            db_path.display()
        ),
        source: Box::new(e),
    })?;

    // Wrap blocking filesystem operation in spawn_blocking to avoid blocking tokio runtime.
    // This is a one-time startup operation, so impact is low, but good practice.
    let path_for_task = db_path_str.clone();
    let file_creation_result = tokio::task::spawn_blocking(move || {
        OpenOptions::new()
            .read(true)
            .write(true)
            .create_new(true)
            .open(&path_for_task)
            .with_path(&path_for_task)
            .map(|_| ())
    })
    .await
    .map_err(|e| {
        error!("Task panicked while creating database file: {e}");
        DatabaseError::FileCreationError {
            context: format!("Background task panicked while creating database file {db_path_str}"),
            source: Box::new(e),
        }
    })?;

    match file_creation_result {
        Ok(()) => info!("Database file created successfully."),
        Err(ref e) if e.io_error.kind() == ErrorKind::AlreadyExists => {
            info!("Database file already exists.");
        }
        Err(e) => {
            error!("Failed to create database file: {e}");
            return Err(DatabaseError::FileCreationError {
                context: format!("Failed to open database file {db_path_str}"),
                source: Box::new(e),
            });
        }
    }

    let db_url = format!("sqlite:{db_path_str}");
    // Use SqliteConnectOptions::pragma() so that per-connection PRAGMAs
    // (foreign_keys, synchronous, busy_timeout) are applied to EVERY connection
    // the pool creates, not just the first one. Without this, new pooled
    // connections revert to SQLite defaults (foreign_keys=OFF, synchronous=FULL,
    // busy_timeout=0).
    let options = SqliteConnectOptions::from_str(&db_url)
        .map_err(|e| {
            error!("Failed to parse database URL: {e}");
            DatabaseError::FileCreationError {
                context: format!("Invalid database path: {db_path_str}"),
                source: Box::new(e),
            }
        })?
        .create_if_missing(true)
        .pragma("foreign_keys", "ON")
        .pragma("synchronous", "NORMAL")
        .pragma("wal_autocheckpoint", "1000")
        .pragma("busy_timeout", "5000");

    let pool = SqlitePoolOptions::new()
        .max_connections(max_connections)
        .acquire_timeout(Duration::from_secs(5)) // Fail fast instead of blocking 30s
        .idle_timeout(Some(Duration::from_secs(60))) // Clean up idle connections
        .connect_with(options)
        .await
        .map_err(|e| {
            error!("Failed to connect to database: {e}");
            DatabaseError::SqlError(e)
        })?;

    // Enable WAL mode — this is a database-level (persistent) setting, so
    // executing it once on any connection is sufficient.
    sqlx::query("PRAGMA journal_mode=WAL")
        .execute(&pool)
        .await
        .map_err(|e| {
            error!("Failed to set WAL mode: {e}");
            DatabaseError::SqlError(e)
        })?;

    Ok(Arc::new(pool))
}

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::{NamedTempFile, TempDir};

    #[tokio::test]
    async fn test_init_db_pool_with_path_success() {
        // Test successful pool initialization
        let temp_file = NamedTempFile::new().expect("Failed to create temp file");
        let db_path = temp_file.path();

        let result = init_db_pool_with_path(db_path, 5).await;
        assert!(result.is_ok(), "Pool initialization should succeed");
        let pool = result.unwrap();
        assert!(!pool.is_closed(), "Pool should be open");
    }

    #[tokio::test]
    async fn test_init_db_pool_with_path_existing_file() {
        // Test pool initialization when file already exists
        let temp_file = NamedTempFile::new().expect("Failed to create temp file");
        let db_path = temp_file.path();

        // Create the file first
        std::fs::File::create(db_path).expect("Failed to create file");

        let result = init_db_pool_with_path(db_path, 5).await;
        assert!(
            result.is_ok(),
            "Pool initialization should succeed with existing file"
        );
    }

    #[tokio::test]
    async fn test_init_db_pool_with_path_wal_mode_enabled() {
        // Test that WAL mode is actually enabled
        let temp_file = NamedTempFile::new().expect("Failed to create temp file");
        let db_path = temp_file.path();

        let pool = init_db_pool_with_path(db_path, 5)
            .await
            .expect("Failed to initialize pool");

        // Verify WAL mode is enabled
        let result: String = sqlx::query_scalar("PRAGMA journal_mode")
            .fetch_one(pool.as_ref())
            .await
            .expect("Failed to query journal mode");

        assert_eq!(
            result.to_uppercase(),
            "WAL",
            "WAL mode should be enabled, got: {}",
            result
        );
    }

    #[tokio::test]
    async fn test_init_db_pool_with_path_foreign_keys_enabled() {
        // Test that foreign keys are actually enabled
        let temp_file = NamedTempFile::new().expect("Failed to create temp file");
        let db_path = temp_file.path();

        let pool = init_db_pool_with_path(db_path, 5)
            .await
            .expect("Failed to initialize pool");

        // Verify foreign keys are enabled
        let result: i64 = sqlx::query_scalar("PRAGMA foreign_keys")
            .fetch_one(pool.as_ref())
            .await
            .expect("Failed to query foreign keys");

        assert_eq!(result, 1, "Foreign keys should be enabled");
    }

    #[tokio::test]
    async fn test_init_db_pool_with_path_busy_timeout_enabled() {
        let temp_file = NamedTempFile::new().expect("Failed to create temp file");
        let db_path = temp_file.path();

        let pool = init_db_pool_with_path(db_path, 5)
            .await
            .expect("Failed to initialize pool");

        let result: i64 = sqlx::query_scalar("PRAGMA busy_timeout")
            .fetch_one(pool.as_ref())
            .await
            .expect("Failed to query busy_timeout");

        assert_eq!(result, 5000, "busy_timeout should be 5000 ms");
    }

    #[test]
    fn sqlite_pool_size_caps_and_floors_concurrency() {
        assert_eq!(sqlite_pool_size(1), SQLITE_POOL_CONNECTION_FLOOR);
        assert_eq!(sqlite_pool_size(2), 2);
        assert_eq!(sqlite_pool_size(30), 30);
        assert_eq!(sqlite_pool_size(32), SQLITE_POOL_CONNECTION_CAP);
        assert_eq!(sqlite_pool_size(10_000), SQLITE_POOL_CONNECTION_CAP);
    }

    /// Kills: `init_db_pool_with_path` returning `Ok` (or a non-`FileCreationError`)
    /// when a parent path is a file, or dropping the dest path from `context`.
    #[tokio::test]
    async fn test_init_db_pool_unwritable_parent_is_file_creation_error() {
        let tmp = TempDir::new().expect("tempdir");
        let blocker = tmp.path().join("not_a_directory");
        std::fs::write(&blocker, b"x").expect("write blocker");
        let dest = blocker.join("domain_status.db");
        let err = init_db_pool_with_path(&dest, 2)
            .await
            .expect_err("file-as-parent must fail");
        match err {
            DatabaseError::FileCreationError { context, .. } => {
                assert!(
                    context.contains(&dest.display().to_string()),
                    "FileCreationError context must name the dest path, got: {context}"
                );
            }
            other => panic!("expected FileCreationError, got {other:?}"),
        }
    }

    /// Kills: `AlreadyExists` guard replaced with `true` so a non-`AlreadyExists`
    /// `create_new` error (parent not writable) is swallowed into `SqlError`.
    /// Dest-is-directory is `AlreadyExists` on this platform, so it cannot kill
    /// that mutant.
    #[tokio::test]
    #[cfg(unix)]
    async fn test_init_db_pool_unwritable_dest_is_file_creation_error() {
        use std::os::unix::fs::PermissionsExt;
        let tmp = TempDir::new().expect("tempdir");
        let parent = tmp.path().join("locked");
        std::fs::create_dir(&parent).expect("parent");
        let dest = parent.join("domain_status.db");
        std::fs::set_permissions(&parent, std::fs::Permissions::from_mode(0o555))
            .expect("lock parent");
        let result = init_db_pool_with_path(&dest, 2).await;
        let _ = std::fs::set_permissions(&parent, std::fs::Permissions::from_mode(0o755));
        let err = result.expect_err("unwritable dest must fail");
        match err {
            DatabaseError::FileCreationError { context, .. } => {
                assert!(
                    context.contains(&dest.display().to_string()),
                    "FileCreationError context must name the dest path, got: {context}"
                );
            }
            other => panic!("expected FileCreationError, got {other:?}"),
        }
    }
}