standout_dispatch/

handler.rs

//! Command handler types.
//!
//! This module provides the core types for building logic handlers - the
//! business logic layer in the dispatch pipeline.
//!
//! # Design Rationale
//!
//! Logic handlers are responsible for business logic only. They:
//!
//! - Receive parsed CLI arguments (`&ArgMatches`) and execution context
//! - Perform application logic (database queries, file operations, etc.)
//! - Return serializable data that will be passed to the render handler
//!
//! Handlers explicitly do not handle:
//! - Output formatting (that's the render handler's job)
//! - Template selection (that's configured at the framework level)
//! - Theme/style decisions (that's the render handler's job)
//!
//! This separation keeps handlers focused and testable - you can unit test
//! a handler by checking the data it returns, without worrying about rendering.
//!
//! # Core Types
//!
//! - [`CommandContext`]: Environment information passed to handlers
//! - [`Output`]: What a handler produces (render data, silent, or binary)
//! - [`HandlerResult`]: The result type for handlers (`Result<Output<T>, Error>`)
//! - [`RunResult`]: The result of running the CLI dispatcher
//! - [`Handler`]: Trait for thread-safe command handlers (`Send + Sync`, `&self`)
//! - [`LocalHandler`]: Trait for local command handlers (no `Send + Sync`, `&mut self`)

use clap::ArgMatches;
use serde::Serialize;

/// Context passed to command handlers.
///
/// Provides information about the execution environment. Note that output format
/// is deliberately not included here - format decisions are made by the
/// render handler, not by logic handlers.
///
/// If handlers need format-aware behavior (e.g., skip expensive formatting for
/// JSON output), the consuming framework can extend this context or pass format
/// information through other means.
#[derive(Debug, Clone, Default)]
pub struct CommandContext {
    /// The command path being executed (e.g., ["config", "get"])
    pub command_path: Vec<String>,
}

/// What a handler produces.
///
/// This enum represents the different types of output a command handler can produce.
#[derive(Debug)]
pub enum Output<T: Serialize> {
    /// Data to render with a template or serialize to JSON/YAML/etc.
    Render(T),
    /// Silent exit (no output produced)
    Silent,
    /// Binary output for file exports
    Binary {
        /// The binary data
        data: Vec<u8>,
        /// Suggested filename for the output
        filename: String,
    },
}

impl<T: Serialize> Output<T> {
    /// Returns true if this is a render result.
    pub fn is_render(&self) -> bool {
        matches!(self, Output::Render(_))
    }

    /// Returns true if this is a silent result.
    pub fn is_silent(&self) -> bool {
        matches!(self, Output::Silent)
    }

    /// Returns true if this is a binary result.
    pub fn is_binary(&self) -> bool {
        matches!(self, Output::Binary { .. })
    }
}

/// The result type for command handlers.
///
/// Enables use of the `?` operator for error propagation.
pub type HandlerResult<T> = Result<Output<T>, anyhow::Error>;

/// Result of running the CLI dispatcher.
///
/// After processing arguments, the dispatcher either handles a command
/// or falls through for manual handling.
#[derive(Debug)]
pub enum RunResult {
    /// A handler processed the command; contains the rendered output
    Handled(String),
    /// A handler produced binary output (bytes, suggested filename)
    Binary(Vec<u8>, String),
    /// Silent output (handler completed but produced no output)
    Silent,
    /// No handler matched; contains the ArgMatches for manual handling
    NoMatch(ArgMatches),
}

impl RunResult {
    /// Returns true if a handler processed the command (text output).
    pub fn is_handled(&self) -> bool {
        matches!(self, RunResult::Handled(_))
    }

    /// Returns true if the result is binary output.
    pub fn is_binary(&self) -> bool {
        matches!(self, RunResult::Binary(_, _))
    }

    /// Returns true if the result is silent.
    pub fn is_silent(&self) -> bool {
        matches!(self, RunResult::Silent)
    }

    /// Returns the output if handled, or None otherwise.
    pub fn output(&self) -> Option<&str> {
        match self {
            RunResult::Handled(s) => Some(s),
            _ => None,
        }
    }

    /// Returns the binary data and filename if binary, or None otherwise.
    pub fn binary(&self) -> Option<(&[u8], &str)> {
        match self {
            RunResult::Binary(bytes, filename) => Some((bytes, filename)),
            _ => None,
        }
    }

    /// Returns the matches if unhandled, or None if handled.
    pub fn matches(&self) -> Option<&ArgMatches> {
        match self {
            RunResult::NoMatch(m) => Some(m),
            _ => None,
        }
    }
}

/// Trait for thread-safe command handlers.
///
/// Handlers must be `Send + Sync` and use immutable `&self`.
pub trait Handler: Send + Sync {
    /// The output type produced by this handler (must be serializable)
    type Output: Serialize;

    /// Execute the handler with the given matches and context.
    fn handle(&self, matches: &ArgMatches, ctx: &CommandContext) -> HandlerResult<Self::Output>;
}

/// A wrapper that implements Handler for closures.
pub struct FnHandler<F, T>
where
    F: Fn(&ArgMatches, &CommandContext) -> HandlerResult<T> + Send + Sync,
    T: Serialize + Send + Sync,
{
    f: F,
    _phantom: std::marker::PhantomData<fn() -> T>,
}

