A nicer way to export definitions to stdout and import them from stdin

instead of a brittle and shell/escaping-dependent special
value of '-', which is still supported for backwards
compatibility, even in single quotes, the user
is now asked to pass --stdout and --stdin, respectively.
'

Author: michaelklishin

CHANGELOG.md

@@ -1,8 +1,50 @@
 # rabbitmqadmin-ng Change Log
 
-## v0.29.0 (in development)
+## v0.30.0 (in development)
 
-In (documented) changes yet.
+No (documented) changes yet.
+
+
+## v0.29.0 (Mar 23, 2025)
+
+### Breaking Changes
+
+ * `definitions export`'s special `--file` value of `-` for "standard input" is deprecated. Use `--stdout` instead:
+
+   ```shell
+   rabbitmqadmin definitions export --stdout > definitions.json
+   ```
+
+      ```shell
+   # exports 3.x-era definitions that might contain classic queue mirroring keys, transforms
+   # them to not use any CMQ policies, injects an explicit queue type into the matched queues,
+   # and drops all the policies that had nothing beyond the CMQ keys,
+   # then passes the result to the standard input of
+   # 'rabbitmqadmin definitions import --stdin'
+   rabbitmqadmin --node "source.node" definitions export --transformations strip_cmq_keys_from_policies,drop_empty_policies --stdout | rabbitmqadmin --node "destination.node" definitions import --stdin
+   ```
+
+### Enhancements
+
+ * 'definitions import` now supports reading definitions from the standard input instead of a file.
+   For that, pass `--stdin` instead of `--file "/path/to/definitions.json"`.
+
+   ```shell
+   rabbitmqadmin definitions import --stdin < definitions.json
+   ```
+
+   ```shell
+   cat definitions.json | rabbitmqadmin definitions import --stdin
+   ```
+
+   ```shell
+   # exports 3.x-era definitions that might contain classic queue mirroring keys, transforms
+   # them to not use any CMQ policies, injects an explicit queue type into the matched queues,
+   # and drops all the policies that had nothing beyond the CMQ keys,
+   # then passes the result to the standard input of
+   # 'rabbitmqadmin definitions import --stdin'
+   rabbitmqadmin --node "source.node" definitions export --transformations strip_cmq_keys_from_policies,drop_empty_policies --stdout | rabbitmqadmin --node "destination.node" definitions import --stdin
+   ```
 
 
 ## v0.28.0 (Mar 23, 2025)

src/cli.rs

@@ -1203,10 +1203,22 @@ fn definitions_subcommands() -> [Command; 4] {
         ))
         .arg(
             Arg::new("file")
+                .group("output")
                 .long("file")
-                .help("output file path or '-' for standard output")
+                .help("output file path")
                 .required(false)
-                .default_value("-"),
+                .default_value("-")
+                .conflicts_with("stdout"),
+        )
+        .arg(
+            Arg::new("stdout")
+                .group("output")
+                .long("stdout")
+                .help("print result to the standard output stream")
+                .required(false)
+                .num_args(0)
+                .action(ArgAction::SetTrue)
+                .conflicts_with("file"),
         )
         .arg(
             Arg::new("transformations")
@@ -1250,10 +1262,22 @@ Examples:
         ))
         .arg(
             Arg::new("file")
+                .group("output")
                 .long("file")
-                .help("output file path or '-' for standard output")
+                .help("output file path")
                 .required(false)
-                .default_value("-"),
+                .default_value("-")
+                .conflicts_with("stdout"),
+        )
+        .arg(
+            Arg::new("stdout")
+                .group("output")
+                .long("stdout")
+                .help("print result to the standard output stream")
+                .required(false)
+                .num_args(0)
+                .action(ArgAction::SetTrue)
+                .conflicts_with("file"),
         );
 
     let import_cmd = Command::new("import")
@@ -1264,9 +1288,21 @@ Examples:
         ))
         .arg(
             Arg::new("file")
+                .group("input")
                 .long("file")
-                .help("JSON file with cluster-wide definitions")
-                .required(true),
+                .help("cluster-wide definitions JSON file path; mutually exclusive with --stdin")
+                .required(true)
+                .conflicts_with("stdin"),
+        )
+        .arg(
+            Arg::new("stdin")
+                .group("input")
+                .long("stdin")
+                .help("read input JSON from the standard input stream, mutually exclusive with --file")
+                .required(false)
+                .num_args(0)
+                .action(ArgAction::SetTrue)
+                .conflicts_with("file"),
         );
 
     let import_into_vhost_cmd = Command::new("import_into_vhost")
