Restructure with workspace

nut-client/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "nut-client"
+version = "0.0.4"
+authors = ["Aram Peres <aram.peres@wavy.fm>"]
+edition = "2018"
+description = "Network UPS Tools (NUT) client library"
+categories = ["network-programming"]
+keywords = ["ups", "nut"]
+repository = "https://github.com/aramperes/nut-client-rs"
+documentation = "https://docs.rs/nut-client"
+readme = "../README.md"
+license = "MIT"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+shell-words = "1.0.0"
+dotenv = { version = "0.15.0", optional = true }
+
+[features]
+env-file = ["dotenv"]

nut-client/examples/blocking.rs

@@ -0,0 +1,40 @@
+use std::env;
+use std::net::ToSocketAddrs;
+
+use nut_client::blocking::Connection;
+use nut_client::{Auth, ConfigBuilder, Host};
+
+fn main() -> nut_client::Result<()> {
+    let addr = env::var("NUT_ADDR")
+        .unwrap_or_else(|_| "localhost:3493".into())
+        .to_socket_addrs()
+        .unwrap()
+        .next()
+        .unwrap();
+
+    let username = env::var("NUT_USER").ok();
+    let password = env::var("NUT_PASSWORD").ok();
+    let auth = username.map(|username| Auth::new(username, password));
+
+    let config = ConfigBuilder::new()
+        .with_host(Host::Tcp(addr))
+        .with_auth(auth)
+        .build();
+
+    let mut conn = Connection::new(config)?;
+
+    // Print a list of all UPS devices
+    println!("Connected UPS devices:");
+    for (name, description) in conn.list_ups()? {
+        println!("\t- Name: {}", name);
+        println!("\t  Description: {}", description);
+
+        // List UPS variables (key = val)
+        println!("\t  Variables:");
+        for var in conn.list_vars(&name)? {
+            println!("\t\t- {}", var);
+        }
+    }
+
+    Ok(())
+}

nut-client/src/blocking/mod.rs

@@ -0,0 +1,159 @@
+use std::io;
+use std::io::{BufRead, BufReader, Write};
+use std::net::{SocketAddr, TcpStream};
+
+use crate::cmd::{Command, Response};
+use crate::{ClientError, Config, Host, NutError, Variable};
+
+/// A blocking NUT client connection.
+pub enum Connection {
+    /// A TCP connection.
+    Tcp(TcpConnection),
+}
+
+impl Connection {
+    /// Initializes a connection to a NUT server (upsd).
+    pub fn new(config: Config) -> crate::Result<Self> {
+        match &config.host {
+            Host::Tcp(socket_addr) => {
+                Ok(Self::Tcp(TcpConnection::new(config.clone(), socket_addr)?))
+            }
+        }
+    }
+
+    /// Queries a list of UPS devices.
+    pub fn list_ups(&mut self) -> crate::Result<Vec<(String, String)>> {
+        match self {
+            Self::Tcp(conn) => conn.list_ups(),
+        }
+    }
+
+    /// Queries the list of variables for a UPS device.
+    pub fn list_vars(&mut self, ups_name: &str) -> crate::Result<Vec<Variable>> {
+        match self {
+            Self::Tcp(conn) => Ok(conn
+                .list_vars(ups_name)?
+                .into_iter()
+                .map(|(key, val)| Variable::parse(key.as_str(), val))
+                .collect()),
+        }
+    }
+}
+
+/// A blocking TCP NUT client connection.
+#[derive(Debug)]
+pub struct TcpConnection {
+    config: Config,
+    tcp_stream: TcpStream,
+}
+
+impl TcpConnection {
+    fn new(config: Config, socket_addr: &SocketAddr) -> crate::Result<Self> {
+        // Create the TCP connection
+        let tcp_stream = TcpStream::connect_timeout(socket_addr, config.timeout)?;
+        let mut connection = Self { config, tcp_stream };
+
+        // Attempt login using `config.auth`
+        connection.login()?;
+
+        Ok(connection)
+    }
+
+    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()?;
+
+            // 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()?;
+            }
+        }
+        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"])?;
+
+        Ok(list
+            .into_iter()
+            .map(|mut row| (row.remove(0), row.remove(0)))
+            .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)?;
+
+        Ok(list
+            .into_iter()
+            .map(|mut row| (row.remove(0), row.remove(0)))
+            .collect())
+    }
+
+    fn write_cmd(stream: &mut TcpStream, line: Command) -> crate::Result<()> {
+        let line = format!("{}\n", line);
+        stream.write_all(line.as_bytes())?;
+        stream.flush()?;
+        Ok(())
+    }
+
+    fn parse_line(reader: &mut BufReader<&mut TcpStream>) -> crate::Result<Vec<String>> {
+        let mut raw = String::new();
+        reader.read_line(&mut raw)?;
+        raw = raw[..raw.len() - 1].to_string(); // Strip off \n
+
+        // Parse args by splitting whitespace, minding quotes for args with multiple words
+        let args = shell_words::split(&raw)
+            .map_err(|e| NutError::Generic(format!("Parsing server response failed: {}", e)))?;
+
+        Ok(args)
+    }
+
+    fn read_response(stream: &mut TcpStream) -> crate::Result<Response> {
+        let mut reader = io::BufReader::new(stream);
+        let args = Self::parse_line(&mut reader)?;
+        Response::from_args(args)
+    }
+
+    fn read_list(stream: &mut TcpStream, query: &[&str]) -> crate::Result<Vec<Vec<String>>> {
+        let mut reader = io::BufReader::new(stream);
+        let args = Self::parse_line(&mut reader)?;
+
+        Response::from_args(args)?.expect_begin_list(query)?;
+        let mut lines: Vec<Vec<String>> = Vec::new();
+
+        loop {
+            let mut args = Self::parse_line(&mut reader)?;
+            let resp = Response::from_args(args.clone());
+
+            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);
+                }
+            }
+        }
+        Ok(lines)
+    }
+}