impl<F, T> FnHandler<F, T>
where
    F: Fn(&ArgMatches, &CommandContext) -> HandlerResult<T> + Send + Sync,
    T: Serialize + Send + Sync,
{
    /// Creates a new FnHandler wrapping the given closure.
    pub fn new(f: F) -> Self {
        Self {
            f,
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<F, T> Handler for FnHandler<F, T>
where
    F: Fn(&ArgMatches, &CommandContext) -> HandlerResult<T> + Send + Sync,
    T: Serialize + Send + Sync,
{
    type Output = T;

    fn handle(&self, matches: &ArgMatches, ctx: &CommandContext) -> HandlerResult<T> {
        (self.f)(matches, ctx)
    }
}

/// Trait for local (single-threaded) command handlers.
///
/// Unlike [`Handler`], this trait:
/// - Does NOT require `Send + Sync`
/// - Takes `&mut self` instead of `&self`
/// - Allows handlers to mutate their internal state directly
pub trait LocalHandler {
    /// The output type produced by this handler (must be serializable)
    type Output: Serialize;

    /// Execute the handler with the given matches and context.
    fn handle(&mut self, matches: &ArgMatches, ctx: &CommandContext)
        -> HandlerResult<Self::Output>;
}

/// A wrapper that implements LocalHandler for FnMut closures.
pub struct LocalFnHandler<F, T>
where
    F: FnMut(&ArgMatches, &CommandContext) -> HandlerResult<T>,
    T: Serialize,
{
    f: F,
    _phantom: std::marker::PhantomData<fn() -> T>,
}

impl<F, T> LocalFnHandler<F, T>
where
    F: FnMut(&ArgMatches, &CommandContext) -> HandlerResult<T>,
    T: Serialize,
{
    /// Creates a new LocalFnHandler wrapping the given FnMut closure.
    pub fn new(f: F) -> Self {
        Self {
            f,
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<F, T> LocalHandler for LocalFnHandler<F, T>
where
    F: FnMut(&ArgMatches, &CommandContext) -> HandlerResult<T>,
    T: Serialize,
{
    type Output = T;

    fn handle(&mut self, matches: &ArgMatches, ctx: &CommandContext) -> HandlerResult<T> {
        (self.f)(matches, ctx)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn test_command_context_creation() {
        let ctx = CommandContext {
            command_path: vec!["config".into(), "get".into()],
        };
        assert_eq!(ctx.command_path, vec!["config", "get"]);
    }

    #[test]
    fn test_command_context_default() {
        let ctx = CommandContext::default();
        assert!(ctx.command_path.is_empty());
    }

    #[test]
    fn test_output_render() {
        let output: Output<String> = Output::Render("success".into());
        assert!(output.is_render());
        assert!(!output.is_silent());
        assert!(!output.is_binary());
    }

    #[test]
    fn test_output_silent() {
        let output: Output<String> = Output::Silent;
        assert!(!output.is_render());
        assert!(output.is_silent());
        assert!(!output.is_binary());
    }

    #[test]
    fn test_output_binary() {
        let output: Output<String> = Output::Binary {
            data: vec![0x25, 0x50, 0x44, 0x46],
            filename: "report.pdf".into(),
        };
        assert!(!output.is_render());
        assert!(!output.is_silent());
        assert!(output.is_binary());
    }

    #[test]
    fn test_run_result_handled() {
        let result = RunResult::Handled("output".into());
        assert!(result.is_handled());
        assert!(!result.is_binary());
        assert!(!result.is_silent());
        assert_eq!(result.output(), Some("output"));
        assert!(result.matches().is_none());
    }

    #[test]
    fn test_run_result_silent() {
        let result = RunResult::Silent;
        assert!(!result.is_handled());
        assert!(!result.is_binary());
        assert!(result.is_silent());
    }

    #[test]
    fn test_run_result_binary() {
        let bytes = vec![0x25, 0x50, 0x44, 0x46];
        let result = RunResult::Binary(bytes.clone(), "report.pdf".into());
        assert!(!result.is_handled());
        assert!(result.is_binary());
        assert!(!result.is_silent());

        let (data, filename) = result.binary().unwrap();
        assert_eq!(data, &bytes);
        assert_eq!(filename, "report.pdf");
    }

    #[test]
    fn test_run_result_no_match() {
        let matches = clap::Command::new("test").get_matches_from(vec!["test"]);
        let result = RunResult::NoMatch(matches);
        assert!(!result.is_handled());
        assert!(!result.is_binary());
        assert!(result.matches().is_some());
    }

    #[test]
    fn test_fn_handler() {
        let handler = FnHandler::new(|_m: &ArgMatches, _ctx: &CommandContext| {
            Ok(Output::Render(json!({"status": "ok"})))
        });

        let ctx = CommandContext::default();
        let matches = clap::Command::new("test").get_matches_from(vec!["test"]);

        let result = handler.handle(&matches, &ctx);
        assert!(result.is_ok());
    }

    #[test]
    fn test_local_fn_handler_mutation() {
        let mut counter = 0u32;

        let mut handler = LocalFnHandler::new(|_m: &ArgMatches, _ctx: &CommandContext| {
            counter += 1;
            Ok(Output::Render(counter))
        });

        let ctx = CommandContext::default();
        let matches = clap::Command::new("test").get_matches_from(vec!["test"]);

        let _ = handler.handle(&matches, &ctx);
        let _ = handler.handle(&matches, &ctx);
        let result = handler.handle(&matches, &ctx);

        assert!(result.is_ok());
        if let Ok(Output::Render(count)) = result {
            assert_eq!(count, 3);
        }
    }
}