@@ -1277,9 +1313,21 @@ Examples:
         ))
         .arg(
             Arg::new("file")
+                .group("input")
                 .long("file")
-                .help("JSON file with virtual host-specific definitions")
-                .required(true),
+                .help("cluster-wide definitions JSON file path; mutually exclusive with --stdin")
+                .required(true)
+                .conflicts_with("stdin"),
+        )
+        .arg(
+            Arg::new("stdin")
+                .group("input")
+                .long("stdin")
+                .help("read input JSON from the standard input stream, mutually exclusive with --file")
+                .required(false)
+                .num_args(0)
+                .action(ArgAction::SetTrue)
+                .conflicts_with("file"),
         );
 
     [

src/commands.rs

@@ -1215,16 +1215,31 @@ fn export_cluster_wide_definitions_without_transformations(
 ) -> ClientResult<()> {
     match client.export_cluster_wide_definitions() {
         Ok(definitions) => {
-            let path = command_args.get_one::<String>("file").unwrap();
-            match path.as_str() {
-                "-" => {
+            let path = command_args.get_one::<String>("file").cloned();
+            let use_stdout = command_args.get_one::<bool>("stdout").copied();
+            match (path, use_stdout) {
+                (Some(_val), Some(true)) => {
                     println!("{}", &definitions);
                     Ok(())
                 }
-                file => {
-                    _ = fs::write(file, &definitions);
+                (Some(val), Some(false)) => match val.as_str() {
+                    "-" => {
+                        println!("{}", &definitions);
+                        Ok(())
+                    }
+                    _ => {
+                        _ = fs::write(val, &definitions);
+                        Ok(())
+                    }
+                },
+                (_, Some(true)) => {
+                    println!("{}", &definitions);
                     Ok(())
                 }
+                _ => {
+                    eprintln!("either --file or --stdout must be provided");
+                    process::exit(1)
+                }
             }
         }
         Err(err) => Err(err),
@@ -1257,19 +1272,39 @@ pub fn export_vhost_definitions(
 pub fn import_definitions(client: APIClient, command_args: &ArgMatches) -> ClientResult<()> {
     let path = command_args
         .get_one::<String>("file")
-        .map(|s| s.trim_ascii().trim_matches('\'').trim_matches('"'))
-        .unwrap();
-    let definitions = read_definitions(path);
+        .map(|s| s.trim_ascii().trim_matches('\'').trim_matches('"'));
+    let use_stdin = command_args.get_one::<bool>("stdin").copied();
+    let definitions = read_definitions(path, use_stdin);
     match definitions {
         Ok(defs) => {
             let defs_json = serde_json::from_str(defs.as_str()).unwrap_or_else(|err| {
-                eprintln!("`{}` is not a valid JSON file: {}", path, err);
+                match path {
+                    None => {
+                        eprintln!("could not parse the value read from the standard input: {}", err);
+                    }
+                    Some(val) => {
+                        eprintln!("`{}` does not exist, is not a readable file, or is not a valid JSON file: {}", val, err);
+                    }
+                }
                 process::exit(1)
             });
             client.import_definitions(defs_json)
         }
         Err(err) => {
-            eprintln!("`{}` could not be read: {}", path, err);
+            match path {
+                None => {
+                    eprintln!(
+                        "could not parse the value read from the standard input: {}",
+                        err
+                    );
+                }
+                Some(val) => {
+                    eprintln!(
+                        "`{}` does not exist, is not a readable file, or is not a valid JSON file: {}",
+                        val, err
+                    );
+                }
+            }
             process::exit(1)
         }
     }
@@ -1282,43 +1317,79 @@ pub fn import_vhost_definitions(
 ) -> ClientResult<()> {
     let path = command_args
         .get_one::<String>("file")
-        .map(|s| s.trim_ascii().trim_matches('\'').trim_matches('"'))
-        .unwrap();
-    let definitions = read_definitions(path);
+        .map(|s| s.trim_ascii().trim_matches('\'').trim_matches('"'));
+    let use_stdin = command_args.get_one::<bool>("stdin").copied();
+    let definitions = read_definitions(path, use_stdin);
     match definitions {
         Ok(defs) => {
             let defs_json = serde_json::from_str(defs.as_str()).unwrap_or_else(|err| {
-                eprintln!("`{}` is not a valid JSON file: {}", path, err);
+                match path {
+                    None => {
+                        eprintln!("could not parse the value read from the standard input: {}", err);
+                    }
+                    Some(val) => {
+                        eprintln!("`{}` does not exist, is not a readable file, or is not a valid JSON file: {}", val, err);
+                    }
+                }
                 process::exit(1)
             });
             client.import_vhost_definitions(vhost, defs_json)
         }
         Err(err) => {
-            eprintln!("`{}` could not be read: {}", path, err);
+            match path {
+                None => {
+                    eprintln!(
+                        "could not parse the value read from the standard input: {}",
+                        err
+                    );
+                }
+                Some(val) => {
+                    eprintln!(
+                        "`{}` does not exist, is not a readable file, or is not a valid JSON file: {}",
+                        val, err
+                    );
+                }
+            }
             process::exit(1)
         }
     }
 }
 
-fn read_definitions(path: &str) -> io::Result<String> {
-    match path {
-        "-" => {
+fn read_definitions(path: Option<&str>, use_stdin: Option<bool>) -> io::Result<String> {
+    match (path, use_stdin) {
+        (_, Some(true)) => {
             let mut buffer = String::new();
-            let stdin = io::stdin();
-            let lines = stdin.lines();
-            for ln in lines {
-                match ln {
-                    Ok(line) => buffer.push_str(&line),
-                    Err(err) => {
-                        eprintln!("Error reading from standard input: {}", err);
-                        process::exit(1);
-                    }
-                }
-            }
+            read_stdin_lines(&mut buffer);
 
             Ok(buffer)
         }
-        _ => fs::read_to_string(path),
+        (Some(val), _) => match val {
+            "-" => {
+                let mut buffer = String::new();
+                read_stdin_lines(&mut buffer);
+
+                Ok(buffer)
+            }
+            _ => fs::read_to_string(val),
+        },
+        _ => Err(io::Error::new(
+            io::ErrorKind::InvalidInput,
+            "either an input file path or --stdin must be specified",
+        )),
+    }
+}
+
+fn read_stdin_lines(buffer: &mut String) {
+    let stdin = io::stdin();
+    let lines = stdin.lines();
+    for ln in lines {
+        match ln {
+            Ok(line) => buffer.push_str(&line),
+            Err(err) => {
+                eprintln!("Error reading from standard input: {}", err);
+                process::exit(1);
+            }
+        }
     }
 }