nut-client/src/cmd.rs

@@ -0,0 +1,148 @@
+use core::fmt;
+
+use crate::NutError;
+
+#[derive(Debug, Clone)]
+pub enum Command<'a> {
+    /// Passes the login username.
+    SetUsername(&'a str),
+    /// Passes the login password.
+    SetPassword(&'a str),
+    /// Queries for a list. Allows for any number of arguments, which forms a single query.
+    List(&'a [&'a str]),
+}
+
+impl<'a> Command<'a> {
+    /// The network identifier of the command.
+    pub fn name(&self) -> &'static str {
+        match self {
+            Self::SetUsername(_) => "USERNAME",
+            Self::SetPassword(_) => "PASSWORD",
+            Self::List(_) => "LIST",
+        }
+    }
+
+    /// The arguments of the command to serialize.
+    pub fn args(&self) -> Vec<&str> {
+        match self {
+            Self::SetUsername(username) => vec![username],
+            Self::SetPassword(password) => vec![password],
+            Self::List(query) => query.to_vec(),
+        }
+    }
+}
+
+impl<'a> fmt::Display for Command<'a> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let mut args = self.args();
+        args.insert(0, self.name());
+        write!(f, "{}", shell_words::join(args))
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum Response {
+    /// A successful response.
+    Ok,
+    /// Marks the beginning of a list response.
+    BeginList(String),
+    /// Marks the end of a list response.
+    EndList(String),
+}
+
+impl Response {
+    pub fn from_args(mut args: Vec<String>) -> crate::Result<Response> {
+        if args.is_empty() {
+            return Err(
+                NutError::Generic("Parsing server response failed: empty line".into()).into(),
+            );
+        }
+        let cmd_name = args.remove(0);
+        match cmd_name.as_str() {
+            "OK" => Ok(Self::Ok),
+            "ERR" => {
+                if args.is_empty() {
+                    Err(NutError::Generic("Unspecified server error".into()).into())
+                } else {
+                    let err_type = args.remove(0);
+                    match err_type.as_str() {
+                        "ACCESS-DENIED" => Err(NutError::AccessDenied.into()),
+                        "UNKNOWN-UPS" => Err(NutError::UnknownUps.into()),
+                        _ => Err(NutError::Generic(format!(
+                            "Server error: {} {}",
+                            err_type,
+                            args.join(" ")
+                        ))
+                        .into()),
+                    }
+                }
+            }
+            "BEGIN" => {
+                if args.is_empty() {
+                    Err(NutError::Generic("Unspecified BEGIN type".into()).into())
+                } else {
+                    let begin_type = args.remove(0);
+                    if &begin_type != "LIST" {
+                        Err(
+                            NutError::Generic(format!("Unexpected BEGIN type: {}", begin_type))
+                                .into(),
+                        )
+                    } else {
+                        let args = shell_words::join(args);
+                        Ok(Response::BeginList(args))
+                    }
+                }
+            }
+            "END" => {
+                if args.is_empty() {
+                    Err(NutError::Generic("Unspecified END type".into()).into())
+                } else {
+                    let begin_type = args.remove(0);
+                    if &begin_type != "LIST" {
+                        Err(
+                            NutError::Generic(format!("Unexpected END type: {}", begin_type))
+                                .into(),
+                        )
+                    } else {
+                        let args = shell_words::join(args);
+                        Ok(Response::EndList(args))
+                    }
+                }
+            }
+            _ => Err(NutError::UnknownResponseType(cmd_name).into()),
+        }
+    }
+
+    pub fn expect_ok(&self) -> crate::Result<&Response> {
+        match self {
+            Self::Ok => Ok(self),
+            _ => Err(NutError::UnexpectedResponse.into()),
+        }
+    }
+
+    pub fn expect_begin_list(self, expected_args: &[&str]) -> crate::Result<Response> {
+        let expected_args = shell_words::join(expected_args);
+        if let Self::BeginList(args) = &self {
+            if &expected_args == args {
+                Ok(self)
+            } else {
+                Err(NutError::UnexpectedResponse.into())
+            }
+        } else {
+            Err(NutError::UnexpectedResponse.into())
+        }
+    }
+
+    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())
+            }
+        } else {
+            Err(NutError::UnexpectedResponse.into())
+        }
+    }
+}

