diff --git a/src/filter_plugin/mod.rs b/src/filter_plugin/mod.rs index 9bcd944..abbd133 100644 --- a/src/filter_plugin/mod.rs +++ b/src/filter_plugin/mod.rs @@ -2,6 +2,20 @@ use std::io::{Result, Read, Write}; use std::str::FromStr; use strum::EnumString; +/// Filter plugin module for processing input streams. +/// +/// This module defines the `FilterPlugin` trait and `FilterChain` for chaining filters, +/// along with parsing utilities for filter strings. Filters can process data like head/tail, +/// grep, etc. +/// +/// # Usage +/// +/// Parse a filter string and apply to a reader: +/// +/// ``` +/// let chain = parse_filter_string("head_lines(10)|grep(pattern=error)")?; +/// chain.filter(&mut reader, &mut writer)?; +/// ``` pub mod head; pub mod tail; pub mod skip; @@ -18,6 +32,14 @@ pub use grep::GrepFilter; pub use strip_ansi::StripAnsiFilter; /// Represents an option for a filter plugin. +/// +/// Defines a configurable parameter for filters, with name, default, and required flag. +/// +/// # Fields +/// +/// * `name` - Option name. +/// * `default` - Optional default value. +/// * `required` - If true, must be provided. #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, utoipa::ToSchema)] pub struct FilterOption { pub name: String, @@ -27,6 +49,25 @@ pub struct FilterOption { } /// Trait for filter plugins that process input streams. +/// +/// Implement this trait to create a filter that reads from an input stream and writes filtered output. +/// +/// # Required Methods +/// +/// * `filter` - Process the stream. +/// * `clone_box` - For cloning dynamic instances. +/// * `options` - Describe configurable options. +/// +/// # Examples +/// +/// ``` +/// impl FilterPlugin for MyFilter { +/// fn filter(&mut self, reader: Box<&mut dyn Read>, writer: Box<&mut dyn Write>) -> Result<()> { +/// // Implementation +/// } +/// // ... +/// } +/// ``` pub trait FilterPlugin: Send { /// Processes the input stream and writes the filtered output. /// @@ -54,6 +95,14 @@ pub trait FilterPlugin: Send { } /// Enum representing the different types of filters. +/// +/// Used for parsing and instantiating specific filter plugins. +/// +/// # Variants +/// +/// * `HeadBytes` - Head by bytes. +/// * `HeadLines` - Head by lines. +/// * ... etc. #[derive(Debug, EnumString, strum::VariantNames, strum::Display)] #[strum(serialize_all = "snake_case")] pub enum FilterType { @@ -68,6 +117,12 @@ pub enum FilterType { } /// A chain of filter plugins applied sequentially. +/// +/// Chains multiple filters, applying them in order to the input stream. +/// +/// # Fields +/// +/// * `plugins` - Vector of boxed filter plugins. pub struct FilterChain { plugins: Vec>, } diff --git a/src/modes/server/common.rs b/src/modes/server/common.rs index f1b3599..18a41b1 100644 --- a/src/modes/server/common.rs +++ b/src/modes/server/common.rs @@ -238,6 +238,12 @@ pub struct ItemInfo { /// /// This structure provides item details along with its content, handling binary /// content detection and safe string representation. +/// +/// # Fields +/// +/// * `metadata` - Flattened metadata HashMap. +/// * `content` - Optional string content (text only). +/// * `binary` - True if binary content. #[derive(Serialize, Deserialize, ToSchema)] #[schema(description = "Item information including content and metadata, with binary detection")] pub struct ItemContentInfo { @@ -262,6 +268,10 @@ pub struct ItemContentInfo { /// Query parameters for tags. /// /// Structure for handling tag-based query parameters in API requests. +/// +/// # Fields +/// +/// * `tags` - Optional comma-separated tags for filtering. #[derive(Debug, Deserialize)] pub struct TagsQuery { /// Optional comma-separated tags. @@ -273,6 +283,13 @@ pub struct TagsQuery { /// Query parameters for listing items. /// /// Structure for pagination and sorting parameters in item listing endpoints. +/// +/// # Fields +/// +/// * `tags` - Optional tags for filtering. +/// * `order` - Optional sort: "newest" or "oldest". +/// * `start` - Optional start index. +/// * `count` - Optional item limit. #[derive(Debug, Deserialize)] pub struct ListItemsQuery { /// Optional comma-separated tags for filtering. @@ -296,6 +313,14 @@ pub struct ListItemsQuery { /// Query parameters for item retrieval. /// /// Structure for content retrieval parameters, including binary handling and streaming options. +/// +/// # Fields +/// +/// * `allow_binary` - Allow binary (default true). +/// * `offset` - Byte offset (default 0). +/// * `length` - Byte length (default 0 = all). +/// * `stream` - Enable streaming (default false). +/// * `as_meta` - Return as JSON metadata (default false). #[derive(Debug, Deserialize, utoipa::ToSchema)] pub struct ItemQuery { /// Allow binary content (default: true). @@ -328,6 +353,15 @@ pub struct ItemQuery { /// Query parameters for item content retrieval. /// /// Extended query parameters for content-specific operations, including tag filtering. +/// +/// # Fields +/// +/// * `tags` - Optional tags for filtering. +/// * `allow_binary` - Allow binary (default true). +/// * `offset` - Byte offset (default 0). +/// * `length` - Byte length (default 0 = all). +/// * `stream` - Enable streaming (default false). +/// * `as_meta` - Return as JSON metadata (default false). #[derive(Debug, Deserialize, utoipa::ToSchema)] pub struct ItemContentQuery { /// Optional comma-separated tags for filtering. @@ -401,7 +435,12 @@ fn default_as_meta() -> bool { /// /// # Returns /// -/// * `bool` - True if authentication succeeds, false otherwise. +/// * `true` - If authentication succeeds. +/// * `false` - Otherwise. +/// +/// # Errors +/// +/// None; returns false on failure. fn check_bearer_auth(auth_str: &str, expected_password: &str, expected_hash: &Option) -> bool { if !auth_str.starts_with("Bearer ") { return false; @@ -431,7 +470,12 @@ fn check_bearer_auth(auth_str: &str, expected_password: &str, expected_hash: &Op /// /// # Returns /// -/// * `bool` - True if authentication succeeds, false otherwise. +/// * `true` - If authentication succeeds. +/// * `false` - Otherwise. +/// +/// # Errors +/// +/// Returns false on decode or validation failure. fn check_basic_auth(auth_str: &str, expected_password: &str, expected_hash: &Option) -> bool { if !auth_str.starts_with("Basic ") { return false; @@ -470,7 +514,16 @@ fn check_basic_auth(auth_str: &str, expected_password: &str, expected_hash: &Opt /// /// # Returns /// -/// * `bool` - True if authorization is valid, false otherwise. +/// * `true` - If authorized (or no auth required). +/// * `false` - If unauthorized. +/// +/// # Examples +/// +/// ``` +/// if check_auth(&headers, &Some("pass".to_string()), &None) { +/// // Proceed +/// } +/// ``` pub fn check_auth(headers: &HeaderMap, password: &Option, password_hash: &Option) -> bool { // If neither password nor hash is set, no authentication required if password.is_none() && password_hash.is_none() { @@ -493,13 +546,17 @@ pub fn check_auth(headers: &HeaderMap, password: &Option, password_hash: /// /// # Arguments /// -/// * `ConnectInfo(addr)` - Connection information including client address. -/// * `request` - The incoming HTTP request. -/// * `next` - The next middleware in the chain. +/// * `ConnectInfo(addr)` - Connection info with client address. +/// * `request` - Incoming request. +/// * `next` - Next middleware. /// /// # Returns /// -/// The response with logging applied. +/// The processed response with logging. +/// +/// # Examples +/// +/// Used in Axum router: `.layer_handler(logging_middleware)`. pub async fn logging_middleware( ConnectInfo(addr): ConnectInfo, request: Request, @@ -540,12 +597,19 @@ pub async fn logging_middleware( /// /// # Arguments /// -/// * `password` - Optional plain text password for authentication. -/// * `password_hash` - Optional hashed password for authentication. +/// * `password` - Optional plain text password. +/// * `password_hash` - Optional hashed password. /// /// # Returns /// -/// An authentication middleware function that can be used with axum. +/// A clonable async middleware function for Axum. +/// +/// # Examples +/// +/// ``` +/// let auth_middleware = create_auth_middleware(Some("pass".to_string()), None); +/// router.layer(auth_middleware); +/// ``` pub fn create_auth_middleware( password: Option, password_hash: Option,