rustfs_cli/output/
formatter.rs

1//! Output formatter for human-readable and JSON output
2//!
3//! Ensures consistent output formatting across all commands.
4//! JSON output follows the schema defined in schemas/output_v1.json.
5
6use console::Style;
7use serde::Serialize;
8
9use super::OutputConfig;
10use crate::exit_code::ExitCode;
11
12const USAGE_SUGGESTION: &str =
13    "Run the command with --help to review the expected arguments and flags.";
14const NETWORK_SUGGESTION: &str =
15    "Retry the command. If the problem persists, verify the endpoint and network connectivity.";
16const AUTH_SUGGESTION: &str =
17    "Verify the alias credentials and permissions, then retry the command.";
18const NOT_FOUND_SUGGESTION: &str = "Check the alias, bucket, or object path and retry the command.";
19const CONFLICT_SUGGESTION: &str =
20    "Review the target resource state and retry with the appropriate overwrite or ignore flag.";
21const UNSUPPORTED_SUGGESTION: &str =
22    "Retry with --force only if you want to bypass capability detection.";
23
24#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
25struct JsonErrorOutput {
26    error: String,
27    #[serde(skip_serializing_if = "Option::is_none")]
28    code: Option<i32>,
29    #[serde(skip_serializing_if = "Option::is_none")]
30    details: Option<JsonErrorDetails>,
31}
32
33#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
34struct JsonErrorDetails {
35    #[serde(rename = "type")]
36    error_type: &'static str,
37    message: String,
38    #[serde(skip_serializing_if = "Option::is_none")]
39    suggestion: Option<String>,
40    retryable: bool,
41}
42
43#[derive(Debug, Clone, PartialEq, Eq)]
44struct ErrorDescriptor {
45    code: Option<ExitCode>,
46    error_type: &'static str,
47    message: String,
48    suggestion: Option<String>,
49    retryable: bool,
50}
51
52impl ErrorDescriptor {
53    fn from_message(message: &str) -> Self {
54        let message = message.to_string();
55        let (error_type, retryable, suggestion) = infer_error_metadata(&message);
56
57        Self {
58            code: None,
59            error_type,
60            message,
61            suggestion,
62            retryable,
63        }
64    }
65
66    fn from_code(code: ExitCode, message: &str) -> Self {
67        let (error_type, retryable, suggestion) = defaults_for_exit_code(code);
68
69        Self {
70            code: Some(code),
71            error_type,
72            message: message.to_string(),
73            suggestion: suggestion.map(str::to_string),
74            retryable,
75        }
76    }
77
78    fn with_suggestion(mut self, suggestion: impl Into<String>) -> Self {
79        self.suggestion = Some(suggestion.into());
80        self
81    }
82
83    fn to_json_output(&self) -> JsonErrorOutput {
84        JsonErrorOutput {
85            error: self.message.clone(),
86            code: self.code.map(ExitCode::as_i32),
87            details: Some(JsonErrorDetails {
88                error_type: self.error_type,
89                message: self.message.clone(),
90                suggestion: self.suggestion.clone(),
91                retryable: self.retryable,
92            }),
93        }
94    }
95}
96
97fn defaults_for_exit_code(code: ExitCode) -> (&'static str, bool, Option<&'static str>) {
98    match code {
99        ExitCode::Success => ("success", false, None),
100        ExitCode::GeneralError => ("general_error", false, None),
101        ExitCode::UsageError => ("usage_error", false, Some(USAGE_SUGGESTION)),
102        ExitCode::NetworkError => ("network_error", true, Some(NETWORK_SUGGESTION)),
103        ExitCode::AuthError => ("auth_error", false, Some(AUTH_SUGGESTION)),
104        ExitCode::NotFound => ("not_found", false, Some(NOT_FOUND_SUGGESTION)),
105        ExitCode::Conflict => ("conflict", false, Some(CONFLICT_SUGGESTION)),
106        ExitCode::UnsupportedFeature => {
107            ("unsupported_feature", false, Some(UNSUPPORTED_SUGGESTION))
108        }
109        ExitCode::Interrupted => (
110            "interrupted",
111            true,
112            Some("Retry the command if you still need the operation to complete."),
113        ),
114    }
115}
116
117fn infer_error_metadata(message: &str) -> (&'static str, bool, Option<String>) {
118    let normalized = message.to_ascii_lowercase();
119
120    if normalized.contains("not found") || normalized.contains("does not exist") {
121        return ("not_found", false, Some(NOT_FOUND_SUGGESTION.to_string()));
122    }
123
124    if normalized.contains("access denied")
125        || normalized.contains("unauthorized")
126        || normalized.contains("forbidden")
127        || normalized.contains("authentication")
128        || normalized.contains("credentials")
129    {
130        return ("auth_error", false, Some(AUTH_SUGGESTION.to_string()));
131    }
132
133    if normalized.contains("invalid")
134        || normalized.contains("cannot be empty")
135        || normalized.contains("must be")
136        || normalized.contains("must use")
137        || normalized.contains("must include")
138        || normalized.contains("must specify")
139        || normalized.contains("expected:")
140        || normalized.contains("use -r/--recursive")
141    {
142        return ("usage_error", false, Some(USAGE_SUGGESTION.to_string()));
143    }
144
145    if normalized.contains("already exists")
146        || normalized.contains("conflict")
147        || normalized.contains("precondition")
148        || normalized.contains("destination exists")
149    {
150        return ("conflict", false, Some(CONFLICT_SUGGESTION.to_string()));
151    }
152
153    if normalized.contains("does not support")
154        || normalized.contains("unsupported")
155        || normalized.contains("not yet supported")
156    {
157        return (
158            "unsupported_feature",
159            false,
160            Some(UNSUPPORTED_SUGGESTION.to_string()),
161        );
162    }
163
164    if normalized.contains("timeout")
165        || normalized.contains("network")
166        || normalized.contains("connection")
167        || normalized.contains("temporarily unavailable")
168        || normalized.contains("failed to create s3 client")
169    {
170        return ("network_error", true, Some(NETWORK_SUGGESTION.to_string()));
171    }
172
173    ("general_error", false, None)
174}
175
176/// Color theme for styled output (exa/eza inspired)
177#[derive(Debug, Clone)]
178pub struct Theme {
179    /// Directory names - blue + bold
180    pub dir: Style,
181    /// File names - default
182    pub file: Style,
183    /// File sizes - green
184    pub size: Style,
185    /// Timestamps - dim/dark gray
186    pub date: Style,
187    /// Property keys (stat output) - cyan
188    pub key: Style,
189    /// URLs/endpoints - cyan + underline
190    pub url: Style,
191    /// Alias/bucket names - bold
192    pub name: Style,
193    /// Success messages - green
194    pub success: Style,
195    /// Error messages - red
196    pub error: Style,
197    /// Warning messages - yellow
198    pub warning: Style,
199    /// Tree branch characters - dim
200    pub tree_branch: Style,
201}
202
203impl Default for Theme {
204    fn default() -> Self {
205        Self {
206            dir: Style::new().blue().bold(),
207            file: Style::new(),
208            size: Style::new().green(),
209            date: Style::new().dim(),
210            key: Style::new().cyan(),
211            url: Style::new().cyan().underlined(),
212            name: Style::new().bold(),
213            success: Style::new().green(),
214            error: Style::new().red(),
215            warning: Style::new().yellow(),
216            tree_branch: Style::new().dim(),
217        }
218    }
219}
220
221impl Theme {
222    /// Returns a theme with no styling (for no-color mode)
223    pub fn plain() -> Self {
224        Self {
225            dir: Style::new(),
226            file: Style::new(),
227            size: Style::new(),
228            date: Style::new(),
229            key: Style::new(),
230            url: Style::new(),
231            name: Style::new(),
232            success: Style::new(),
233            error: Style::new(),
234            warning: Style::new(),
235            tree_branch: Style::new(),
236        }
237    }
238}
239
240/// Formatter for CLI output
241///
242/// Handles both human-readable and JSON output formats based on configuration.
243/// When JSON mode is enabled, all output is strict JSON without colors or progress.
244#[derive(Debug, Clone)]
245#[allow(dead_code)]
246pub struct Formatter {
247    config: OutputConfig,
248    theme: Theme,
249}
250
251#[allow(dead_code)]
252impl Formatter {
253    /// Create a new formatter with the given configuration
254    pub fn new(config: OutputConfig) -> Self {
255        let theme = if config.no_color || config.json {
256            Theme::plain()
257        } else {
258            Theme::default()
259        };
260        Self { config, theme }
261    }
262
263    /// Check if JSON output mode is enabled
264    pub fn is_json(&self) -> bool {
265        self.config.json
266    }
267
268    /// Check if quiet mode is enabled
269    pub fn is_quiet(&self) -> bool {
270        self.config.quiet
271    }
272
273    /// Check if colors are enabled
274    pub fn colors_enabled(&self) -> bool {
275        !self.config.no_color && !self.config.json
276    }
277
278    /// Get the current theme
279    pub fn theme(&self) -> &Theme {
280        &self.theme
281    }
282
283    /// Get a clone of the output configuration
284    pub fn output_config(&self) -> OutputConfig {
285        self.config.clone()
286    }
287
288    // ========== Style helper methods ==========
289
290    /// Style a directory name (blue + bold)
291    pub fn style_dir(&self, text: &str) -> String {
292        self.theme.dir.apply_to(text).to_string()
293    }
294
295    /// Style a file name (default)
296    pub fn style_file(&self, text: &str) -> String {
297        self.theme.file.apply_to(text).to_string()
298    }
299
300    /// Style a file size (green)
301    pub fn style_size(&self, text: &str) -> String {
302        self.theme.size.apply_to(text).to_string()
303    }
304
305    /// Style a timestamp/date (dim)
306    pub fn style_date(&self, text: &str) -> String {
307        self.theme.date.apply_to(text).to_string()
308    }
309
310    /// Style a property key (cyan)
311    pub fn style_key(&self, text: &str) -> String {
312        self.theme.key.apply_to(text).to_string()
313    }
314
315    /// Style a URL/endpoint (cyan + underline)
316    pub fn style_url(&self, text: &str) -> String {
317        self.theme.url.apply_to(text).to_string()
318    }
319
320    /// Style an alias/bucket name (bold)
321    pub fn style_name(&self, text: &str) -> String {
322        self.theme.name.apply_to(text).to_string()
323    }
324
325    /// Style tree branch characters (dim)
326    pub fn style_tree_branch(&self, text: &str) -> String {
327        self.theme.tree_branch.apply_to(text).to_string()
328    }
329
330    // ========== Output methods ==========
331
332    /// Output a value
333    ///
334    /// In JSON mode, serializes the value to JSON.
335    /// In human mode, uses the Display implementation.
336    pub fn output<T: Serialize + std::fmt::Display>(&self, value: &T) {
337        if self.config.quiet {
338            return;
339        }
340
341        if self.config.json {
342            // JSON output: strict, no colors, no extra formatting
343            match serde_json::to_string_pretty(value) {
344                Ok(json) => println!("{json}"),
345                Err(e) => eprintln!("Error serializing output: {e}"),
346            }
347        } else {
348            println!("{value}");
349        }
350    }
351
352    /// Output a success message
353    pub fn success(&self, message: &str) {
354        if self.config.quiet {
355            return;
356        }
357
358        if self.config.json {
359            // In JSON mode, success is indicated by exit code, not message
360            return;
361        }
362
363        let checkmark = self.theme.success.apply_to("✓");
364        println!("{checkmark} {message}");
365    }
366
367    /// Output an error message
368    ///
369    /// Errors are always printed, even in quiet mode.
370    pub fn error(&self, message: &str) {
371        self.emit_error(ErrorDescriptor::from_message(message));
372    }
373
374    /// Output an error message with an explicit exit code.
375    pub fn error_with_code(&self, code: ExitCode, message: &str) {
376        self.emit_error(ErrorDescriptor::from_code(code, message));
377    }
378
379    /// Output an error message with an explicit exit code and recovery suggestion.
380    pub fn error_with_suggestion(&self, code: ExitCode, message: &str, suggestion: &str) {
381        self.emit_error(ErrorDescriptor::from_code(code, message).with_suggestion(suggestion));
382    }
383
384    /// Print an error and return the provided exit code.
385    pub fn fail(&self, code: ExitCode, message: &str) -> ExitCode {
386        self.error_with_code(code, message);
387        code
388    }
389
390    /// Print an error with a recovery hint and return the provided exit code.
391    pub fn fail_with_suggestion(
392        &self,
393        code: ExitCode,
394        message: &str,
395        suggestion: &str,
396    ) -> ExitCode {
397        self.error_with_suggestion(code, message, suggestion);
398        code
399    }
400
401    fn emit_error(&self, descriptor: ErrorDescriptor) {
402        if self.config.json {
403            let error = descriptor.to_json_output();
404            eprintln!(
405                "{}",
406                serde_json::to_string_pretty(&error).unwrap_or_else(|_| descriptor.message.clone())
407            );
408        } else {
409            let cross = self.theme.error.apply_to("✗");
410            eprintln!("{cross} {}", descriptor.message);
411        }
412    }
413
414    /// Output a warning message
415    pub fn warning(&self, message: &str) {
416        if self.config.quiet || self.config.json {
417            return;
418        }
419
420        let warn_icon = self.theme.warning.apply_to("⚠");
421        eprintln!("{warn_icon} {message}");
422    }
423
424    /// Output JSON directly
425    ///
426    /// Used when you want to output a pre-built JSON structure.
427    pub fn json<T: Serialize>(&self, value: &T) {
428        match serde_json::to_string_pretty(value) {
429            Ok(json) => println!("{json}"),
430            Err(e) => eprintln!("Error serializing output: {e}"),
431        }
432    }
433
434    /// Print a line of text (respects quiet mode)
435    pub fn println(&self, message: &str) {
436        if self.config.quiet {
437            return;
438        }
439        println!("{message}");
440    }
441}
442
443impl Default for Formatter {
444    fn default() -> Self {
445        Self::new(OutputConfig::default())
446    }
447}
448
449#[cfg(test)]
450mod tests {
451    use super::*;
452
453    #[test]
454    fn test_formatter_default() {
455        let formatter = Formatter::default();
456        assert!(!formatter.is_json());
457        assert!(!formatter.is_quiet());
458        assert!(formatter.colors_enabled());
459    }
460
461    #[test]
462    fn test_formatter_json_mode() {
463        let config = OutputConfig {
464            json: true,
465            ..Default::default()
466        };
467        let formatter = Formatter::new(config);
468        assert!(formatter.is_json());
469        assert!(!formatter.colors_enabled()); // Colors disabled in JSON mode
470    }
471
472    #[test]
473    fn test_formatter_no_color() {
474        let config = OutputConfig {
475            no_color: true,
476            ..Default::default()
477        };
478        let formatter = Formatter::new(config);
479        assert!(!formatter.colors_enabled());
480    }
481
482    #[test]
483    fn test_error_descriptor_from_code_sets_defaults() {
484        let descriptor =
485            ErrorDescriptor::from_code(ExitCode::NetworkError, "Failed to create S3 client");
486
487        assert_eq!(descriptor.code, Some(ExitCode::NetworkError));
488        assert_eq!(descriptor.error_type, "network_error");
489        assert!(descriptor.retryable);
490        assert_eq!(descriptor.suggestion.as_deref(), Some(NETWORK_SUGGESTION));
491    }
492
493    #[test]
494    fn test_error_descriptor_from_message_infers_not_found() {
495        let descriptor = ErrorDescriptor::from_message("Alias 'local' not found");
496        let json = descriptor.to_json_output();
497
498        assert_eq!(json.error, "Alias 'local' not found");
499        assert_eq!(json.code, None);
500        let details = json.details.expect("details should be present");
501        assert_eq!(details.error_type, "not_found");
502        assert!(!details.retryable);
503        assert_eq!(details.suggestion.as_deref(), Some(NOT_FOUND_SUGGESTION));
504    }
505
506    #[test]
507    fn test_error_descriptor_from_message_prefers_usage_for_invalid_permission() {
508        let descriptor = ErrorDescriptor::from_message("Invalid permission 'download'");
509        let json = descriptor.to_json_output();
510
511        let details = json.details.expect("details should be present");
512        assert_eq!(details.error_type, "usage_error");
513        assert!(!details.retryable);
514        assert_eq!(details.suggestion.as_deref(), Some(USAGE_SUGGESTION));
515    }
516
517    #[test]
518    fn test_error_descriptor_from_message_prefers_auth_for_invalid_credentials() {
519        let descriptor = ErrorDescriptor::from_message("Invalid credentials for alias 'local'");
520        let json = descriptor.to_json_output();
521
522        let details = json.details.expect("details should be present");
523        assert_eq!(details.error_type, "auth_error");
524        assert!(!details.retryable);
525        assert_eq!(details.suggestion.as_deref(), Some(AUTH_SUGGESTION));
526    }
527
528    #[test]
529    fn test_error_descriptor_from_message_classifies_other_auth_failures() {
530        for message in [
531            "Unauthorized request for alias 'local'",
532            "Forbidden: bucket access denied",
533            "Authentication failed for alias 'local'",
534        ] {
535            let descriptor = ErrorDescriptor::from_message(message);
536            let json = descriptor.to_json_output();
537            let details = json.details.expect("details should be present");
538
539            assert_eq!(details.error_type, "auth_error", "message: {message}");
540            assert!(!details.retryable, "message: {message}");
541            assert_eq!(
542                details.suggestion.as_deref(),
543                Some(AUTH_SUGGESTION),
544                "message: {message}"
545            );
546        }
547    }
548
549    #[test]
550    fn test_error_descriptor_from_message_infers_conflict() {
551        let descriptor = ErrorDescriptor::from_message("Destination exists: report.json");
552        let json = descriptor.to_json_output();
553
554        let details = json.details.expect("details should be present");
555        assert_eq!(details.error_type, "conflict");
556        assert!(!details.retryable);
557        assert_eq!(details.suggestion.as_deref(), Some(CONFLICT_SUGGESTION));
558    }
559
560    #[test]
561    fn test_error_descriptor_from_message_infers_unsupported_feature() {
562        let descriptor = ErrorDescriptor::from_message(
563            "Cross-alias S3-to-S3 copy not yet supported. Use download + upload.",
564        );
565        let json = descriptor.to_json_output();
566
567        let details = json.details.expect("details should be present");
568        assert_eq!(details.error_type, "unsupported_feature");
569        assert!(!details.retryable);
570        assert_eq!(details.suggestion.as_deref(), Some(UNSUPPORTED_SUGGESTION));
571    }
572
573    #[test]
574    fn test_error_descriptor_from_message_infers_retryable_network_error() {
575        let descriptor =
576            ErrorDescriptor::from_message("Service temporarily unavailable while connecting");
577        let json = descriptor.to_json_output();
578
579        let details = json.details.expect("details should be present");
580        assert_eq!(details.error_type, "network_error");
581        assert!(details.retryable);
582        assert_eq!(details.suggestion.as_deref(), Some(NETWORK_SUGGESTION));
583    }
584
585    #[test]
586    fn test_error_with_suggestion_overrides_default_hint() {
587        let descriptor = ErrorDescriptor::from_code(
588            ExitCode::UnsupportedFeature,
589            "Backend does not support notifications.",
590        )
591        .with_suggestion("Retry with --force to bypass capability detection.");
592
593        let json = descriptor.to_json_output();
594        let details = json.details.expect("details should be present");
595
596        assert_eq!(details.error_type, "unsupported_feature");
597        assert_eq!(
598            details.suggestion.as_deref(),
599            Some("Retry with --force to bypass capability detection.")
600        );
601    }
602}
rustfs_cli/output/formatter.rs

rustfs_cli/output/
formatter.rs