nut-client/src/config.rs

@@ -0,0 +1,109 @@
+use core::fmt;
+use std::net::{SocketAddr, ToSocketAddrs};
+use std::time::Duration;
+
+/// A host specification.
+#[derive(Clone, Debug)]
+pub enum Host {
+    /// A TCP hostname and port.
+    Tcp(SocketAddr),
+    // TODO: Support Unix socket streams.
+}
+
+impl Default for Host {
+    fn default() -> Self {
+        let addr = (String::from("localhost"), 3493)
+            .to_socket_addrs()
+            .expect("Failed to create local UPS socket address. This is a bug.")
+            .next()
+            .expect("Failed to create local UPS socket address. This is a bug.");
+        Self::Tcp(addr)
+    }
+}
+
+/// An authentication mechanism.
+#[derive(Clone)]
+pub struct Auth {
+    /// The username of the user to login as.
+    pub(crate) username: String,
+    /// Optional password assigned to the remote user.
+    pub(crate) password: Option<String>,
+}
+
+impl Auth {
+    /// Initializes authentication credentials with a username, and optionally a password.
+    pub fn new(username: String, password: Option<String>) -> Self {
+        Auth { username, password }
+    }
+}
+
+impl fmt::Debug for Auth {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Auth")
+            .field("username", &self.username)
+            .field("password", &self.password.as_ref().map(|_| "(redacted)"))
+            .finish()
+    }
+}
+
+/// Configuration for connecting to a remote NUT server.
+#[derive(Clone, Debug)]
+pub struct Config {
+    pub(crate) host: Host,
+    pub(crate) auth: Option<Auth>,
+    pub(crate) timeout: Duration,
+}
+
+impl Config {
+    /// Creates a connection configuration.
+    pub fn new(host: Host, auth: Option<Auth>, timeout: Duration) -> Self {
+        Config {
+            host,
+            auth,
+            timeout,
+        }
+    }
+}
+
+/// A builder for [`Config`].
+#[derive(Clone, Debug, Default)]
+pub struct ConfigBuilder {
+    host: Option<Host>,
+    auth: Option<Auth>,
+    timeout: Option<Duration>,
+}
+
+impl ConfigBuilder {
+    /// Initializes an empty builder for [`Config`].
+    pub fn new() -> Self {
+        ConfigBuilder::default()
+    }
+
+    /// Sets the connection host, such as the TCP address and port.
+    pub fn with_host(mut self, host: Host) -> Self {
+        self.host = Some(host);
+        self
+    }
+
+    /// Sets the optional authentication parameters.
+    pub fn with_auth(mut self, auth: Option<Auth>) -> Self {
+        self.auth = auth;
+        self
+    }
+
+    /// Sets the network connection timeout. This may be ignored by non-network
+    /// connections, such as Unix domain sockets.
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = Some(timeout);
+        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)),
+        )
+    }
+}

