mostly docs, some code tweaks as well (#31)

Db background tasks never shutdown o_O

src/cmd/set.rs

@@ -5,57 +5,127 @@ use bytes::Bytes;
 use std::time::Duration;
 use tracing::{debug, instrument};
 
+/// Set `key` to hold the string `value`.
+///
+/// If `key` already holds a value, it is overwritten, regardless of its type.
+/// Any previous time to live associated with the key is discarded on successful
+/// SET operation.
+///
+/// # Options
+///
+/// Currently, the following options are supported:
+///
+/// * EX `seconds` -- Set the specified expire time, in seconds.
+/// * PX `milliseconds` -- Set the specified expire time, in milliseconds.
 #[derive(Debug)]
 pub struct Set {
     /// the lookup key
-    pub(crate) key: String,
+    key: String,
 
     /// the value to be stored
-    pub(crate) value: Bytes,
+    value: Bytes,
 
     /// When to expire the key
-    pub(crate) expire: Option<Duration>,
+    expire: Option<Duration>,
 }
 
 impl Set {
-    #[instrument]
-    pub(crate) fn parse_frames(parse: &mut Parse) -> Result<Set, ParseError> {
+    /// Create a new `Set` command which sets `key` to `value`.
+    ///
+    /// If `expire` is `Some`, the value should expire after the specified
+    /// duration.
+    pub(crate) fn new(key: impl ToString, value: Bytes, expire: Option<Duration>) -> Set {
+        Set {
+            key: key.to_string(),
+            value,
+            expire,
+        }
+    }
+
+    /// Parse a `Set` instance from received data.
+    ///
+    /// The `Parse` argument provides a cursor like API to read fields from a
+    /// received `Frame`. At this point, the data has already been received from
+    /// the socket.
+    ///
+    /// The `SET` string has already been consumed.
+    ///
+    /// # Returns
+    ///
+    /// Returns the `Set` value on success. If the frame is malformed, `Err` is
+    /// returned.
+    ///
+    /// # Format
+    ///
+    /// Expects an array frame containing at least 3 entries.
+    ///
+    /// ```text
+    /// SET key value [EX seconds|PX milliseconds]
+    /// ```
+    pub(crate) fn parse_frames(parse: &mut Parse) -> crate::Result<Set> {
         use ParseError::EndOfStream;
 
+        // Read the key to set. This is a required field
         let key = parse.next_string()?;
+
+        // Read the value to set. This is a required field.
         let value = parse.next_bytes()?;
+
+        // The expiration is optional. If nothing else follows, then it is
+        // `None`.
         let mut expire = None;
 
+        // Attempt to parse another string.
         match parse.next_string() {
             Ok(s) if s == "EX" => {
+                // An expiration is specified in seconds. The next value is an
+                // integer.
                 let secs = parse.next_int()?;
                 expire = Some(Duration::from_secs(secs));
             }
             Ok(s) if s == "PX" => {
+                // An expiration is specified in milliseconds. The next value is
+                // an integer.
                 let ms = parse.next_int()?;
                 expire = Some(Duration::from_millis(ms));
             }
-            Ok(_) => unimplemented!(),
+            // Currently, mini-redis does not support any of the other SET
+            // options. An error here results in the connection being
+            // terminated. Other connections will continue to operate normally.
+            Ok(_) => return Err("currently `SET` only supports the expiration option".into()),
+            // The `EndOfStream` error indicates there is no further data to
+            // parse. In this case, it is a normal run time situation and
+            // indicates there are no specified `SET` options.
             Err(EndOfStream) => {}
-            Err(err) => return Err(err),
+            // All other errors are bubbled up, resulting in the connection
+            // being terminated.
+            Err(err) => return Err(err.into()),
         }
 
-        debug!(?key, ?value, ?expire);
-
         Ok(Set { key, value, expire })
     }
 
-    #[instrument(skip(db))]
+    /// Apply the `Get` command to the specified `Db` instace.
+    ///
+    /// The response is written to `dst`. This is called by the server in order
+    /// to execute a received command.
+    #[instrument(skip(self, db, dst))]
     pub(crate) async fn apply(self, db: &Db, dst: &mut Connection) -> crate::Result<()> {
-        // Set the value
+        // Set the value in the shared database state.
         db.set(self.key, self.value, self.expire);
 
+        // Create a success response and write it to `dst`.
         let response = Frame::Simple("OK".to_string());
         debug!(?response);
         dst.write_frame(&response).await?;
+
         Ok(())
     }
 
+    /// Converts the command into an equivalent `Frame`.
+    ///
+    /// This is called by the client when encoding a `Set` command to send to
+    /// the server.
     pub(crate) fn into_frame(self) -> Frame {
         let mut frame = Frame::array();
         frame.push_bulk(Bytes::from("set".as_bytes()));