Skip to main content

torrust_tracker_deployer_lib/presentation/cli/views/
mod.rs

1//! Views Layer - User Interface Output
2//!
3//! This module implements the Views layer of the MVC presentation architecture, handling
4//! user-facing output formatting and presentation. It provides clean separation between
5//! internal logging and user interface output, implementing a dual-channel strategy
6//! following Unix conventions and modern CLI best practices (similar to cargo, docker, npm):
7//!
8//! - **stdout (Results Channel)**: Final results, structured data, output for piping/redirection
9//! - **stderr (Progress/Operational Channel)**: Progress updates, status messages, warnings, errors
10//!
11//! This separation enables:
12//! - Clean piping: `torrust-tracker-deployer destroy env | jq .status` works correctly
13//! - Automation friendly: Scripts can redirect progress to /dev/null while capturing results
14//! - Unix convention compliance: Follows established patterns from modern CLI tools
15//! - Better UX: Progress feedback doesn't interfere with result data
16//!
17//! ## Type-Safe Channel Routing
18//!
19//! The module uses newtype wrappers (`StdoutWriter` and `StderrWriter`) to provide compile-time
20//! guarantees that messages are routed to the correct output channel. This prevents accidental
21//! channel confusion and makes the code more maintainable by catching routing errors at compile
22//! time rather than runtime.
23//!
24//! The newtype pattern is a zero-cost abstraction - it has the same memory layout and performance
25//! characteristics as the wrapped type, but provides type safety benefits.
26//!
27//! ## Buffering Behavior
28//!
29//! Output is line-buffered by default. Messages are typically flushed automatically
30//! after each newline. For cases where immediate output is critical (e.g., before
31//! long-running operations), call `flush()` explicitly:
32//!
33//! ```rust,ignore
34//! output.progress("Starting long operation...");
35//! output.flush()?; // Ensure message appears before operation starts
36//! perform_long_operation();
37//! ```
38//!
39//! ## Example Usage
40//!
41//! ```rust
42//! use torrust_tracker_deployer_lib::presentation::cli::views::{UserOutput, VerbosityLevel};
43//!
44//! let mut output = UserOutput::new(VerbosityLevel::Normal);
45//!
46//! // Progress messages go to stderr
47//! output.progress("Destroying environment...");
48//!
49//! // Success status goes to stderr
50//! output.success("Environment destroyed successfully");
51//!
52//! // Results go to stdout for piping
53//! output.result(r#"{"status": "destroyed"}"#);
54//! ```
55//!
56//! ## Channel Strategy
57//!
58//! Based on research from [`docs/research/UX/console-app-output-patterns.md`](../../docs/research/UX/console-app-output-patterns.md):
59//!
60//! - **stdout**: Deployment results, configuration summaries, structured data (JSON)
61//! - **stderr**: Step progress, status updates, warnings, error messages with actionable guidance
62//!
63//! ## Progress Indicators
64//!
65//! The [`progress`] module provides components for displaying real-time progress during long operations.
66//!
67//! See also: [`docs/research/UX/user-output-vs-logging-separation.md`](../../docs/research/UX/user-output-vs-logging-separation.md)
68
69// Re-export core types and traits for backward compatibility
70pub use channel::Channel;
71pub use formatters::JsonFormatter;
72pub use messages::{
73    DebugDetailMessage, DetailMessage, ErrorMessage, InfoBlockMessage, InfoBlockMessageBuilder,
74    ProgressMessage, ResultMessage, StepsMessage, StepsMessageBuilder, SuccessMessage,
75    WarningMessage,
76};
77pub use sinks::{CompositeSink, FileSink, StandardSink, TelemetrySink};
78pub use theme::Theme;
79pub use traits::{FormatterOverride, OutputMessage, OutputSink};
80pub use user_output::UserOutput;
81pub use verbosity::VerbosityLevel;
82
83// Render trait and error type
84pub mod render;
85pub use render::{Render, ViewRenderError};
86
87// Internal modules
88mod channel;
89mod formatters;
90mod messages;
91mod sinks;
92mod theme;
93mod traits;
94mod user_output;
95mod verbosity;
96
97// Progress indicators module (moved from presentation root for clear ownership)
98pub mod progress;
99
100// Command-specific views (organized by command)
101pub mod commands;
102
103// Testing utilities module (public for use in tests across the codebase)
104pub mod testing;