nut-client/src/error.rs

@@ -0,0 +1,66 @@
+use core::fmt;
+use std::io;
+
+/// A NUT-native error.
+#[derive(Debug)]
+pub enum NutError {
+    /// Occurs when the username/password combination is rejected.
+    AccessDenied,
+    /// Occurs when the specified UPS device does not exist.
+    UnknownUps,
+    /// Occurs when the response type or content wasn't expected at the current stage.
+    UnexpectedResponse,
+    /// Occurs when the response type is not recognized by the client.
+    UnknownResponseType(String),
+    /// Generic (usually internal) client error.
+    Generic(String),
+}
+
+impl fmt::Display for NutError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::AccessDenied => write!(f, "Authentication failed"),
+            Self::UnknownUps => write!(f, "Unknown UPS device name"),
+            Self::UnexpectedResponse => write!(f, "Unexpected server response content"),
+            Self::UnknownResponseType(ty) => write!(f, "Unknown response type: {}", ty),
+            Self::Generic(msg) => write!(f, "Internal client error: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for NutError {}
+
+/// Encapsulation for errors emitted by the client library.
+#[derive(Debug)]
+pub enum ClientError {
+    /// Encapsulates IO errors.
+    Io(io::Error),
+    /// Encapsulates NUT and client-specific errors.
+    Nut(NutError),
+}
+
+impl fmt::Display for ClientError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Io(err) => err.fmt(f),
+            Self::Nut(err) => err.fmt(f),
+        }
+    }
+}
+
+impl std::error::Error for ClientError {}
+
+impl From<io::Error> for ClientError {
+    fn from(err: io::Error) -> Self {
+        ClientError::Io(err)
+    }
+}
+
+impl From<NutError> for ClientError {
+    fn from(err: NutError) -> Self {
+        ClientError::Nut(err)
+    }
+}
+
+/// Result type for [`ClientError`]
+pub type Result<T> = std::result::Result<T, ClientError>;

nut-client/src/lib.rs

@@ -0,0 +1,18 @@
+#![deny(missing_docs)]
+
+//! # nut-client
+//!
+//! The `nut-client` crate provides a network client implementation
+//! for Network UPS Tools (NUT) servers.
+
+pub use config::*;
+pub use error::*;
+pub use var::*;
+
+/// Blocking client implementation for NUT.
+pub mod blocking;
+
+mod cmd;
+mod config;
+mod error;
+mod var;

nut-client/src/var.rs

