aria2-core 0.3.0

aria2-rust core download engine: multi-protocol segmented downloads, rate limiting, configuration, session persistence, and BitTorrent seeding
Documentation
//! File I/O operations for session persistence
//!
//! Provides async functions for loading and saving session files
//! using atomic write patterns for data integrity.

use std::path::Path;
use std::sync::Arc;

use crate::error::{Aria2Error, Result};
use crate::request::request_group::RequestGroup;

use super::SessionEntry;
use super::deserialization::deserialize;
use super::serialize::serialize_groups;

/// Loads and deserializes session entries from a file
///
/// Reads the specified session file and parses its contents into
/// a vector of SessionEntry objects using atomic read operations.
///
/// # Arguments
///
/// * `path` - Path to the session file to load
///
/// # Returns
///
/// Result containing a Vec of SessionEntry objects or an IO error
///
/// # Errors
///
/// Returns an error if:
/// - The file cannot be read (permission denied, not found, etc.)
/// - The file contains invalid UTF-8
///
/// # Example
///
/// ```rust,no_run
/// use aria2_core::session::session_serializer::load_from_file;
/// use std::path::Path;
///
/// #[tokio::main]
/// async fn main() {
///     let path = Path::new("aria2.session");
///     let _entries = load_from_file(path).await.unwrap();
/// }
/// ```
pub async fn load_from_file(path: &Path) -> Result<Vec<SessionEntry>> {
    let content = tokio::fs::read_to_string(path).await.map_err(|e| {
        Aria2Error::Io(format!(
            "Failed to read session file {}: {}",
            path.display(),
            e
        ))
    })?;

    deserialize(&content)
}

/// Saves multiple RequestGroups to a session file using atomic write
///
/// Serializes all provided RequestGroups and writes them to the specified
/// file using an atomic write pattern (write to temp file + rename).
/// This ensures session file integrity even if the process crashes during write.
///
/// # Arguments
///
/// * `path` - Target path for the session file
/// * `groups` - Slice of Arc<std::sync::RwLock<RequestGroup>> references to serialize
///
/// # Returns
///
/// Result indicating success or an IO error
///
/// # Atomic Write Strategy
///
/// 1. Serialize all groups to memory
/// 2. Write to `{path}.sess.tmp` temporary file
/// 3. Rename temp file to target path (atomic on most filesystems)
///
/// # Errors
///
/// Returns an error if:
/// - Temporary file cannot be written
/// - Rename operation fails
///
/// # Example
///
/// ```rust,no_run
/// use aria2_core::session::session_serializer::save_to_file;
/// use std::path::Path;
/// use std::sync::Arc;
/// use std::sync::RwLock;
///
/// #[tokio::main]
/// async fn main() {
///     let path = Path::new("aria2.session");
///     let groups: Vec<Arc<RwLock<aria2_core::request::request_group::RequestGroup>>> = vec![];
///     save_to_file(path, &groups).await.unwrap();
/// }
/// ```
pub async fn save_to_file(
    path: &Path,
    groups: &[Arc<std::sync::RwLock<RequestGroup>>],
) -> Result<()> {
    let content = serialize_groups(groups)?;
    let tmp_path = path.with_extension("sess.tmp");

    tokio::fs::write(&tmp_path, &content).await.map_err(|e| {
        Aria2Error::Io(format!(
            "Failed to write session temp file {}: {}",
            tmp_path.display(),
            e
        ))
    })?;

    tokio::fs::rename(&tmp_path, path).await.map_err(|e| {
        Aria2Error::Io(format!(
            "Failed to rename session file {}: {}",
            path.display(),
            e
        ))
    })
}

/// Saves pre-serialized SessionEntry list directly to file (bypasses RequestGroup conversion)
///
/// Useful when you already have SessionEntry objects and want to save them
/// without converting through RequestGroup. Uses atomic write pattern for safety.
///
/// # Arguments
///
/// * `path` - Target path for the session file
/// * `entries` - Slice of SessionEntry objects to serialize and save
///
/// # Returns
///
/// Result indicating success or an IO error
///
/// # When to Use
///
/// - Testing session persistence without full RequestGroup setup
/// - Migrating sessions from another source
/// - Manual session manipulation tools
///
/// # Atomic Write Strategy
///
/// Same as [`save_to_file()`]: write to `.sess.tmp` then rename atomically.
///
/// # Example
///
/// ```rust,no_run
/// use aria2_core::session::session_entry::SessionEntry;
/// use aria2_core::session::session_serializer::save_to_file_with_entries;
/// use std::path::Path;
///
/// #[tokio::main]
/// async fn main() {
///     let path = Path::new("custom.session");
///     let entries = vec![
///         SessionEntry::new(1, vec!["http://example.com/f".to_string()]),
///     ];
///     save_to_file_with_entries(path, &entries).await.unwrap();
/// }
/// ```
pub async fn save_to_file_with_entries(path: &Path, entries: &[SessionEntry]) -> Result<()> {
    let mut content = String::new();
    for entry in entries {
        content.push_str(&entry.serialize());
        content.push('\n');
    }

    let tmp_path = path.with_extension("sess.tmp");

    tokio::fs::write(&tmp_path, &content).await.map_err(|e| {
        Aria2Error::Io(format!(
            "Failed to write session temp file {}: {}",
            tmp_path.display(),
            e
        ))
    })?;

    tokio::fs::rename(&tmp_path, path).await.map_err(|e| {
        Aria2Error::Io(format!(
            "Failed to rename session file {}: {}",
            path.display(),
            e
        ))
    })
}