From 7e5d0600329599296533df1283f8fbc1dd67ddc1 Mon Sep 17 00:00:00 2001 From: Daniel Sanchez Quiros Date: Wed, 5 Oct 2022 15:39:46 +0200 Subject: [PATCH] Add docs to node methods --- waku/src/node/management.rs | 10 ++--- waku/src/node/mod.rs | 73 +++++++++++++++++++++++++++++++++---- waku/src/node/peers.rs | 2 +- 3 files changed, 71 insertions(+), 14 deletions(-) diff --git a/waku/src/node/management.rs b/waku/src/node/management.rs index 9c7f36e..cd55c56 100644 --- a/waku/src/node/management.rs +++ b/waku/src/node/management.rs @@ -4,7 +4,7 @@ use std::ffi::{CStr, CString}; // crates // internal use super::config::WakuNodeConfig; -use crate::general::{JsonResponse, Result}; +use crate::general::{JsonResponse, PeerId, Result}; /// Instantiates a Waku node /// as per the [specification](https://rfc.vac.dev/spec/36/#extern-char-waku_newchar-jsonconfig) @@ -52,7 +52,7 @@ pub fn waku_stop() -> Result { /// If the execution is successful, the result is the peer ID as a string (base58 encoded) /// as per the [specification](https://rfc.vac.dev/spec/36/#extern-char-waku_stop) -pub fn waku_peer_id() -> Result { +pub fn waku_peer_id() -> Result { let response = unsafe { CStr::from_ptr(waku_sys::waku_peerid()) } .to_str() .expect("Response should always succeed to load to a &str"); @@ -65,7 +65,7 @@ pub fn waku_peer_id() -> Result { /// Get the multiaddresses the Waku node is listening to /// as per [specification](https://rfc.vac.dev/spec/36/#extern-char-waku_listen_addresses) -pub fn waku_listen_addressses() -> Result> { +pub fn waku_listen_addresses() -> Result> { let response = unsafe { CStr::from_ptr(waku_sys::waku_listen_addresses()) } .to_str() .expect("Response should always succeed to load to a &str"); @@ -79,7 +79,7 @@ pub fn waku_listen_addressses() -> Result> { #[cfg(test)] mod test { use super::waku_new; - use crate::node::management::{waku_listen_addressses, waku_peer_id, waku_start, waku_stop}; + use crate::node::management::{waku_listen_addresses, waku_peer_id, waku_start, waku_stop}; #[test] fn waku_flow() { @@ -91,7 +91,7 @@ mod test { assert!(!id.is_empty()); // test addresses, since we cannot start different instances of the node - let addresses = waku_listen_addressses().unwrap(); + let addresses = waku_listen_addresses().unwrap(); dbg!(&addresses); assert!(!addresses.is_empty()); diff --git a/waku/src/node/mod.rs b/waku/src/node/mod.rs index dbc6eca..09817c8 100644 --- a/waku/src/node/mod.rs +++ b/waku/src/node/mod.rs @@ -36,18 +36,28 @@ impl WakuNodeState for Running {} pub struct WakuNodeHandle(PhantomData); impl WakuNodeHandle { - pub fn peer_id(&self) -> Result { + /// If the execution is successful, the result is the peer ID as a string (base58 encoded) + /// + /// wrapper around [`management::waku_peer_id`] + pub fn peer_id(&self) -> Result { management::waku_peer_id() } + /// Get the multiaddresses the Waku node is listening to + /// + /// wrapper around [`management::waku_listen_addresses`] pub fn listen_addresses(&self) -> Result> { - management::waku_listen_addressses() + management::waku_listen_addresses() } + /// Add a node multiaddress and protocol to the waku node’s peerstore + /// + /// wrapper around [`peers::waku_add_peers`] pub fn add_peer(&mut self, address: Multiaddr, protocol_id: usize) -> Result { peers::waku_add_peers(address, protocol_id) } } + fn stop_node() -> Result<()> { let mut node_initialized = WAKU_NODE_INITIALIZED .lock() @@ -57,20 +67,35 @@ fn stop_node() -> Result<()> { } impl WakuNodeHandle { + /// Start a Waku node mounting all the protocols that were enabled during the Waku node instantiation + /// + /// wrapper around [`management::waku_start`] pub fn start(self) -> Result> { management::waku_start().map(|_| WakuNodeHandle(Default::default())) } + /// Stops a Waku node + /// + /// internally uses [`management::waku_stop`] pub fn stop(self) -> Result<()> { stop_node() } } impl WakuNodeHandle { + /// Stops a Waku node + /// + /// internally uses [`management::waku_stop`] pub fn stop(self) -> Result<()> { stop_node() } + /// Dial peer using a multiaddress + /// If `timeout` as milliseconds doesn't fit into a `i32` it is clamped to [`i32::MAX`] + /// If the function execution takes longer than `timeout` value, the execution will be canceled and an error returned. + /// Use 0 for no timeout + /// + /// wrapper around [`peers::waku_connect_peer_with_address`] pub fn connect_peer_with_address( &mut self, address: Multiaddr, @@ -79,6 +104,9 @@ impl WakuNodeHandle { peers::waku_connect_peer_with_address(address, timeout) } + /// Dial peer using its peer ID + /// + /// wrapper around [`peers::waku_connect_peer_with_id`] pub fn connect_peer_with_id( &mut self, peer_id: PeerId, @@ -87,19 +115,31 @@ impl WakuNodeHandle { peers::waku_connect_peer_with_id(peer_id, timeout) } + /// Disconnect a peer using its peerID + /// + /// wrapper around [`peers::waku_disconnect_peer_with_id`] pub fn disconnect_peer_with_id(&mut self, peer_id: PeerId) -> Result<()> { peers::waku_disconnect_peer_with_id(peer_id) } + /// Get number of connected peers + /// + /// wrapper around [`peers::waku_peer_count`] pub fn peer_count(&self) -> Result { peers::waku_peer_count() } + /// Retrieve the list of peers known by the Waku node + /// + /// wrapper around [`peers::waku_peers`] pub fn peers(&self) -> Result { peers::waku_peers() } - pub fn publish_message( + /// Publish a message using Waku Relay + /// + /// wrapper around [`relay::waku_relay_publish_message`] + pub fn relay_publish_message( &mut self, message: &WakuMessage, pubsub_topic: Option, @@ -108,7 +148,10 @@ impl WakuNodeHandle { relay::waku_relay_publish_message(message, pubsub_topic, timeout) } - pub fn publish_encrypt_asymmetric( + /// Optionally sign, encrypt using asymmetric encryption and publish a message using Waku Relay + /// + /// wrapper around [`relay::waku_relay_publish_encrypt_asymmetric`] + pub fn relay_publish_encrypt_asymmetric( &mut self, message: &WakuMessage, pubsub_topic: Option, @@ -125,7 +168,10 @@ impl WakuNodeHandle { ) } - pub fn publish_encrypt_symmetric( + /// Optionally sign, encrypt using symmetric encryption and publish a message using Waku Relay + /// + /// wrapper around [`relay::waku_relay_publish_encrypt_symmetric`] + pub fn relay_publish_encrypt_symmetric( &mut self, message: &WakuMessage, pubsub_topic: Option, @@ -142,19 +188,30 @@ impl WakuNodeHandle { ) } - pub fn enough_peers(&self, pubsub_topic: Option) -> Result { + /// Determine if there are enough peers to publish a message on a given pubsub topic + /// + /// wrapper around [`relay::waku_enough_peers`] + pub fn relay_enough_peers(&self, pubsub_topic: Option) -> Result { relay::waku_enough_peers(pubsub_topic) } - pub fn subscribe(&mut self, pubsub_topic: Option) -> Result<()> { + /// Subscribe to a Waku Relay pubsub topic to receive messages + /// + /// wrapper around [`relay::waku_relay_subscribe`] + pub fn relay_subscribe(&mut self, pubsub_topic: Option) -> Result<()> { relay::waku_relay_subscribe(pubsub_topic) } - pub fn unsubscribe(&mut self, pubsub_topic: Option) -> Result<()> { + /// Closes the pubsub subscription to a pubsub topic. No more messages will be received from this pubsub topic + /// + /// wrapper around [`relay::waku_relay_unsubscribe`] + pub fn relay_unsubscribe(&mut self, pubsub_topic: Option) -> Result<()> { relay::waku_relay_unsubscribe(pubsub_topic) } } +/// Spawn a new Waku node with the givent configuration (default configuration if `None` provided) +/// Internally uses [`management::waku_new`] pub fn waku_new(config: Option) -> Result> { let mut node_initialized = WAKU_NODE_INITIALIZED .lock() diff --git a/waku/src/node/peers.rs b/waku/src/node/peers.rs index 9594dac..4b1a933 100644 --- a/waku/src/node/peers.rs +++ b/waku/src/node/peers.rs @@ -57,7 +57,7 @@ pub fn waku_connect_peer_with_address(address: Multiaddr, timeout: Option) -> Result<()> { let response = unsafe {