@@ -0,0 +1,149 @@
+use core::fmt;
+use std::time::Duration;
+
+/// Well-known variable keys for NUT UPS devices.
+///
+/// List retrieved from: https://networkupstools.org/docs/user-manual.chunked/apcs01.html
+pub mod key {
+    /// Device model.
+    pub const DEVICE_MODEL: &str = "device.model";
+    /// Device manufacturer.
+    pub const DEVICE_MANUFACTURER: &str = "device.mfr";
+    /// Device serial number.
+    pub const DEVICE_SERIAL: &str = "device.serial";
+    /// Device type.
+    pub const DEVICE_TYPE: &str = "device.type";
+    /// Device description.
+    pub const DEVICE_DESCRIPTION: &str = "device.description";
+    /// Device administrator name.
+    pub const DEVICE_CONTACT: &str = "device.contact";
+    /// Device physical location.
+    pub const DEVICE_LOCATION: &str = "device.location";
+    /// Device part number.
+    pub const DEVICE_PART: &str = "device.part";
+    /// Device MAC address.
+    pub const DEVICE_MAC_ADDRESS: &str = "device.macaddr";
+    /// Device uptime.
+    pub const DEVICE_UPTIME: &str = "device.uptime";
+}
+
+/// Well-known variables for NUT UPS devices.
+///
+/// List retrieved from: https://networkupstools.org/docs/user-manual.chunked/apcs01.html
+#[derive(Debug, Clone)]
+pub enum Variable {
+    /// Device model.
+    DeviceModel(String),
+    /// Device manufacturer.
+    DeviceManufacturer(String),
+    /// Device serial number.
+    DeviceSerial(String),
+    /// Device type.
+    DeviceType(DeviceType),
+    /// Device description.
+    DeviceDescription(String),
+    /// Device administrator name.
+    DeviceContact(String),
+    /// Device physical location.
+    DeviceLocation(String),
+    /// Device part number.
+    DevicePart(String),
+    /// Device MAC address.
+    DeviceMacAddress(String),
+    /// Device uptime.
+    DeviceUptime(Duration),
+
+    /// Any other variable. Value is a tuple of (key, value).
+    Other((String, String)),
+}
+
+impl Variable {
+    /// Parses a variable from its key and value.
+    pub fn parse(name: &str, value: String) -> Variable {
+        use self::key::*;
+
+        match name {
+            DEVICE_MODEL => Self::DeviceModel(value),
+            DEVICE_MANUFACTURER => Self::DeviceManufacturer(value),
+            DEVICE_SERIAL => Self::DeviceSerial(value),
+            DEVICE_TYPE => Self::DeviceType(DeviceType::from(value)),
+            DEVICE_DESCRIPTION => Self::DeviceDescription(value),
+            DEVICE_CONTACT => Self::DeviceContact(value),
+            DEVICE_LOCATION => Self::DeviceLocation(value),
+            DEVICE_PART => Self::DevicePart(value),
+            DEVICE_MAC_ADDRESS => Self::DeviceMacAddress(value),
+            DEVICE_UPTIME => Self::DeviceUptime(Duration::from_secs(
+                value.parse().expect("invalid uptime value"),
+            )),
+
+            _ => Self::Other((name.into(), value)),
+        }
+    }
+}
+
+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),
+        }
+    }
+}
+
+/// NUT device type.
+#[derive(Debug, Clone)]
+pub enum DeviceType {
+    /// UPS (Uninterruptible Power Supply)
+    Ups,
+    /// PDU (Power Distribution Unit)
+    Pdu,
+    /// SCD (Solar Controller Device)
+    Scd,
+    /// PSU (Power Supply Unit)
+    Psu,
+    /// ATS (Automatic Transfer Switch)
+    Ats,
+    /// Other device type.
+    Other(String),
+}
+
+impl DeviceType {
+    /// Convert from string.
+    pub fn from(v: String) -> DeviceType {
+        match v.as_str() {
+            "ups" => Self::Ups,
+            "pdu" => Self::Pdu,
+            "scd" => Self::Scd,
+            "psu" => Self::Psu,
+            "ats" => Self::Ats,
+            _ => Self::Other(v),
+        }
+    }
+}
+
+impl fmt::Display for DeviceType {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Ups => write!(f, "ups"),
+            Self::Pdu => write!(f, "pdu"),
+            Self::Scd => write!(f, "scd"),
+            Self::Psu => write!(f, "psu"),
+            Self::Ats => write!(f, "ats"),
+            Self::Other(val) => write!(f, "other({})", val),
+        }
+    }
+}