Add library error handling

Author: nlopes

README.md

@@ -131,7 +131,8 @@ data.insert("payload_length".to_string(), json!(27));
 
 let mut ev = client.new_event();
 ev.add(data);
-ev.send(&mut client);
+ // In production code, please check return of `.send()`
+ev.send(&mut client).err();
 ```
 
 [API reference]: https://docs.rs/libhoney-rust

examples/client.rs

@@ -1,24 +1,32 @@
 use env_logger;
+use log;
 
 use libhoney;
+use libhoney::Error;
 use libhoney::FieldHolder;
 
-fn main() {
+fn main() -> Result<(), Error> {
     env_logger::init();
 
     let mut client = libhoney::init(libhoney::Config {
         options: libhoney::client::Options {
-            api_key: std::env::var("HONEYCOMB_API_KEY").unwrap(),
-            dataset: std::env::var("HONEYCOMB_DATASET").unwrap(),
+            api_key: std::env::var("HONEYCOMB_API_KEY").expect("need to set HONEYCOMB_API_KEY"),
+            dataset: std::env::var("HONEYCOMB_DATASET").expect("need to set HONEYCOMB_DATASET"),
             ..Default::default()
         },
         transmission_options: libhoney::transmission::Options::default(),
     });
     let mut event = client.new_event();
     event.add_field("extra", libhoney::Value::String("wheeee".to_string()));
     event.add_field("extra_ham", libhoney::Value::String("cheese".to_string()));
-    event.send(&mut client);
-    let response = client.responses().iter().next().unwrap();
-    assert_eq!(response.error, None);
-    client.close();
+    match event.send(&mut client) {
+        Ok(()) => {
+            let response = client.responses().iter().next().unwrap();
+            assert_eq!(response.error, None);
+        }
+        Err(e) => {
+            log::error!("Could not send event: {}", e);
+        }
+    }
+    client.close()
 }

src/builder.rs

@@ -3,15 +3,32 @@ use std::collections::HashMap;
 use serde_json::Value;
 
 use crate::client::Options;
+use crate::errors::Result;
 use crate::event::Event;
 use crate::fields::FieldHolder;
 
 /// Shorthand type for the function to be passed to the `add_dynamic_field` calls
 pub type DynamicFieldFunc = fn() -> Value;
 
 impl FieldHolder for Builder {
-    fn get_fields(&mut self) -> &mut HashMap<String, Value> {
-        &mut self.fields
+    fn add(&mut self, data: HashMap<String, Value>) {
+        self.fields.extend(data);
+    }
+
+    /// add_field adds a field to the current (event/builder) fields
+    fn add_field(&mut self, name: &str, value: Value) {
+        self.fields.insert(name.to_string(), value);
+    }
+
+    /// add_func iterates over the results from func (until Err) and adds the results to
+    /// the event/builder fields
+    fn add_func<F>(&mut self, func: F)
+    where
+        F: Fn() -> Result<(String, Value)>,
+    {
+        while let Ok((name, value)) = func() {
+            self.add_field(&name, value);
+        }
     }
 }
 

src/client.rs

@@ -7,6 +7,7 @@ use crossbeam_channel::Receiver;
 use log::info;
 use serde_json::Value;
 
+use crate::errors::Result;
 use crate::fields::FieldHolder;
 use crate::response::Response;
 use crate::Event;
@@ -109,9 +110,9 @@ impl Client {
 
     /// close waits for all in-flight messages to be sent. You should call close() before
     /// app termination.
-    pub fn close(mut self) {
+    pub fn close(mut self) -> Result<()> {
         info!("closing libhoney client");
-        self.transmission.stop();
+        self.transmission.stop()
     }
 
     /// flush closes and reopens the Transmission, ensuring events are sent without
@@ -120,10 +121,11 @@ impl Client {
     /// Flush if asynchronous sends are not guaranteed to run (i.e. running in AWS Lambda)
     /// Flush is not thread safe - use it only when you are sure that no other parts of
     /// your program are calling Send
-    pub fn flush(&mut self) {
+    pub fn flush(&mut self) -> Result<()> {
         info!("flushing libhoney client");
-        self.transmission.stop();
+        self.transmission.stop()?;
         self.transmission.start();
+        Ok(())
     }
 
     /// new_builder creates a new event builder. The builder inherits any Dynamic or
@@ -146,16 +148,16 @@ impl Client {
 
 #[cfg(test)]
 mod tests {
-    use super::*;
+    use super::{Client, FieldHolder, Options, Transmission, Value};
     use crate::transmission;
 
     #[test]
     fn test_init() {
         let client = Client::new(
             Options::default(),
-            Transmission::new(transmission::Options::default()),
+            Transmission::new(transmission::Options::default()).unwrap(),
         );
-        client.close();
+        client.close().unwrap();
     }
 
     #[test]
@@ -179,36 +181,37 @@ mod tests {
                 api_host: api_host.to_string(),
                 ..Options::default()
             },
-            Transmission::new(transmission::Options::default()),
+            Transmission::new(transmission::Options::default()).unwrap(),
         );
 
         let mut event = client.new_event();
         event.add_field("some_field", Value::String("some_value".to_string()));
         event.metadata = Some(json!("some metadata in a string"));
-        event.send(&mut client);
+        event.send(&mut client).unwrap();
 
         let response = client.responses().iter().next().unwrap();
         assert_eq!(response.status_code, Some(StatusCode::ACCEPTED));
         assert_eq!(response.metadata, Some(json!("some metadata in a string")));
 
-        client.flush();
+        client.flush().unwrap();
 
         event = client.new_event();
         event.add_field("some_field", Value::String("some_value".to_string()));
         event.metadata = Some(json!("some metadata in a string"));
-        event.send(&mut client);
+        event.send(&mut client).unwrap();
 
         let response = client.responses().iter().next().unwrap();
         assert_eq!(response.status_code, Some(StatusCode::ACCEPTED));
         assert_eq!(response.metadata, Some(json!("some metadata in a string")));
 
-        client.close();
+        client.close().unwrap();
     }
 
     #[test]
     fn test_send_without_api_key() {
         use serde_json::json;
-        use std::time::Duration;
+
+        use crate::errors::ErrorKind;
 
         let api_host = &mockito::server_url();
         let _m = mockito::mock(
@@ -225,17 +228,19 @@ mod tests {
                 api_host: api_host.to_string(),
                 ..Options::default()
             },
-            Transmission::new(transmission::Options::default()),
+            Transmission::new(transmission::Options::default()).unwrap(),
         );
 
         let mut event = client.new_event();
         event.add_field("some_field", Value::String("some_value".to_string()));
         event.metadata = Some(json!("some metadata in a string"));
-        event.send(&mut client);
-        client
-            .responses()
-            .recv_timeout(Duration::from_millis(100))
-            .err();
-        client.close();
+        let err = event.send(&mut client).err().unwrap();
+
+        assert_eq!(err.kind, ErrorKind::MissingOption);
+        assert_eq!(
+            err.message,
+            "missing option 'api_key', can't send to Honeycomb"
+        );
+        client.close().unwrap();
     }
 }

src/errors.rs

@@ -0,0 +1,92 @@
+use std::error::Error as _;
+use std::fmt;
+use std::io;
+
+/// Result shorthand for a `std::result::Result` wrapping our own `Error`
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Type of error, exposed through `Error` member `kind`
+#[derive(Debug, Copy, Clone, PartialEq)]
+pub enum ErrorKind {
+    /// Event has no populated fields
+    MissingEventFields,
+
+    /// Mandatory client/transmission Option is missing
+    MissingOption,
+
+    /// User Func error
+    UserFuncError,
+
+    /// Sender full
+    ChannelError,
+
+    /// Any IO related error
+    Io,
+}
+
+/// Error
+#[derive(Debug)]
+pub struct Error {
+    /// Error message
+    pub message: String,
+    /// Type of error
+    pub kind: ErrorKind,
+}
+
+impl Error {
+    #[doc(hidden)]
+    pub(crate) fn missing_event_fields() -> Self {
+        Self {
+            message: String::from("event has no data"),
+            kind: ErrorKind::MissingEventFields,
+        }
+    }
+
+    #[doc(hidden)]
+    pub(crate) fn missing_option(option: &str, extra: &str) -> Self {
+        Self {
+            message: format!("missing option '{}', {}", option, extra),
+            kind: ErrorKind::MissingOption,
+        }
+    }
+
+    #[doc(hidden)]
+    pub(crate) fn sender_full(sender: &str) -> Self {
+        Self {
+            message: format!("sender '{}' is full", sender),
+            kind: ErrorKind::ChannelError,
+        }
+    }
+
+    #[doc(hidden)]
+    pub(crate) fn with_description(description: &str, kind: ErrorKind) -> Self {
+        Error {
+            message: format!("error: {}", description),
+            kind,
+        }
+    }
+}
+
+impl std::error::Error for Error {
+    fn description(&self) -> &str {
+        &*self.message
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        writeln!(f, "{}", self.message)
+    }
+}
+
+impl From<io::Error> for Error {
+    fn from(e: io::Error) -> Self {
+        Error::with_description(e.description(), ErrorKind::Io)
+    }
+}
+
+impl<T> From<crossbeam_channel::SendError<T>> for Error {
+    fn from(e: crossbeam_channel::SendError<T>) -> Self {
+        Error::with_description(&e.to_string(), ErrorKind::ChannelError)
+    }
+}