asp/keep
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Enhance Rustdoc for CompressionService, StatusService, and MetaPluginExec

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-09-10 15:29:56 -03:00
parent 9f48d7980b
commit 0e036e3789
4 changed files with 196 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
src/meta_plugin/exec.rs
View File

@@ -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<String>,
@@ -18,6 +27,9 @@ pub struct MetaPluginExec {
}
// Manual Debug implementation because Box<dyn Write> doesn't implement Debug
/// Custom Debug implementation for MetaPluginExec.
///
/// Obfuscates the writer field since Box<dyn Write> 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<String, serde_yaml::Value>` - The outputs map.
fn outputs(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
&self.outputs
}
/// Returns a mutable reference to the plugin's outputs.
///
/// # Returns
///
/// * `&mut HashMap<String, serde_yaml::Value>` - Mutable outputs map.
fn outputs_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
&mut self.outputs
}
/// Returns the default output keys for this plugin.
///
/// # Returns
///
/// * `Vec<String>` - Vector with the exec type string.
fn default_outputs(&self) -> Vec<String> {
vec![self.meta_type().to_string()]
}
/// Returns an immutable reference to the plugin's options.
///
/// # Returns
///
/// * `&HashMap<String, serde_yaml::Value>` - The options map.
fn options(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
&self.options
}
/// Returns a mutable reference to the plugin's options.
///
/// # Returns
///
/// * `&mut HashMap<String, serde_yaml::Value>` - Mutable options map.
fn options_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
&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

44
src/services/compression_service.rs
View File

@@ -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<Vec<u8>, CoreError>` - Decompressed content bytes.
/// * `Ok(Vec<u8>)` - 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<Box<dyn Read + Send>, CoreError>` - Boxed streaming reader.
/// * `Ok(Box<dyn Read + Send>)` - 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
///

30
src/services/status_service.rs
View File

@@ -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()
}