diff --git a/src/filter_plugin/head.rs b/src/filter_plugin/head.rs index ff36694..6ec2ac8 100644 --- a/src/filter_plugin/head.rs +++ b/src/filter_plugin/head.rs @@ -14,6 +14,10 @@ impl HeadBytesFilter { /// # Arguments /// /// * `count` - The maximum number of bytes to read from the input. + /// + /// # Returns + /// + /// A new instance of `HeadBytesFilter`. pub fn new(count: usize) -> Self { Self { remaining: count, @@ -88,6 +92,10 @@ impl HeadLinesFilter { /// # Arguments /// /// * `count` - The maximum number of lines to read from the input. + /// + /// # Returns + /// + /// A new instance of `HeadLinesFilter`. pub fn new(count: usize) -> Self { Self { remaining: count, diff --git a/src/meta_plugin/env.rs b/src/meta_plugin/env.rs index 66c1fbf..1d1e0e6 100644 --- a/src/meta_plugin/env.rs +++ b/src/meta_plugin/env.rs @@ -8,6 +8,16 @@ pub struct EnvMetaPlugin { } impl EnvMetaPlugin { + /// Creates a new `EnvMetaPlugin` instance. + /// + /// # Arguments + /// + /// * `_options` - Optional configuration options for the plugin (unused in this implementation). + /// * `outputs` - Optional output mappings for metadata. + /// + /// # Returns + /// + /// A new instance of `EnvMetaPlugin`. pub fn new( _options: Option>, outputs: Option>, @@ -44,18 +54,38 @@ impl EnvMetaPlugin { } impl MetaPlugin for EnvMetaPlugin { + /// Returns the type of this meta plugin. + /// + /// # Returns + /// + /// `MetaPluginType::Env`. fn meta_type(&self) -> MetaPluginType { MetaPluginType::Env } + /// Checks if the plugin has been finalized. + /// + /// # Returns + /// + /// `true` if finalized, `false` otherwise. fn is_finalized(&self) -> bool { self.is_finalized } + /// Sets the finalized state of the plugin. + /// + /// # Arguments + /// + /// * `finalized` - The new finalized state. fn set_finalized(&mut self, finalized: bool) { self.is_finalized = finalized; } + /// Initializes the plugin, processing environment variables. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with environment metadata and finalized state set to `true`. fn initialize(&mut self) -> crate::meta_plugin::MetaPluginResponse { // If already finalized, don't process again if self.is_finalized { @@ -86,6 +116,15 @@ impl MetaPlugin for EnvMetaPlugin { } } + /// Updates the plugin with new data (unused in this implementation). + /// + /// # Arguments + /// + /// * `_data` - The data chunk (unused). + /// + /// # Returns + /// + /// A `MetaPluginResponse` with empty metadata and finalized state. fn update(&mut self, _data: &[u8]) -> crate::meta_plugin::MetaPluginResponse { // If already finalized, don't process more data if self.is_finalized { @@ -101,6 +140,11 @@ impl MetaPlugin for EnvMetaPlugin { } } + /// Finalizes the plugin, calling initialize if not already done. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with environment metadata if not finalized, or empty if already done. fn finalize(&mut self) -> crate::meta_plugin::MetaPluginResponse { // If not already finalized, we can call initialize if !self.is_finalized { @@ -113,20 +157,40 @@ impl MetaPlugin for EnvMetaPlugin { } } + /// Returns a reference to the outputs mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of outputs. fn outputs(&self) -> &std::collections::HashMap { &self.outputs } + /// Returns a mutable reference to the outputs mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of outputs. fn outputs_mut(&mut self) -> &mut std::collections::HashMap { &mut self.outputs } + /// Returns the default output names based on collected env vars. + /// + /// # Returns + /// + /// A vector of environment variable names. fn default_outputs(&self) -> Vec { self.env_vars.iter() .map(|(name, _)| name.clone()) .collect() } + /// Returns a reference to the options mapping (empty for this plugin). + /// + /// # Returns + /// + /// An empty `HashMap`. fn options(&self) -> &std::collections::HashMap { use once_cell::sync::Lazy; static EMPTY: Lazy> = @@ -134,16 +198,9 @@ impl MetaPlugin for EnvMetaPlugin { &EMPTY } - fn options_mut(&mut self) -> &mut std::collections::HashMap { - panic!("options_mut() not implemented for EnvMetaPlugin") - } -} -use crate::meta_plugin::register_meta_plugin; - -// Register the plugin at module initialization time -#[ctor::ctor] -fn register_env_plugin() { - register_meta_plugin(MetaPluginType::Env, |options, outputs| { - Box::new(EnvMetaPlugin::new(options, outputs)) - }); -} + /// Returns a mutable reference to the options mapping. + /// + /// # Panics + /// + /// Panics with "options_mut() not implemented for EnvMetaPlugin". + fn options_mut(&mut self) -> &mut std::collections::HashMap>, outputs: Option>, @@ -43,14 +53,29 @@ impl KeepPidMetaPlugin { } impl MetaPlugin for KeepPidMetaPlugin { + /// Checks if the plugin has been finalized. + /// + /// # Returns + /// + /// `true` if finalized, `false` otherwise. fn is_finalized(&self) -> bool { self.is_finalized } + /// Sets the finalized state of the plugin. + /// + /// # Arguments + /// + /// * `finalized` - The new finalized state. fn set_finalized(&mut self, finalized: bool) { self.is_finalized = finalized; } + /// Finalizes the plugin, processing any remaining data if needed. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with empty metadata and finalized state set to `true`. fn finalize(&mut self) -> crate::meta_plugin::MetaPluginResponse { // If already finalized, don't process again if self.is_finalized { @@ -69,6 +94,15 @@ impl MetaPlugin for KeepPidMetaPlugin { } } + /// Updates the plugin with new data chunk. + /// + /// # Arguments + /// + /// * `_data` - The data chunk (unused in this implementation). + /// + /// # Returns + /// + /// A `MetaPluginResponse` with empty metadata and finalized state. fn update(&mut self, _data: &[u8]) -> crate::meta_plugin::MetaPluginResponse { // If already finalized, don't process more data if self.is_finalized { @@ -84,54 +118,49 @@ impl MetaPlugin for KeepPidMetaPlugin { } } + /// Returns the type of this meta plugin. + /// + /// # Returns + /// + /// `MetaPluginType::KeepPid`. fn meta_type(&self) -> MetaPluginType { MetaPluginType::KeepPid } - fn initialize(&mut self) -> crate::meta_plugin::MetaPluginResponse { - // If already finalized, don't process again - if self.is_finalized { - return crate::meta_plugin::MetaPluginResponse { - metadata: Vec::new(), - is_finalized: true, - }; - } - - let mut metadata = Vec::new(); - let pid = process::id().to_string(); - - // Use process_metadata_outputs to handle output mapping - if let Some(meta_data) = crate::meta_plugin::process_metadata_outputs( - "keep_pid", - serde_yaml::Value::String(pid), - &self.outputs - ) { - metadata.push(meta_data); - } - - // Mark as finalized since this plugin only needs to run once - self.is_finalized = true; - - crate::meta_plugin::MetaPluginResponse { - metadata, - is_finalized: true, - } - } - + /// Returns a reference to the outputs mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of outputs. fn outputs(&self) -> &std::collections::HashMap { &self.outputs } + /// Returns a mutable reference to the outputs mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of outputs. fn outputs_mut(&mut self) -> &mut std::collections::HashMap { &mut self.outputs } + /// Returns a reference to the options mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of options. fn options(&self) -> &std::collections::HashMap { &self.options } + /// Returns a mutable reference to the options mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of options. fn options_mut(&mut self) -> &mut std::collections::HashMap { &mut self.options } diff --git a/src/meta_plugin/mod.rs b/src/meta_plugin/mod.rs index 9ede23c..1fdb2b7 100644 --- a/src/meta_plugin/mod.rs +++ b/src/meta_plugin/mod.rs @@ -34,50 +34,88 @@ pub use shell_pid::ShellPidMetaPlugin; pub use keep_pid::KeepPidMetaPlugin; pub use env::EnvMetaPlugin; -/// Represents metadata to be stored +/// Represents metadata to be stored. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct MetaData { + /// The name of the metadata field. pub name: String, + /// The value of the metadata field. pub value: String, } -/// Response from meta plugin operations +/// Response from meta plugin operations. #[derive(Debug, Default, Clone, Serialize, Deserialize)] pub struct MetaPluginResponse { + /// The generated metadata items. pub metadata: Vec, + /// Indicates if the plugin has finished processing. pub is_finalized: bool, } -/// Base implementation for meta plugins to reduce boilerplate +/// Base implementation for meta plugins to reduce boilerplate. #[derive(Debug, Clone, Default)] pub struct BaseMetaPlugin { + /// Output mappings for metadata. pub outputs: std::collections::HashMap, + /// Configuration options for the plugin. pub options: std::collections::HashMap, + /// Whether the plugin is finalized. pub is_finalized: bool, } impl BaseMetaPlugin { + /// Creates a new `BaseMetaPlugin`. + /// + /// # Returns + /// + /// A new instance of `BaseMetaPlugin`. pub fn new() -> Self { Self::default() } + /// Returns a reference to the outputs mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of outputs. pub fn outputs(&self) -> &std::collections::HashMap { &self.outputs } + /// Returns a mutable reference to the outputs mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of outputs. pub fn outputs_mut(&mut self) -> &mut std::collections::HashMap { &mut self.outputs } + /// Returns a reference to the options mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of options. pub fn options(&self) -> &std::collections::HashMap { &self.options } + /// Returns a mutable reference to the options mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of options. pub fn options_mut(&mut self) -> &mut std::collections::HashMap { &mut self.options } - /// Helper function to initialize plugin options and outputs + /// Helper function to initialize plugin options and outputs. + /// + /// # Arguments + /// + /// * `default_outputs` - Slice of default output names. + /// * `options` - Optional user-provided options. + /// * `outputs` - Optional user-provided outputs. pub fn initialize_plugin( &mut self, default_outputs: &[&str], @@ -100,24 +138,49 @@ impl BaseMetaPlugin { } impl MetaPlugin for BaseMetaPlugin { + /// Returns the type of this meta plugin. + /// + /// # Returns + /// + /// `MetaPluginType::Text` (default for base). fn meta_type(&self) -> MetaPluginType { // This is a base implementation, so we need to return something // This might not be used, but we need to satisfy the trait MetaPluginType::Text } + /// Returns a reference to the outputs mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of outputs. fn outputs(&self) -> &std::collections::HashMap { &self.outputs } + /// Returns a mutable reference to the outputs mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of outputs. fn outputs_mut(&mut self) -> &mut std::collections::HashMap { &mut self.outputs } + /// Returns a reference to the options mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of options. fn options(&self) -> &std::collections::HashMap { &self.options } + /// Returns a mutable reference to the options mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of options. fn options_mut(&mut self) -> &mut std::collections::HashMap { &mut self.options } @@ -142,8 +205,17 @@ pub enum MetaPluginType { Env, } -/// Central function to handle metadata output with name mapping -/// outputs: HashMap where key is internal name, value is either custom name or "false" to disable +/// Central function to handle metadata output with name mapping. +/// +/// # Arguments +/// +/// * `internal_name` - The internal name of the metadata. +/// * `value` - The value to process. +/// * `outputs` - The outputs mapping. +/// +/// # Returns +/// +/// An optional `MetaData` if the output is enabled, `None` if disabled. pub fn process_metadata_outputs(internal_name: &str, value: serde_yaml::Value, outputs: &std::collections::HashMap) -> Option { // Check if this output is disabled if let Some(mapping) = outputs.get(internal_name) { @@ -198,25 +270,56 @@ pub fn process_metadata_outputs(internal_name: &str, value: serde_yaml::Value, o } pub trait MetaPlugin where Self: 'static { + /// Returns the type of this meta plugin. + /// + /// # Returns + /// + /// The `MetaPluginType` enum variant for this plugin. fn meta_type(&self) -> MetaPluginType; + /// Checks if the plugin is supported on the current system. + /// + /// # Returns + /// + /// `true` if supported, `false` otherwise. fn is_supported(&self) -> bool { true } + /// Checks if the plugin is internal (built-in). + /// + /// # Returns + /// + /// `true` if internal, `false` otherwise. fn is_internal(&self) -> bool { true } - // Check if the plugin is already finalized + /// Checks if the plugin is already finalized. + /// + /// # Returns + /// + /// `true` if finalized, `false` otherwise. fn is_finalized(&self) -> bool { false } - // Set the finalized state (only for plugins that can track this) + /// Sets the finalized state (only for plugins that can track this). + /// + /// # Arguments + /// + /// * `_finalized` - The new finalized state (unused in default). fn set_finalized(&mut self, _finalized: bool) {} - // Update the meta plugin with new data + /// Updates the meta plugin with new data. + /// + /// # Arguments + /// + /// * `_data` - The data chunk to process (unused in default). + /// + /// # Returns + /// + /// A `MetaPluginResponse` with empty metadata and `is_finalized` set to `false`. fn update(&mut self, _data: &[u8]) -> MetaPluginResponse { // Default implementation does nothing MetaPluginResponse { @@ -225,6 +328,11 @@ pub trait MetaPlugin where Self: 'static { } } + /// Finalizes the plugin. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with empty metadata and `is_finalized` set to `true`. fn finalize(&mut self) -> MetaPluginResponse { // Default implementation does nothing MetaPluginResponse { @@ -233,12 +341,20 @@ pub trait MetaPlugin where Self: 'static { } } - // Get program information for display in status + /// Gets program information for display in status. + /// + /// # Returns + /// + /// An optional tuple of program name and arguments, or `None`. fn program_info(&self) -> Option<(&str, Vec<&str>)> { None } - // Initialize the plugin + /// Initializes the plugin. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with empty metadata and `is_finalized` set to `false`. fn initialize(&mut self) -> MetaPluginResponse { // Default implementation does nothing MetaPluginResponse { @@ -247,7 +363,11 @@ pub trait MetaPlugin where Self: 'static { } } - // Access to outputs mapping with default implementation + /// Returns a reference to the outputs mapping. + /// + /// # Returns + /// + /// An empty `HashMap` (default implementation). fn outputs(&self) -> &std::collections::HashMap { use once_cell::sync::Lazy; static EMPTY: Lazy> = @@ -255,11 +375,20 @@ pub trait MetaPlugin where Self: 'static { &EMPTY } + /// Returns a mutable reference to the outputs mapping. + /// + /// # Panics + /// + /// Panics with "outputs_mut() not implemented for this plugin". fn outputs_mut(&mut self) -> &mut std::collections::HashMap { panic!("outputs_mut() not implemented for this plugin") } - // Access to options mapping with default implementation + /// Returns a reference to the options mapping. + /// + /// # Returns + /// + /// An empty `HashMap` (default implementation). fn options(&self) -> &std::collections::HashMap { use once_cell::sync::Lazy; static EMPTY: Lazy> = @@ -267,11 +396,20 @@ pub trait MetaPlugin where Self: 'static { &EMPTY } + /// Returns a mutable reference to the options mapping. + /// + /// # Panics + /// + /// Panics with "options_mut() not implemented for this plugin". fn options_mut(&mut self) -> &mut std::collections::HashMap { panic!("options_mut() not implemented for this plugin") } - // Get the default output names this plugin can produce + /// Gets the default output names this plugin can produce. + /// + /// # Returns + /// + /// A vector containing the meta type as a string (default). fn default_outputs(&self) -> Vec { // Default implementation returns the meta type as a string vec![self.meta_type().to_string()] @@ -279,17 +417,26 @@ pub trait MetaPlugin where Self: 'static { - // Method to downcast to concrete type (for checking finalization state) + /// Method to downcast to concrete type (for checking finalization state). + /// + /// # Returns + /// + /// A mutable reference to `self` as `dyn Any`. fn as_any_mut(&mut self) -> &mut dyn std::any::Any where Self: Sized { self } } -/// Global registry for meta plugins +/// Global registry for meta plugins. static META_PLUGIN_REGISTRY: Lazy>, Option>) -> Box>>> = Lazy::new(|| Mutex::new(HashMap::new())); -/// Register a meta plugin with the global registry +/// Register a meta plugin with the global registry. +/// +/// # Arguments +/// +/// * `meta_plugin_type` - The type of the meta plugin to register. +/// * `constructor` - The constructor function for creating plugin instances. pub fn register_meta_plugin( meta_plugin_type: MetaPluginType, constructor: fn(Option>, Option>) -> Box diff --git a/src/meta_plugin/read_rate.rs b/src/meta_plugin/read_rate.rs index 0570806..dceeefb 100644 --- a/src/meta_plugin/read_rate.rs +++ b/src/meta_plugin/read_rate.rs @@ -12,6 +12,16 @@ pub struct ReadRateMetaPlugin { } impl ReadRateMetaPlugin { + /// Creates a new `ReadRateMetaPlugin` instance. + /// + /// # Arguments + /// + /// * `_options` - Optional configuration options for the plugin (unused in this implementation). + /// * `outputs` - Optional output mappings for metadata. + /// + /// # Returns + /// + /// A new instance of `ReadRateMetaPlugin`. pub fn new( _options: Option>, outputs: Option>, @@ -48,14 +58,29 @@ impl ReadRateMetaPlugin { } impl MetaPlugin for ReadRateMetaPlugin { + /// Checks if the plugin has been finalized. + /// + /// # Returns + /// + /// `true` if finalized, `false` otherwise. fn is_finalized(&self) -> bool { self.is_finalized } + /// Sets the finalized state of the plugin. + /// + /// # Arguments + /// + /// * `finalized` - The new finalized state. fn set_finalized(&mut self, finalized: bool) { self.is_finalized = finalized; } + /// Finalizes the plugin, calculating the read rate. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with read rate metadata and finalized state set to `true`. fn finalize(&mut self) -> crate::meta_plugin::MetaPluginResponse { // If already finalized, don't process again if self.is_finalized { @@ -94,6 +119,15 @@ impl MetaPlugin for ReadRateMetaPlugin { } } + /// Updates the plugin with new data, accumulating bytes read. + /// + /// # Arguments + /// + /// * `data` - The data chunk to process. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with empty metadata and finalized state set to `false`. fn update(&mut self, data: &[u8]) -> crate::meta_plugin::MetaPluginResponse { // If already finalized, don't process more data if self.is_finalized { @@ -113,24 +147,49 @@ impl MetaPlugin for ReadRateMetaPlugin { } } + /// Returns the type of this meta plugin. + /// + /// # Returns + /// + /// `MetaPluginType::ReadRate`. fn meta_type(&self) -> MetaPluginType { MetaPluginType::ReadRate } + /// Returns a reference to the outputs mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of outputs. fn outputs(&self) -> &std::collections::HashMap { &self.outputs } + /// Returns a mutable reference to the outputs mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of outputs. fn outputs_mut(&mut self) -> &mut std::collections::HashMap { &mut self.outputs } + /// Returns a reference to the options mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of options. fn options(&self) -> &std::collections::HashMap { &self.options } + /// Returns a mutable reference to the options mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of options. fn options_mut(&mut self) -> &mut std::collections::HashMap { &mut self.options } diff --git a/src/meta_plugin/user.rs b/src/meta_plugin/user.rs index a93ec06..419ec6f 100644 --- a/src/meta_plugin/user.rs +++ b/src/meta_plugin/user.rs @@ -6,6 +6,16 @@ pub struct UserMetaPlugin { } impl UserMetaPlugin { + /// Creates a new `UserMetaPlugin` instance. + /// + /// # Arguments + /// + /// * `options` - Optional configuration options for the plugin. + /// * `outputs` - Optional output mappings for metadata. + /// + /// # Returns + /// + /// A new instance of `UserMetaPlugin`. pub fn new( options: Option>, outputs: Option>, @@ -25,11 +35,21 @@ impl UserMetaPlugin { } + /// Gets the current username. + /// + /// # Returns + /// + /// An `Option` with the username, or `None` if unavailable. fn get_current_username() -> Option { uzers::get_user_by_uid(uzers::get_current_uid()) .map(|user| user.name().to_string_lossy().to_string()) } + /// Gets the current group name. + /// + /// # Returns + /// + /// An `Option` with the group name, or `None` if unavailable. fn get_current_groupname() -> Option { uzers::get_group_by_gid(uzers::get_current_gid()) .map(|group| group.name().to_string_lossy().to_string()) @@ -37,6 +57,11 @@ impl UserMetaPlugin { } impl MetaPlugin for UserMetaPlugin { + /// Initializes the plugin, capturing user information. + /// + /// # Returns + /// + /// A `MetaPluginResponse` with user metadata and `is_finalized` set to `true`. fn initialize(&mut self) -> crate::meta_plugin::MetaPluginResponse { let mut metadata = Vec::new(); @@ -70,27 +95,57 @@ impl MetaPlugin for UserMetaPlugin { } } + /// Returns the type of this meta plugin. + /// + /// # Returns + /// + /// `MetaPluginType::User`. fn meta_type(&self) -> MetaPluginType { MetaPluginType::User } + /// Returns a reference to the outputs mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of outputs. fn outputs(&self) -> &std::collections::HashMap { self.base.outputs() } + /// Returns a mutable reference to the outputs mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of outputs. fn outputs_mut(&mut self) -> &mut std::collections::HashMap { self.base.outputs_mut() } + /// Returns the default output names. + /// + /// # Returns + /// + /// A vector of default output names. fn default_outputs(&self) -> Vec { vec!["user_uid".to_string(), "user_gid".to_string(), "user_name".to_string(), "user_group".to_string()] } + /// Returns a reference to the options mapping. + /// + /// # Returns + /// + /// A reference to the `HashMap` of options. fn options(&self) -> &std::collections::HashMap { self.base.options() } + /// Returns a mutable reference to the options mapping. + /// + /// # Returns + /// + /// A mutable reference to the `HashMap` of options. fn options_mut(&mut self) -> &mut std::collections::HashMap { self.base.options_mut() }