Implement rupsc, clone of upsc (#5)

Fixes #4

nut-client/examples/blocking.rs

@@ -19,6 +19,7 @@ fn main() -> nut_client::Result<()> {
     let config = ConfigBuilder::new()
         .with_host(Host::Tcp(addr))
         .with_auth(auth)
+        .with_debug(false) // Turn this on for debugging network chatter
         .build();
 
     let mut conn = Connection::new(config)?;

nut-client/src/blocking/mod.rs

@@ -3,7 +3,7 @@ use std::io::{BufRead, BufReader, Write};
 use std::net::{SocketAddr, TcpStream};
 
 use crate::cmd::{Command, Response};
-use crate::{ClientError, Config, Host, NutError, Variable};
+use crate::{Config, Host, NutError, Variable};
 
 /// A blocking NUT client connection.
 pub enum Connection {
@@ -28,6 +28,13 @@ impl Connection {
         }
     }
 
+    /// Queries a list of client IP addresses connected to the given device.
+    pub fn list_clients(&mut self, ups_name: &str) -> crate::Result<Vec<String>> {
+        match self {
+            Self::Tcp(conn) => conn.list_clients(ups_name),
+        }
+    }
+
     /// Queries the list of variables for a UPS device.
     pub fn list_vars(&mut self, ups_name: &str) -> crate::Result<Vec<Variable>> {
         match self {
@@ -38,6 +45,16 @@ impl Connection {
                 .collect()),
         }
     }
+
+    /// Queries one variable for a UPS device.
+    pub fn get_var(&mut self, ups_name: &str, variable: &str) -> crate::Result<Variable> {
+        match self {
+            Self::Tcp(conn) => {
+                let var = conn.get_var(ups_name, variable)?;
+                Ok(Variable::parse(var.0.as_str(), var.1))
+            }
+        }
+    }
 }
 
 /// A blocking TCP NUT client connection.
@@ -62,49 +79,88 @@ impl TcpConnection {
     fn login(&mut self) -> crate::Result<()> {
         if let Some(auth) = &self.config.auth {
             // Pass username and check for 'OK'
-            Self::write_cmd(&mut self.tcp_stream, Command::SetUsername(&auth.username))?;
-            Self::read_response(&mut self.tcp_stream)?.expect_ok()?;
+            Self::write_cmd(
+                &mut self.tcp_stream,
+                Command::SetUsername(&auth.username),
+                self.config.debug,
+            )?;
+            Self::read_response(&mut self.tcp_stream, self.config.debug)?.expect_ok()?;
 
             // Pass password and check for 'OK'
             if let Some(password) = &auth.password {
-                Self::write_cmd(&mut self.tcp_stream, Command::SetPassword(password))?;
-                Self::read_response(&mut self.tcp_stream)?.expect_ok()?;
+                Self::write_cmd(
+                    &mut self.tcp_stream,
+                    Command::SetPassword(password),
+                    self.config.debug,
+                )?;
+                Self::read_response(&mut self.tcp_stream, self.config.debug)?.expect_ok()?;
             }
         }
         Ok(())
     }
 
     fn list_ups(&mut self) -> crate::Result<Vec<(String, String)>> {
-        Self::write_cmd(&mut self.tcp_stream, Command::List(&["UPS"]))?;
-        let list = Self::read_list(&mut self.tcp_stream, &["UPS"])?;
+        Self::write_cmd(
+            &mut self.tcp_stream,
+            Command::List(&["UPS"]),
+            self.config.debug,
+        )?;
+        let list = Self::read_list(&mut self.tcp_stream, &["UPS"], self.config.debug)?;
 
-        Ok(list
-            .into_iter()
-            .map(|mut row| (row.remove(0), row.remove(0)))
-            .collect())
+        list.into_iter().map(|row| row.expect_ups()).collect()
+    }
+
+    fn list_clients(&mut self, ups_name: &str) -> crate::Result<Vec<String>> {
+        let query = &["CLIENT", ups_name];
+        Self::write_cmd(
+            &mut self.tcp_stream,
+            Command::List(query),
+            self.config.debug,
+        )?;
+        let list = Self::read_list(&mut self.tcp_stream, query, self.config.debug)?;
+
+        list.into_iter().map(|row| row.expect_client()).collect()
     }
 
     fn list_vars(&mut self, ups_name: &str) -> crate::Result<Vec<(String, String)>> {
         let query = &["VAR", ups_name];
-        Self::write_cmd(&mut self.tcp_stream, Command::List(query))?;
-        let list = Self::read_list(&mut self.tcp_stream, query)?;
+        Self::write_cmd(
+            &mut self.tcp_stream,
+            Command::List(query),
+            self.config.debug,
+        )?;
+        let list = Self::read_list(&mut self.tcp_stream, query, self.config.debug)?;
 
-        Ok(list
-            .into_iter()
-            .map(|mut row| (row.remove(0), row.remove(0)))
-            .collect())
+        list.into_iter().map(|row| row.expect_var()).collect()
     }
 
-    fn write_cmd(stream: &mut TcpStream, line: Command) -> crate::Result<()> {
+    fn get_var(&mut self, ups_name: &str, variable: &str) -> crate::Result<(String, String)> {
+        let query = &["VAR", ups_name, variable];
+        Self::write_cmd(&mut self.tcp_stream, Command::Get(query), self.config.debug)?;
+
+        let resp = Self::read_response(&mut self.tcp_stream, self.config.debug)?;
+        resp.expect_var()
+    }
+
+    fn write_cmd(stream: &mut TcpStream, line: Command, debug: bool) -> crate::Result<()> {
         let line = format!("{}\n", line);
+        if debug {
+            eprint!("DEBUG -> {}", line);
+        }
         stream.write_all(line.as_bytes())?;
         stream.flush()?;
         Ok(())
     }
 
-    fn parse_line(reader: &mut BufReader<&mut TcpStream>) -> crate::Result<Vec<String>> {
+    fn parse_line(
+        reader: &mut BufReader<&mut TcpStream>,
+        debug: bool,
+    ) -> crate::Result<Vec<String>> {
         let mut raw = String::new();
         reader.read_line(&mut raw)?;
+        if debug {
+            eprint!("DEBUG <- {}", raw);
+        }
         raw = raw[..raw.len() - 1].to_string(); // Strip off \n
 
         // Parse args by splitting whitespace, minding quotes for args with multiple words
@@ -114,46 +170,35 @@ impl TcpConnection {
         Ok(args)
     }
 
-    fn read_response(stream: &mut TcpStream) -> crate::Result<Response> {
+    fn read_response(stream: &mut TcpStream, debug: bool) -> crate::Result<Response> {
         let mut reader = io::BufReader::new(stream);
-        let args = Self::parse_line(&mut reader)?;
+        let args = Self::parse_line(&mut reader, debug)?;
         Response::from_args(args)
     }
 
-    fn read_list(stream: &mut TcpStream, query: &[&str]) -> crate::Result<Vec<Vec<String>>> {
+    fn read_list(
+        stream: &mut TcpStream,
+        query: &[&str],
+        debug: bool,
+    ) -> crate::Result<Vec<Response>> {
         let mut reader = io::BufReader::new(stream);
-        let args = Self::parse_line(&mut reader)?;
+        let args = Self::parse_line(&mut reader, debug)?;
 
         Response::from_args(args)?.expect_begin_list(query)?;
-        let mut lines: Vec<Vec<String>> = Vec::new();
+        let mut lines: Vec<Response> = Vec::new();
 
         loop {
-            let mut args = Self::parse_line(&mut reader)?;
-            let resp = Response::from_args(args.clone());
+            let args = Self::parse_line(&mut reader, debug)?;
+            let resp = Response::from_args(args)?;
 
-            if let Ok(resp) = resp {
-                resp.expect_end_list(query)?;
-                break;
-            } else {
-                let err = resp.unwrap_err();
-                if let ClientError::Nut(err) = err {
-                    if let NutError::UnknownResponseType(_) = err {
-                        // Likely an item entry, let's check...
-                        if args.len() < query.len() || &args[0..query.len()] != query {
-                            return Err(ClientError::Nut(err));
-                        } else {
-                            let args = args.drain(query.len()..).collect();
-                            lines.push(args);
-                            continue;
-                        }
-                    } else {
-                        return Err(ClientError::Nut(err));
-                    }
-                } else {
-                    return Err(err);
+            match resp {
+                Response::EndList(_) => {
+                    break;
                 }
+                _ => lines.push(resp),
             }
         }
+
         Ok(lines)
     }
 }

nut-client/src/cmd.rs

@@ -1,9 +1,10 @@
 use core::fmt;
 
-use crate::NutError;
+use crate::{ClientError, NutError};
 
 #[derive(Debug, Clone)]
 pub enum Command<'a> {
+    Get(&'a [&'a str]),
     /// Passes the login username.
     SetUsername(&'a str),
     /// Passes the login password.
@@ -16,6 +17,7 @@ impl<'a> Command<'a> {
     /// The network identifier of the command.
     pub fn name(&self) -> &'static str {
         match self {
+            Self::Get(_) => "GET",
             Self::SetUsername(_) => "USERNAME",
             Self::SetPassword(_) => "PASSWORD",
             Self::List(_) => "LIST",
@@ -25,6 +27,7 @@ impl<'a> Command<'a> {
     /// The arguments of the command to serialize.
     pub fn args(&self) -> Vec<&str> {
         match self {
+            Self::Get(cmd) => cmd.to_vec(),
             Self::SetUsername(username) => vec![username],
             Self::SetPassword(password) => vec![password],
             Self::List(query) => query.to_vec(),
@@ -48,6 +51,18 @@ pub enum Response {
     BeginList(String),
     /// Marks the end of a list response.
     EndList(String),
+    /// A variable (VAR) response.
+    ///
+    /// Params: (var name, var value)
+    Var(String, String),
+    /// A UPS (UPS) response.
+    ///
+    /// Params: (device name, device description)
+    Ups(String, String),
+    /// A client (CLIENT) response.
+    ///
+    /// Params: (client IP)
+    Client(String),
 }
 
 impl Response {
@@ -109,6 +124,64 @@ impl Response {
                     }
                 }
             }
+            "VAR" => {
+                let _var_device = if args.is_empty() {
+                    Err(ClientError::from(NutError::Generic(
+                        "Unspecified VAR device name in response".into(),
+                    )))
+                } else {
+                    Ok(args.remove(0))
+                }?;
+                let var_name = if args.is_empty() {
+                    Err(ClientError::from(NutError::Generic(
+                        "Unspecified VAR name in response".into(),
+                    )))
+                } else {
+                    Ok(args.remove(0))
+                }?;
+                let var_value = if args.is_empty() {
+                    Err(ClientError::from(NutError::Generic(
+                        "Unspecified VAR value in response".into(),
+                    )))
+                } else {
+                    Ok(args.remove(0))
+                }?;
+                Ok(Response::Var(var_name, var_value))
+            }
+            "UPS" => {
+                let name = if args.is_empty() {
+                    Err(ClientError::from(NutError::Generic(
+                        "Unspecified UPS name in response".into(),
+                    )))
+                } else {
+                    Ok(args.remove(0))
+                }?;
+                let description = if args.is_empty() {
+                    Err(ClientError::from(NutError::Generic(
+                        "Unspecified UPS description in response".into(),
+                    )))
+                } else {
+                    Ok(args.remove(0))
+                }?;
+                Ok(Response::Ups(name, description))
+            }
+            "CLIENT" => {
+                let _device = if args.is_empty() {
+                    Err(ClientError::from(NutError::Generic(
+                        "Unspecified CLIENT device in response".into(),
+                    )))
+                } else {
+                    Ok(args.remove(0))
+                }?;
+                let ip_address = if args.is_empty() {
+                    Err(ClientError::from(NutError::Generic(
+                        "Unspecified CLIENT IP in response".into(),
+                    )))
+                } else {
+                    Ok(args.remove(0))
+                }?;
+                Ok(Response::Client(ip_address))
+            }
             _ => Err(NutError::UnknownResponseType(cmd_name).into()),
         }
     }
@@ -133,14 +206,25 @@ impl Response {
         }
     }
 
-    pub fn expect_end_list(self, expected_args: &[&str]) -> crate::Result<Response> {
-        let expected_args = shell_words::join(expected_args);
-        if let Self::EndList(args) = &self {
-            if &expected_args == args {
-                Ok(self)
-            } else {
-                Err(NutError::UnexpectedResponse.into())
-            }
+    pub fn expect_var(&self) -> crate::Result<(String, String)> {
+        if let Self::Var(name, value) = &self {
+            Ok((name.to_owned(), value.to_owned()))
+        } else {
+            Err(NutError::UnexpectedResponse.into())
+        }
+    }
+
+    pub fn expect_ups(&self) -> crate::Result<(String, String)> {
+        if let Self::Ups(name, description) = &self {
+            Ok((name.to_owned(), description.to_owned()))
+        } else {
+            Err(NutError::UnexpectedResponse.into())
+        }
+    }
+
+    pub fn expect_client(&self) -> crate::Result<String> {
+        if let Self::Client(client_ip) = &self {
+            Ok(client_ip.to_owned())
         } else {
             Err(NutError::UnexpectedResponse.into())
         }

nut-client/src/config.rs

@@ -12,7 +12,7 @@ pub enum Host {
 
 impl Default for Host {
     fn default() -> Self {
-        let addr = (String::from("localhost"), 3493)
+        let addr = (String::from("127.0.0.1"), 3493)
             .to_socket_addrs()
             .expect("Failed to create local UPS socket address. This is a bug.")
             .next()
@@ -21,6 +21,12 @@ impl Default for Host {
     }
 }
 
+impl From<SocketAddr> for Host {
+    fn from(addr: SocketAddr) -> Self {
+        Self::Tcp(addr)
+    }
+}
+
 /// An authentication mechanism.
 #[derive(Clone)]
 pub struct Auth {
@@ -52,15 +58,17 @@ pub struct Config {
     pub(crate) host: Host,
     pub(crate) auth: Option<Auth>,
     pub(crate) timeout: Duration,
+    pub(crate) debug: bool,
 }
 
 impl Config {
     /// Creates a connection configuration.
-    pub fn new(host: Host, auth: Option<Auth>, timeout: Duration) -> Self {
+    pub fn new(host: Host, auth: Option<Auth>, timeout: Duration, debug: bool) -> Self {
         Config {
             host,
             auth,
             timeout,
+            debug,
         }
     }
 }
@@ -71,6 +79,7 @@ pub struct ConfigBuilder {
     host: Option<Host>,
     auth: Option<Auth>,
     timeout: Option<Duration>,
+    debug: Option<bool>,
 }
 
 impl ConfigBuilder {
@@ -98,12 +107,19 @@ impl ConfigBuilder {
         self
     }
 
+    /// Enables debugging network calls by printing to stderr.
+    pub fn with_debug(mut self, debug: bool) -> Self {
+        self.debug = Some(debug);
+        self
+    }
+
     /// Builds the configuration with this builder.
     pub fn build(self) -> Config {
         Config::new(
             self.host.unwrap_or_default(),
             self.auth,
             self.timeout.unwrap_or_else(|| Duration::from_secs(5)),
+            self.debug.unwrap_or(false),
         )
     }
 }

nut-client/src/var.rs

@@ -79,28 +79,46 @@ impl Variable {
             _ => Self::Other((name.into(), value)),
         }
     }
+
+    /// Returns the NUT name of the variable.
+    pub fn name(&self) -> &str {
+        use self::key::*;
+        match self {
+            Self::DeviceModel(_) => DEVICE_MODEL,
+            Self::DeviceManufacturer(_) => DEVICE_MANUFACTURER,
+            Self::DeviceSerial(_) => DEVICE_SERIAL,
+            Self::DeviceType(_) => DEVICE_TYPE,
+            Self::DeviceDescription(_) => DEVICE_DESCRIPTION,
+            Self::DeviceContact(_) => DEVICE_CONTACT,
+            Self::DeviceLocation(_) => DEVICE_LOCATION,
+            Self::DevicePart(_) => DEVICE_PART,
+            Self::DeviceMacAddress(_) => DEVICE_MAC_ADDRESS,
+            Self::DeviceUptime(_) => DEVICE_UPTIME,
+            Self::Other((name, _)) => name.as_str(),
+        }
+    }
+
+    /// Returns the value of the NUT variable.
+    pub fn value(&self) -> String {
+        match self {
+            Self::DeviceModel(value) => value.clone(),
+            Self::DeviceManufacturer(value) => value.clone(),
+            Self::DeviceSerial(value) => value.clone(),
+            Self::DeviceType(value) => value.to_string(),
+            Self::DeviceDescription(value) => value.clone(),
+            Self::DeviceContact(value) => value.clone(),
+            Self::DeviceLocation(value) => value.clone(),
+            Self::DevicePart(value) => value.clone(),
+            Self::DeviceMacAddress(value) => value.clone(),
+            Self::DeviceUptime(value) => value.as_secs().to_string(),
+            Self::Other((_, value)) => value.clone(),
+        }
+    }
 }
 
 impl fmt::Display for Variable {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        use self::key::*;
-
-        match self {
-            Self::DeviceModel(value) => write!(f, "{} = {}", DEVICE_MODEL, value),
-            Self::DeviceManufacturer(value) => write!(f, "{} = {}", DEVICE_MANUFACTURER, value),
-            Self::DeviceSerial(value) => write!(f, "{} = {}", DEVICE_SERIAL, value),
-            Self::DeviceType(value) => write!(f, "{} = {}", DEVICE_TYPE, value),
-            Self::DeviceDescription(value) => write!(f, "{} = {}", DEVICE_DESCRIPTION, value),
-            Self::DeviceContact(value) => write!(f, "{} = {}", DEVICE_CONTACT, value),
-            Self::DeviceLocation(value) => write!(f, "{} = {}", DEVICE_LOCATION, value),
-            Self::DevicePart(value) => write!(f, "{} = {}", DEVICE_PART, value),
-            Self::DeviceMacAddress(value) => write!(f, "{} = {}", DEVICE_MAC_ADDRESS, value),
-            Self::DeviceUptime(value) => {
-                write!(f, "{} = {} seconds", DEVICE_UPTIME, value.as_secs())
-            }
-
-            Self::Other((key, value)) => write!(f, "other({}) = {}", key, value),
-        }
+        write!(f, "{}: {}", self.name(), self.value())
     }
 }