Share CLI connection logic to cli-tools (#576)

This will be used by xtask when using actions that require a connection
like `applet-install`.

Author: ia0

crates/cli-tools/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Minor
 
+- Add `action::{ConnectionOptions,GlobalConnection}` for lazy platform connection
 - Change the behavior of `fs::copy_if_changed()` to keep an original source
 
 ### Patch

crates/cli-tools/Cargo.lock

@@ -14,7 +14,9 @@ categories = ["command-line-utilities", "embedded", "wasm"]
 [dependencies]
 anyhow = { version = "1.0.86", default-features = false, features = ["std"] }
 cargo_metadata = { version = "0.18.1", default-features = false }
-clap = { version = "4.5.4", default-features = false, features = ["derive", "std"] }
+clap = { version = "4.5.4", default-features = false, features = ["derive", "env", "std"] }
+data-encoding = { version = "2.6.0", default-features = false, features = ["std"] }
+humantime = { version = "2.1.0", default-features = false }
 rusb = { version = "0.9.4", default-features = false }
 serde = { version = "1.0.202", default-features = false, features = ["derive"] }
 toml = { version = "0.8.13", default-features = false, features = ["display", "parse"] }

crates/cli-tools/Cargo.toml

@@ -15,16 +15,101 @@
 use std::fmt::Display;
 use std::path::{Path, PathBuf};
 use std::process::Command;
+use std::time::Duration;
 
 use anyhow::{bail, ensure, Result};
 use cargo_metadata::{Metadata, MetadataCommand};
 use clap::{ValueEnum, ValueHint};
-use rusb::UsbContext;
+use data_encoding::HEXLOWER_PERMISSIVE as HEX;
+use rusb::{GlobalContext, UsbContext};
 use wasefire_protocol::{self as service, applet, Api};
-use wasefire_protocol_usb::Connection;
+use wasefire_protocol_usb::{Candidate, Connection};
 
 use crate::{cmd, fs};
 
+/// Options to connect to a platform.
+#[derive(Clone, clap::Args)]
+pub struct ConnectionOptions {
+    /// Serial of the platform to connect to.
+    #[arg(long, env = "WASEFIRE_SERIAL")]
+    serial: Option<String>,
+
+    /// Timeout to send or receive on the platform protocol.
+    #[arg(long, default_value = "1s")]
+    timeout: humantime::Duration,
+}
+
+impl ConnectionOptions {
+    /// Returns the timeout for platform connection.
+    pub fn timeout(&self) -> Duration {
+        *self.timeout
+    }
+}
+
+/// Reusable lazy connection to a platform.
+pub enum GlobalConnection {
+    /// The connection is not yet configured and can be established.
+    Invalid,
+    /// The connection is configured but not yet established.
+    Ready { options: ConnectionOptions },
+    /// The connection is established.
+    Connected { connection: Connection<GlobalContext> },
+}
+
+impl GlobalConnection {
+    /// Configures the connection (required to access it).
+    pub fn configure(&mut self, options: ConnectionOptions) {
+        match self {
+            GlobalConnection::Invalid => *self = GlobalConnection::Ready { options },
+            _ => panic!("connection already configured"),
+        }
+    }
+
+    /// Accesses the connection (establishing it if needed).
+    pub fn get(&mut self) -> Result<&Connection<GlobalContext>> {
+        if let GlobalConnection::Ready { options } = self {
+            let connection = connect(options.timeout(), options.serial.as_deref())?;
+            *self = GlobalConnection::Connected { connection };
+        }
+        match self {
+            GlobalConnection::Connected { connection } => Ok(connection),
+            _ => panic!("connection not yet configured"),
+        }
+    }
+}
+
+fn connect(timeout: Duration, serial: Option<&str>) -> Result<Connection<GlobalContext>> {
+    let context = GlobalContext::default();
+    let mut candidates = wasefire_protocol_usb::list(&context)?;
+    let candidate = match (serial, candidates.len()) {
+        (None, 0) => bail!("no connected platforms"),
+        (None, 1) => candidates.pop().unwrap(),
+        (None, n) => {
+            eprintln!("Choose one of the {n} connected platforms using its --serial option:");
+            for candidate in candidates {
+                eprintln!("    --serial={}", get_serial(&candidate, timeout)?);
+            }
+            bail!("more than one connected platform");
+        }
+        (Some(serial), _) => {
+            match candidates
+                .into_iter()
+                .try_find(|x| anyhow::Ok(get_serial(x, timeout)? == serial))?
+            {
+                Some(x) => x,
+                None => bail!("no connected platform with serial={serial}"),
+            }
+        }
+    };
+    Ok(candidate.connect(timeout)?)
+}
+
+fn get_serial(candidate: &Candidate<GlobalContext>, timeout: Duration) -> Result<String> {
+    let connection = candidate.clone().connect(timeout)?;
+    let info = connection.call::<service::PlatformInfo>(())?;
+    Ok(HEX.encode(info.get().serial))
+}
+
 /// Parameters for an applet or platform RPC.
 #[derive(clap::Args)]
 pub struct Rpc {

crates/cli-tools/src/action.rs

@@ -17,6 +17,7 @@
 //! This library is also used for the internal maintenance CLI of Wasefire called xtask.
 
 #![feature(path_add_extension)]
+#![feature(try_find)]
 
 macro_rules! debug {
     ($($x:tt)*) => {

crates/cli-tools/src/lib.rs

@@ -30,4 +30,4 @@
 
 ## 0.1.0
 
-<!-- Increment to skip CHANGELOG.md test: 2 -->
+<!-- Increment to skip CHANGELOG.md test: 3 -->

crates/cli/CHANGELOG.md

@@ -20,7 +20,6 @@ anyhow = { version = "1.0.86", default-features = false }
 clap = { version = "4.5.4", default-features = false, features = ["default", "derive", "env"] }
 clap_complete = { version = "4.5.2", default-features = false }
 data-encoding = { version = "2.6.0", default-features = false, features = ["std"] }
-humantime = { version = "2.1.0", default-features = false }
 rusb = { version = "0.9.4", default-features = false }
 wasefire-cli-tools = { version = "0.1.1-git", path = "../cli-tools" }
 wasefire-protocol = { version = "0.1.1-git", path = "../protocol", features = ["host"] }

crates/cli/Cargo.lock

@@ -12,8 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#![feature(try_find)]
-
 use std::fs::File;
 use std::io::Write;
 use std::path::{Path, PathBuf};
@@ -27,29 +25,17 @@ use data_encoding::HEXLOWER_PERMISSIVE as HEX;
 use rusb::GlobalContext;
 use wasefire_cli_tools::{action, fs};
 use wasefire_protocol::{self as service, platform};
-use wasefire_protocol_usb::{Candidate, Connection};
 
 #[derive(Parser)]
 #[command(version, about)]
 struct Flags {
     #[command(flatten)]
-    options: Options,
+    connection_options: action::ConnectionOptions,
 
     #[command(subcommand)]
     action: Action,
 }
 
-#[derive(clap::Args)]
-struct Options {
-    /// Serial of the platform to connect to.
-    #[arg(long, env = "WASEFIRE_SERIAL")]
-    serial: Option<String>,
-
-    /// Timeout to send or receive on the platform protocol.
-    #[arg(long, value_parser = humantime::parse_duration, default_value = "1s")]
-    timeout: Duration,
-}
-
 #[derive(clap::Subcommand)]
 enum Action {
     /// Lists the applets installed on a platform.
@@ -113,15 +99,15 @@ impl Completion {
 
 fn main() -> Result<()> {
     let flags = Flags::parse();
-    CONNECTION.lock().unwrap().set(flags.options.timeout, flags.options.serial);
+    CONNECTION.lock().unwrap().configure(flags.connection_options.clone());
     let dir = std::env::current_dir()?;
     match flags.action {
         Action::AppletList => bail!("not implemented yet"),
         Action::AppletInstall => bail!("not implemented yet"),
         Action::AppletUpdate => bail!("not implemented yet"),
         Action::AppletUninstall => bail!("not implemented yet"),
         Action::AppletRpc(x) => x.run(CONNECTION.lock().unwrap().get()?),
-        Action::PlatformList => platform_list(flags.options.timeout),
+        Action::PlatformList => platform_list(flags.connection_options.timeout()),
         Action::PlatformUpdate => bail!("not implemented yet"),
         Action::PlatformReboot(x) => x.run(CONNECTION.lock().unwrap().get()?),
         Action::PlatformRpc(x) => x.run(CONNECTION.lock().unwrap().get()?),
@@ -132,33 +118,7 @@ fn main() -> Result<()> {
     }
 }
 
-enum GlobalConnection {
-    Invalid,
-    Ready { timeout: Duration, serial: Option<String> },
-    Connected { connection: Connection<GlobalContext> },
-}
-
-impl GlobalConnection {
-    fn set(&mut self, timeout: Duration, serial: Option<String>) {
-        match self {
-            GlobalConnection::Invalid => *self = GlobalConnection::Ready { timeout, serial },
-            _ => unreachable!(),
-        }
-    }
-
-    fn get(&mut self) -> Result<&Connection<GlobalContext>> {
-        if let GlobalConnection::Ready { timeout, serial } = self {
-            *self =
-                GlobalConnection::Connected { connection: connect(*timeout, serial.as_deref())? };
-        }
-        match self {
-            GlobalConnection::Connected { connection } => Ok(connection),
-            _ => unreachable!(),
-        }
-    }
-}
-
-static CONNECTION: Mutex<GlobalConnection> = Mutex::new(GlobalConnection::Invalid);
+static CONNECTION: Mutex<action::GlobalConnection> = Mutex::new(action::GlobalConnection::Invalid);
 
 fn platform_list(timeout: Duration) -> Result<()> {
     let context = GlobalContext::default();
@@ -174,35 +134,3 @@ fn platform_list(timeout: Duration) -> Result<()> {
     }
     Ok(())
 }
-
-fn connect(timeout: Duration, serial: Option<&str>) -> Result<Connection<GlobalContext>> {
-    let context = GlobalContext::default();
-    let mut candidates = wasefire_protocol_usb::list(&context)?;
-    let candidate = match (serial, candidates.len()) {
-        (None, 0) => bail!("no connected platforms"),
-        (None, 1) => candidates.pop().unwrap(),
-        (None, n) => {
-            eprintln!("Choose one of the {n} connected platforms using its --serial option:");
-            for candidate in candidates {
-                eprintln!("    --serial={}", get_serial(&candidate, timeout)?);
-            }
-            bail!("more than one connected platform");
-        }
-        (Some(serial), _) => {
-            match candidates
-                .into_iter()
-                .try_find(|x| anyhow::Ok(get_serial(x, timeout)? == serial))?
-            {
-                Some(x) => x,
-                None => bail!("no connected platform with serial={serial}"),
-            }
-        }
-    };
-    Ok(candidate.connect(timeout)?)
-}
-
-fn get_serial(candidate: &Candidate<GlobalContext>, timeout: Duration) -> Result<String> {
-    let connection = candidate.clone().connect(timeout)?;
-    let info = connection.call::<service::PlatformInfo>(())?;
-    Ok(HEX.encode(info.get().serial))
-}