Add helper environment variable for debugging plugins

Setting the `AGEDEBUG` environment variable to `plugin` will cause all
plugin communications, as well as the plugin's stderr, to be printed to
the stderr of the parent process (e.g. rage).

age-core/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to Rust's notion of
 to 1.0.0 are beta releases.
 
 ## [Unreleased]
+### Added
+- `age_core::io::{DebugReader, DebugWriter}`
+
+### Changed
+- `Connection::open` now returns the debugging-friendly concrete type
+  `Connection<DebugReader<ChildStdout>, DebugWriter<ChildStdin>>`.
 
 ## [0.7.1] - 2021-12-27
 ### Fixed

age-core/Cargo.toml

@@ -38,6 +38,7 @@ nom = { version = "7", default-features = false, features = ["alloc"] }
 secrecy = "0.8"
 
 # Plugin backend
+io_tee = "0.1.1"
 tempfile = { version = "3.2.0", optional = true }
 
 [features]

age-core/src/io.rs

@@ -0,0 +1,62 @@
+//! Common helpers for performing I/O.
+
+use std::io::{self, Read, Stderr, Write};
+
+use io_tee::{ReadExt, TeeReader, TeeWriter, WriteExt};
+
+/// A wrapper around a reader that optionally tees its input to `stderr` for this process.
+pub enum DebugReader<R: Read> {
+    Off(R),
+    On(TeeReader<R, Stderr>),
+}
+
+impl<R: Read> DebugReader<R> {
+    pub(crate) fn new(reader: R, debug_enabled: bool) -> Self {
+        if debug_enabled {
+            DebugReader::On(reader.tee_dbg())
+        } else {
+            DebugReader::Off(reader)
+        }
+    }
+}
+
+impl<R: Read> Read for DebugReader<R> {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        match self {
+            Self::Off(reader) => reader.read(buf),
+            Self::On(reader) => reader.read(buf),
+        }
+    }
+}
+
+/// A wrapper around a writer that optionally tees its output to `stderr` for this process.
+pub enum DebugWriter<W: Write> {
+    Off(W),
+    On(TeeWriter<W, Stderr>),
+}
+
+impl<W: Write> DebugWriter<W> {
+    pub(crate) fn new(writer: W, debug_enabled: bool) -> Self {
+        if debug_enabled {
+            DebugWriter::On(writer.tee_dbg())
+        } else {
+            DebugWriter::Off(writer)
+        }
+    }
+}
+
+impl<W: Write> Write for DebugWriter<W> {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        match self {
+            Self::Off(writer) => writer.write(buf),
+            Self::On(writer) => writer.write(buf),
+        }
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        match self {
+            Self::Off(writer) => writer.flush(),
+            Self::On(writer) => writer.flush(),
+        }
+    }
+}

age-core/src/lib.rs

@@ -12,6 +12,7 @@
 pub use secrecy;
 
 pub mod format;
+pub mod io;
 pub mod primitives;
 
 #[cfg(feature = "plugin")]

age-core/src/plugin.rs

@@ -5,13 +5,17 @@
 
 use rand::{thread_rng, Rng};
 use secrecy::Zeroize;
+use std::env;
 use std::fmt;
 use std::io::{self, BufRead, BufReader, Read, Write};
 use std::iter;
 use std::path::Path;
 use std::process::{ChildStdin, ChildStdout, Command, Stdio};
 
-use crate::format::{grease_the_joint, read, write, Stanza};
+use crate::{
+    format::{grease_the_joint, read, write, Stanza},
+    io::{DebugReader, DebugWriter},
+};
 
 pub const IDENTITY_V1: &str = "identity-v1";
 pub const RECIPIENT_V1: &str = "recipient-v1";
@@ -59,19 +63,31 @@ pub struct Connection<R: Read, W: Write> {
     _working_dir: Option<tempfile::TempDir>,
 }
 
-impl Connection<ChildStdout, ChildStdin> {
-    /// Start a plugin binary with the given state machine.
+impl Connection<DebugReader<ChildStdout>, DebugWriter<ChildStdin>> {
+    /// Starts a plugin binary with the given state machine.
+    ///
+    /// If the `AGEDEBUG` environment variable is set to `plugin`, then all messages sent
+    /// to and from the plugin, as well as anything the plugin prints to its `stderr`,
+    /// will be printed to the `stderr` of the parent process.
     pub fn open(binary: &Path, state_machine: &str) -> io::Result<Self> {
         let working_dir = tempfile::tempdir()?;
+        let debug_enabled = env::var("AGEDEBUG").map(|s| s == "plugin").unwrap_or(false);
         let process = Command::new(binary.canonicalize()?)
             .arg(format!("--age-plugin={}", state_machine))
             .current_dir(working_dir.path())
             .stdin(Stdio::piped())
             .stdout(Stdio::piped())
-            .stderr(Stdio::piped())
+            .stderr(if debug_enabled {
+                Stdio::inherit()
+            } else {
+                Stdio::null()
+            })
             .spawn()?;
-        let input = BufReader::new(process.stdout.expect("could open stdout"));
-        let output = process.stdin.expect("could open stdin");
+        let input = BufReader::new(DebugReader::new(
+            process.stdout.expect("could open stdout"),
+            debug_enabled,
+        ));
+        let output = DebugWriter::new(process.stdin.expect("could open stdin"), debug_enabled);
         Ok(Connection {
             input,
             output,