refactor basic types for cleaner code, better parsing

Author: dr-frmr

README.md

@@ -5,6 +5,7 @@ Library of functions for more ergonomic kinode process development.
 To develop/build:
 ```
 git submodule update --init
+cargo build
 ```
 
-Docs: (TODO link)
+Docs: waiting on other crates to be published.

src/eth.rs

@@ -92,9 +92,6 @@ pub enum EthError {
 
 /// The action type used for configuring eth:distro:sys. Only processes which have the "root"
 /// capability from eth:distro:sys can successfully send this action.
-///
-/// NOTE: changes to config will not be persisted between boots, they must be saved in .env
-/// to be reflected between boots. TODO: can change this
 #[derive(Debug, Serialize, Deserialize)]
 pub enum EthConfigAction {
     /// Add a new provider to the list of providers.

src/lib.rs

@@ -53,13 +53,13 @@ pub use types::{
     address::{Address, AddressParseError},
     capability::Capability,
     lazy_load_blob::LazyLoadBlob,
-    message::wit_message_to_message,
-    message::{Message, SendError, SendErrorKind},
+    message::{Message, _wit_message_to_message},
     on_exit::OnExit,
     package_id::PackageId,
     process_id::{ProcessId, ProcessIdParseError},
     request::Request,
     response::Response,
+    send_error::{SendError, SendErrorKind, _wit_send_error_to_send_error},
 };
 
 /// Implement the wit-bindgen specific code that the kernel uses to hook into
@@ -98,20 +98,24 @@ macro_rules! println {
 /// attempts to send a message to another node, that message may bounce back with
 /// a `SendError`. Those should be handled here.
 ///
-/// TODO: example of usage
+/// Example:
+/// ```
+/// loop {
+///     match await_message() {
+///         Ok(msg) => {
+///             println!("Received message: {:?}", msg);
+///             // Do something with the message
+///         }
+///         Err(send_error) => {
+///             println!("Error sending message: {:?}", send_error);
+///         }
+///     }
+/// }
+/// ```
 pub fn await_message() -> Result<Message, SendError> {
     match crate::receive() {
-        Ok((source, message)) => Ok(wit_message_to_message(source, message)),
-        Err((send_err, context)) => Err(SendError {
-            kind: match send_err.kind {
-                crate::kinode::process::standard::SendErrorKind::Offline => SendErrorKind::Offline,
-                crate::kinode::process::standard::SendErrorKind::Timeout => SendErrorKind::Timeout,
-            },
-            target: send_err.target.clone(),
-            message: wit_message_to_message(send_err.target, send_err.message),
-            lazy_load_blob: send_err.lazy_load_blob,
-            context,
-        }),
+        Ok((source, message)) => Ok(_wit_message_to_message(source, message)),
+        Err((send_err, context)) => Err(_wit_send_error_to_send_error(send_err, context)),
     }
 }
 
@@ -137,7 +141,10 @@ pub fn spawn(
 /// Create a blob with no MIME type and a generic type, plus a serializer
 /// function that turns that type into bytes.
 ///
-/// Example: TODO
+/// Example usage:
+/// ```
+/// make_blob(&my_type, |t| Ok(bincode::serialize(t)?));
+/// ```
 pub fn make_blob<T, F>(blob: &T, serializer: F) -> anyhow::Result<LazyLoadBlob>
 where
     F: Fn(&T) -> anyhow::Result<Vec<u8>>,

src/types/address.rs

@@ -2,7 +2,7 @@ pub use crate::{Address, PackageId, ProcessId};
 use serde::{Deserialize, Serialize};
 use std::hash::{Hash, Hasher};
 
-/// Address is defined in the wit bindings, but constructors and methods here.
+/// Address is defined in `kinode.wit`, but constructors and methods here.
 /// An `Address` is a combination of a node ID (string) and a [`ProcessId`]. It is
 /// used in the Request/Response pattern to indicate which process on a given node
 /// in the network to direct the message to. The formatting structure for
@@ -49,36 +49,42 @@ impl std::str::FromStr for Address {
     /// Attempt to parse an `Address` from a string. The formatting structure for
     /// an Address is `node@process_name:package_name:publisher_node`.
     ///
-    /// TODO: clarify if `@` can be present in process name / package name / publisher name
-    ///
-    /// TODO: ensure `:` cannot sneak into first segment
+    /// The string being parsed must contain exactly one `@` and three `:` characters.
+    /// The `@` character separates the node ID from the rest of the address, and the
+    /// `:` characters separate the process name, package name, and publisher node ID.
     fn from_str(input: &str) -> Result<Self, AddressParseError> {
-        // split string on colons into 4 segments,
-        // first one with @, next 3 with :
-        let mut name_rest = input.split('@');
-        let node = name_rest
-            .next()
-            .ok_or(AddressParseError::MissingField)?
-            .to_string();
-        let mut segments = name_rest
-            .next()
-            .ok_or(AddressParseError::MissingNodeId)?
-            .split(':');
-        let process_name = segments
-            .next()
-            .ok_or(AddressParseError::MissingField)?
-            .to_string();
-        let package_name = segments
-            .next()
-            .ok_or(AddressParseError::MissingField)?
-            .to_string();
-        let publisher_node = segments
-            .next()
-            .ok_or(AddressParseError::MissingField)?
-            .to_string();
-        if segments.next().is_some() {
+        // split string on '@' and ensure there is exactly one '@'
+        let parts: Vec<&str> = input.split('@').collect();
+        if parts.len() < 2 {
+            return Err(AddressParseError::MissingNodeId);
+        } else if parts.len() > 2 {
+            return Err(AddressParseError::TooManyAts);
+        }
+        let node = parts[0].to_string();
+        if node.is_empty() {
+            return Err(AddressParseError::MissingNodeId);
+        }
+
+        // split the rest on ':' and ensure there are exactly three ':'
+        let segments: Vec<&str> = parts[1].split(':').collect();
+        if segments.len() < 3 {
+            return Err(AddressParseError::MissingField);
+        } else if segments.len() > 3 {
             return Err(AddressParseError::TooManyColons);
         }
+        let process_name = segments[0].to_string();
+        if process_name.is_empty() {
+            return Err(AddressParseError::MissingField);
+        }
+        let package_name = segments[1].to_string();
+        if package_name.is_empty() {
+            return Err(AddressParseError::MissingField);
+        }
+        let publisher_node = segments[2].to_string();
+        if publisher_node.is_empty() {
+            return Err(AddressParseError::MissingField);
+        }
+
         Ok(Address {
             node,
             process: ProcessId {
@@ -163,31 +169,93 @@ impl std::fmt::Display for Address {
 /// Error type for parsing an `Address` from a string.
 #[derive(Debug)]
 pub enum AddressParseError {
+    TooManyAts,
     TooManyColons,
     MissingNodeId,
     MissingField,
 }
 
 impl std::fmt::Display for AddressParseError {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(
-            f,
-            "{}",
-            match self {
-                AddressParseError::TooManyColons => "Too many colons in ProcessId string",
-                AddressParseError::MissingNodeId => "Node ID missing",
-                AddressParseError::MissingField => "Missing field in ProcessId string",
-            }
-        )
+        write!(f, "{self}")
     }
 }
 
 impl std::error::Error for AddressParseError {
     fn description(&self) -> &str {
         match self {
+            AddressParseError::TooManyAts => "Too many '@' chars in ProcessId string",
             AddressParseError::TooManyColons => "Too many colons in ProcessId string",
             AddressParseError::MissingNodeId => "Node ID missing",
             AddressParseError::MissingField => "Missing field in ProcessId string",
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::str::FromStr;
+
+    #[test]
+    fn test_valid_address() {
+        let input = "node123@process1:packageA:publisherB";
+        let address: Address = input.parse().unwrap();
+        assert_eq!(address.node(), "node123");
+        assert_eq!(address.process(), "process1");
+        assert_eq!(address.package(), "packageA");
+        assert_eq!(address.publisher(), "publisherB");
+    }
+
+    #[test]
+    fn test_missing_node_id() {
+        let input = "@process1:packageA:publisherB";
+        assert!(matches!(
+            Address::from_str(input),
+            Err(AddressParseError::MissingNodeId)
+        ));
+    }
+
+    #[test]
+    fn test_too_many_ats() {
+        let input = "node123@process1@packageA:publisherB";
+        assert!(matches!(
+            Address::from_str(input),
+            Err(AddressParseError::TooManyAts)
+        ));
+    }
+
+    #[test]
+    fn test_missing_field() {
+        let input = "node123@process1:packageA";
+        assert!(matches!(
+            Address::from_str(input),
+            Err(AddressParseError::MissingField)
+        ));
+    }
+
+    #[test]
+    fn test_too_many_colons() {
+        let input = "node123@process1:packageA:publisherB:extra";
+        assert!(matches!(
+            Address::from_str(input),
+            Err(AddressParseError::TooManyColons)
+        ));
+    }
+
+    #[test]
+    fn test_empty_input() {
+        let input = "";
+        assert!(matches!(
+            Address::from_str(input),
+            Err(AddressParseError::MissingNodeId)
+        ));
+    }
+
+    #[test]
+    fn test_display() {
+        let input = "node123@process1:packageA:publisherB";
+        let address: Address = input.parse().unwrap();
+        assert_eq!(format!("{}", address), input);
+    }
+}

src/types/capability.rs

@@ -5,7 +5,7 @@ use std::hash::{Hash, Hasher};
 
 /// Capability is defined in the wit bindings, but constructors and methods here.
 /// A `Capability` is a combination of an Address and a set of Params (a serialized
-/// json string). Capabilities are attached to messages to either share that capability
+/// JSON string). Capabilities are attached to messages to either share that capability
 /// with the receiving process, or to prove that a process has authority to perform a
 /// certain action.
 impl Capability {
@@ -28,6 +28,15 @@ impl Capability {
     pub fn params(&self) -> &str {
         &self.params
     }
+    /// Read the params from a `Capability` as a `serde_json::Value`.
+    pub fn params_json(&self) -> Result<serde_json::Value, serde_json::Error> {
+        serde_json::from_str(&self.params)
+    }
+    /// Set the params for a `Capability` from a `serde_json::Value`.
+    pub fn set_params_json(&mut self, value: serde_json::Value) -> Result<(), serde_json::Error> {
+        self.params = serde_json::to_string(&value)?;
+        Ok(())
+    }
 }
 
 impl Serialize for Capability {

src/types/lazy_load_blob.rs

@@ -1,5 +1,27 @@
 pub use crate::LazyLoadBlob;
 
+impl LazyLoadBlob {
+    /// Create a new `LazyLoadBlob`. Takes a mime type and a byte vector.
+    pub fn new<T, U>(mime: Option<T>, bytes: U) -> LazyLoadBlob
+    where
+        T: Into<String>,
+        U: Into<Vec<u8>>,
+    {
+        LazyLoadBlob {
+            mime: mime.map(|mime| mime.into()),
+            bytes: bytes.into(),
+        }
+    }
+    /// Read the mime type from a `LazyLoadBlob`.
+    pub fn mime(&self) -> Option<&str> {
+        self.mime.as_ref().map(|mime| mime.as_str())
+    }
+    /// Read the bytes from a `LazyLoadBlob`.
+    pub fn bytes(&self) -> &[u8] {
+        &self.bytes
+    }
+}
+
 impl std::default::Default for LazyLoadBlob {
     fn default() -> Self {
         LazyLoadBlob {