diff --git a/PLAN.md b/PLAN.md index 643f085..a8e7702 100644 --- a/PLAN.md +++ b/PLAN.md @@ -245,15 +245,15 @@ Private helpers (e.g., internal `fn` without `pub`) are not flagged, as they don 43. **src/services/error.rs** [DONE] - `CoreError` enum: Partial variants. -44. **src/services/compression_service.rs** +44. **src/services/compression_service.rs** [DONE] - `CompressionService` struct: Partial. - Methods (`new`, `get_item_content`, `stream_item_content`): Partial. -45. **src/services/status_service.rs** +45. **src/services/status_service.rs** [DONE] - `StatusService` struct: Partial. - `generate_status()` method: Partial. -46. **src/meta_plugin/exec.rs** +46. **src/meta_plugin/exec.rs** [DONE] - `MetaPluginExec` struct: Partial. - `new()` function: Partial. - Impl `MetaPlugin` methods: Partial. diff --git a/src/meta_plugin/exec.rs b/src/meta_plugin/exec.rs index 4c5a919..6fc0cf3 100644 --- a/src/meta_plugin/exec.rs +++ b/src/meta_plugin/exec.rs @@ -5,6 +5,15 @@ use which::which; use crate::meta_plugin::{MetaPlugin, MetaPluginResponse, MetaPluginType}; +/// External program execution meta plugin. +/// +/// This plugin executes a specified external command during item save operations, +/// capturing its output as metadata. It supports piping input data to the command's stdin +/// and processing stdout. Useful for dynamic metadata generation via shell commands. +/// +/// # Examples +/// +/// Configured via options like `command: "date"`, the plugin runs `date` and captures output as metadata. pub struct MetaPluginExec { pub program: String, pub args: Vec, @@ -18,6 +27,9 @@ pub struct MetaPluginExec { } // Manual Debug implementation because Box doesn't implement Debug +/// Custom Debug implementation for MetaPluginExec. +/// +/// Obfuscates the writer field since Box does not implement Debug. impl std::fmt::Debug for MetaPluginExec { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("MetaPluginExec") @@ -36,6 +48,30 @@ impl std::fmt::Debug for MetaPluginExec { impl MetaPluginExec { + /// Creates a new MetaPluginExec instance. + /// + /// Validates the program availability using `which` and initializes outputs and options. + /// The meta_name determines the default output key for captured command output. + /// + /// # Arguments + /// + /// * `program` - The executable name or path to run. + /// * `args` - Slice of arguments to pass to the program. + /// * `meta_name` - Name for the metadata output key. + /// * `split_whitespace` - If true, takes the first whitespace-separated word from output; otherwise, trims full output. + /// * `_options` - Optional configuration options (currently unused beyond passing through). + /// * `outputs` - Optional output mappings to override defaults. + /// + /// # Returns + /// + /// * `MetaPluginExec` - New plugin instance, with `supported` set based on program availability. + /// + /// # Examples + /// + /// ``` + /// let plugin = MetaPluginExec::new("date", vec![], "timestamp", false, None, None); + /// assert!(plugin.supported); // If 'date' is available + /// ``` pub fn new( program: &str, args: Vec<&str>, @@ -80,14 +116,45 @@ impl MetaPluginExec { } impl MetaPlugin for MetaPluginExec { + /// Checks if the external program is available on the system. + /// + /// # Returns + /// + /// * `bool` - True if the program was found via `which`. fn is_supported(&self) -> bool { self.supported } + /// Indicates if this is an internal (built-in) plugin. + /// + /// External exec plugins are always non-internal. + /// + /// # Returns + /// + /// * `false` - Always false for this plugin type. fn is_internal(&self) -> bool { false } + /// Initializes the plugin by spawning the external process. + /// + /// Sets up piped stdin/stdout/stderr for the command. Does not finalize yet. + /// + /// # Returns + /// + /// * `MetaPluginResponse` - Empty metadata, not finalized. + /// + /// # Errors + /// + /// If spawn fails, returns finalized response with no metadata (logs error). + /// + /// # Examples + /// + /// ``` + /// let mut plugin = MetaPluginExec::new("echo", vec!["hello"], "output", false, None, None); + /// let response = plugin.initialize(); + /// assert!(!response.is_finalized); + /// ``` fn initialize(&mut self) -> MetaPluginResponse { debug!("META: Initializing program plugin: {:?}", self); @@ -123,6 +190,24 @@ impl MetaPlugin for MetaPluginExec { } } + /// Finalizes the plugin by waiting for the process to complete and capturing output. + /// + /// Processes stdout based on split_whitespace option, adds to metadata if successful. + /// Logs stderr and status on failure but does not propagate as error. + /// + /// # Returns + /// + /// * `MetaPluginResponse` - Metadata from output (if any), always finalized. + /// + /// # Examples + /// + /// ``` + /// let response = plugin.finalize(); + /// assert!(response.is_finalized); + /// if let Some(meta) = response.metadata.first() { + /// // Contains captured output + /// } + /// ``` fn finalize(&mut self) -> MetaPluginResponse { debug!("META: Finalizing program plugin"); let mut metadata = Vec::new(); @@ -180,6 +265,18 @@ impl MetaPlugin for MetaPluginExec { } } + /// Updates the plugin by writing data to the process's stdin. + /// + /// Pipes incoming data (e.g., item content) to the command for processing. + /// Logs write errors but continues. + /// + /// # Arguments + /// + /// * `data` - Byte slice to write to stdin. + /// + /// # Returns + /// + /// * `MetaPluginResponse` - Empty metadata, not finalized. fn update(&mut self, data: &[u8]) -> MetaPluginResponse { if let Some(ref mut writer) = self.writer { if let Err(e) = writer.write_all(data) { @@ -192,10 +289,22 @@ impl MetaPlugin for MetaPluginExec { } } + /// Returns the type of this meta plugin. + /// + /// # Returns + /// + /// * `MetaPluginType::Exec` - The exec plugin type. fn meta_type(&self) -> MetaPluginType { MetaPluginType::Exec } + /// Provides information about the program and its arguments. + /// + /// Only returns data if the program is supported. + /// + /// # Returns + /// + /// * `Option<(&str, Vec<&str>)>` - Tuple of program path and arg slices, or None. fn program_info(&self) -> Option<(&str, Vec<&str>)> { if self.supported { Some((&self.program, self.args.iter().map(|s| s.as_str()).collect())) @@ -204,27 +313,57 @@ impl MetaPlugin for MetaPluginExec { } } + /// Returns an immutable reference to the plugin's outputs. + /// + /// # Returns + /// + /// * `&HashMap` - The outputs map. fn outputs(&self) -> &std::collections::HashMap { &self.outputs } + /// Returns a mutable reference to the plugin's outputs. + /// + /// # Returns + /// + /// * `&mut HashMap` - Mutable outputs map. fn outputs_mut(&mut self) -> &mut std::collections::HashMap { &mut self.outputs } + /// Returns the default output keys for this plugin. + /// + /// # Returns + /// + /// * `Vec` - Vector with the exec type string. fn default_outputs(&self) -> Vec { vec![self.meta_type().to_string()] } + /// Returns an immutable reference to the plugin's options. + /// + /// # Returns + /// + /// * `&HashMap` - The options map. fn options(&self) -> &std::collections::HashMap { &self.options } + /// Returns a mutable reference to the plugin's options. + /// + /// # Returns + /// + /// * `&mut HashMap` - Mutable options map. fn options_mut(&mut self) -> &mut std::collections::HashMap { &mut self.options } } +/// Registers the exec meta plugin with the global registry. +/// +/// This constructor function is called at module load time using ctor crate. +/// It parses "command" option for program/args, "split_whitespace" for output processing, +/// and "name" for metadata key. Falls back to defaults if missing. use crate::meta_plugin::register_meta_plugin; // Register the plugin at module initialization time diff --git a/src/services/compression_service.rs b/src/services/compression_service.rs index 462a50c..17d677c 100644 --- a/src/services/compression_service.rs +++ b/src/services/compression_service.rs @@ -5,6 +5,18 @@ use std::path::PathBuf; use std::str::FromStr; use anyhow::anyhow; +//// Service for handling compression and decompression of item content. +/// +/// Provides methods to read compressed item files either fully into memory +/// or as streaming readers. Supports various compression types via engines. +/// This service abstracts the underlying compression engines for consistent access. +/// +/// # Examples +/// +/// ``` +/// let service = CompressionService::new(); +/// let content = service.get_item_content(path, "gzip")?; +/// ``` pub struct CompressionService; /// Service for handling compression and decompression of item content. @@ -22,9 +34,11 @@ pub struct CompressionService; impl CompressionService { /// Creates a new CompressionService instance. /// + /// This is a simple constructor; no initialization is required beyond the static methods. + /// /// # Returns /// - /// A new `CompressionService`. + /// * `CompressionService` - A new instance of the service. /// /// # Examples /// @@ -37,19 +51,22 @@ impl CompressionService { /// Reads and decompresses the full content of an item file into memory. /// + /// Loads the entire decompressed content as a byte vector. Suitable for small to medium files. + /// /// # Arguments /// - /// * `item_path` - Path to the compressed item file. - /// * `compression` - Compression type string (e.g., "gzip"). + /// * `item_path` - Path to the compressed item file on disk. + /// * `compression` - Compression type as string (e.g., "gzip", "lz4"); case-insensitive. /// /// # Returns /// - /// * `Result, CoreError>` - Decompressed content bytes. + /// * `Ok(Vec)` - The full decompressed content bytes. + /// * `Err(CoreError)` - On failure (see errors). /// /// # Errors /// - /// * `CoreError::Compression(...)` - If compression type invalid. - /// * `CoreError::Other(...)` - If file open or read fails. + /// * `CoreError::Compression(String)` - If the compression type string is invalid. + /// * `CoreError::Other(anyhow::Error)` - If the file cannot be opened, the engine fails, or reading encounters an I/O error. /// /// # Examples /// @@ -72,22 +89,23 @@ impl CompressionService { /// Opens a streaming reader for decompressing item content. /// - /// For Send compatibility, reads full content into memory and returns a Cursor. - /// Note: Not suitable for very large files due to memory usage. + /// Due to Send requirements in async contexts, this loads the full content into a Cursor. + /// Warning: For very large files, this consumes significant memory; consider alternatives for streaming without loading all data. /// /// # Arguments /// - /// * `item_path` - Path to the compressed item file. - /// * `compression` - Compression type string. + /// * `item_path` - Path to the compressed item file on disk. + /// * `compression` - Compression type as string (e.g., "gzip", "lz4"); case-insensitive. /// /// # Returns /// - /// * `Result, CoreError>` - Boxed streaming reader. + /// * `Ok(Box)` - A boxed reader that can be used for streaming decompressed data. + /// * `Err(CoreError)` - On failure (see errors). /// /// # Errors /// - /// * `CoreError::Compression(...)` - If compression type invalid. - /// * `CoreError::Other(...)` - If file open or read fails. + /// * `CoreError::Compression(String)` - If the compression type string is invalid. + /// * `CoreError::Other(anyhow::Error)` - If the file cannot be opened, the engine fails, or reading encounters an I/O error. /// /// # Examples /// diff --git a/src/services/status_service.rs b/src/services/status_service.rs index 71697ab..d6ce135 100644 --- a/src/services/status_service.rs +++ b/src/services/status_service.rs @@ -13,14 +13,23 @@ use std::str::FromStr; /// configuration, storage paths, compression engines, metadata plugins, /// and filter plugins. It provides a unified interface for status reporting /// used by both CLI and server modes. +/// +/// # Examples +/// +/// ``` +/// let service = StatusService::new(); +/// let status = service.generate_status(&mut cmd, &settings, data_path, db_path); +/// ``` pub struct StatusService; impl StatusService { /// Creates a new `StatusService` instance. /// + /// No specific initialization is needed; it's a stateless service. + /// /// # Returns /// - /// A new `StatusService` instance. + /// * `StatusService` - A new instance. /// /// # Examples /// @@ -35,23 +44,28 @@ impl StatusService { /// /// Collects data about paths, compression engines, available and configured /// meta plugins, and filter plugins. Uses the provided settings to determine - /// enabled components. + /// enabled components. Handles error reporting via Clap if needed. /// /// # Arguments /// - /// * `cmd` - Mutable reference to the Clap command for error reporting. - /// * `settings` - Application settings containing configuration. - /// * `data_path` - Path to the data storage directory. + /// * `cmd` - Mutable reference to the Clap command for error reporting (e.g., invalid plugins). + /// * `settings` - Application settings containing configuration details like enabled plugins. + /// * `data_path` - Path to the data storage directory for item files. /// * `db_path` - Path to the SQLite database file. /// /// # Returns /// - /// `StatusInfo` - Structured status information. + /// * `StatusInfo` - A structured object containing all status details, including paths, plugins, and config. + /// + /// # Errors + /// + /// Exits via Clap error if invalid meta plugin types are configured in settings. /// /// # Examples /// /// ``` /// let status = service.generate_status(&mut cmd, &settings, data_path, db_path); + /// assert!(!status.filter_plugins.is_empty()); /// ``` pub fn generate_status( &self, @@ -100,9 +114,11 @@ impl StatusService { impl Default for StatusService { /// Returns the default `StatusService` instance. /// + /// Delegates to `new()` for consistency. + /// /// # Returns /// - /// A new `StatusService`. + /// * `StatusService` - A new instance. fn default() -> Self { Self::new() }