refactor: rename ws_send to send

to be consistent with the newly introduced `close` method

src/ic-websocket-cdk/src/lib.rs

@@ -13,13 +13,14 @@ mod utils;
 
 use state::*;
 use timers::*;
+#[allow(deprecated)]
+pub use types::CanisterWsSendResult;
 use types::*;
 pub use types::{
-    CanisterCloseResult, CanisterWsCloseArguments, CanisterWsCloseResult,
+    CanisterCloseResult, CanisterSendResult, CanisterWsCloseArguments, CanisterWsCloseResult,
     CanisterWsGetMessagesArguments, CanisterWsGetMessagesResult, CanisterWsMessageArguments,
-    CanisterWsMessageResult, CanisterWsOpenArguments, CanisterWsOpenResult, CanisterWsSendResult,
-    ClientPrincipal, OnCloseCallbackArgs, OnMessageCallbackArgs, OnOpenCallbackArgs, WsHandlers,
-    WsInitParams,
+    CanisterWsMessageResult, CanisterWsOpenArguments, CanisterWsOpenResult, ClientPrincipal,
+    OnCloseCallbackArgs, OnMessageCallbackArgs, OnOpenCallbackArgs, WsHandlers, WsInitParams,
 };
 
 /// The label used when constructing the certification tree.
@@ -235,7 +236,7 @@ pub fn ws_get_messages(args: CanisterWsGetMessagesArguments) -> CanisterWsGetMes
 /// This example is the serialize equivalent of the [OnMessageCallbackArgs's example](struct.OnMessageCallbackArgs.html#example) deserialize one.
 /// ```rust
 /// use candid::{encode_one, CandidType, Principal};
-/// use ic_websocket_cdk::ws_send;
+/// use ic_websocket_cdk::send;
 /// use serde::Deserialize;
 ///
 /// #[derive(CandidType, Deserialize)]
@@ -251,13 +252,20 @@ pub fn ws_get_messages(args: CanisterWsGetMessagesArguments) -> CanisterWsGetMes
 /// };
 ///
 /// let msg_bytes = encode_one(&my_message).unwrap();
-/// ws_send(my_client_principal, msg_bytes);
+/// send(my_client_principal, msg_bytes);
 /// ```
-pub fn ws_send(client_principal: ClientPrincipal, msg_bytes: Vec<u8>) -> CanisterWsSendResult {
+pub fn send(client_principal: ClientPrincipal, msg_bytes: Vec<u8>) -> CanisterSendResult {
     let client_key = get_client_key_from_principal(&client_principal)?;
     _ws_send(&client_key, msg_bytes, false)
 }
 
+#[deprecated(since = "0.3.2", note = "use `ic_websocket_cdk::send` instead")]
+#[allow(deprecated)]
+/// Deprecated: use [send] instead.
+pub fn ws_send(client_principal: ClientPrincipal, msg_bytes: Vec<u8>) -> CanisterWsSendResult {
+    send(client_principal, msg_bytes)
+}
+
 /// Closes the connection with the client.
 pub fn close(client_principal: ClientPrincipal) -> CanisterCloseResult {
     let client_key = get_client_key_from_principal(&client_principal)?;

src/ic-websocket-cdk/src/state.rs

@@ -437,7 +437,7 @@ pub(crate) fn push_message_in_gateway_queue(
 ) -> Result<(), String> {
     REGISTERED_GATEWAYS.with(|map| {
         // messages in the queue are inserted with contiguous and increasing nonces
-        // (from beginning to end of the queue) as ws_send is called sequentially, the nonce
+        // (from beginning to end of the queue) as `send` is called sequentially, the nonce
         // is incremented by one in each call, and the message is pushed at the end of the queue
         map.borrow_mut()
             .get_mut(gateway_principal)
@@ -555,7 +555,7 @@ pub(crate) fn _ws_send(
     client_key: &ClientKey,
     msg_bytes: Vec<u8>,
     is_service_message: bool,
-) -> CanisterWsSendResult {
+) -> CanisterSendResult {
     // get the registered client if it exists
     let registered_client = get_registered_client(client_key)?;
 

src/ic-websocket-cdk/src/tests/integration_tests/c_ws_get_messages.rs

@@ -8,8 +8,8 @@ use crate::{
 
 use super::utils::{
     actor::{
-        ws_get_messages::call_ws_get_messages_with_panic,
-        ws_open::call_ws_open_for_client_key_with_panic, ws_send::call_ws_send_with_panic,
+        send::call_send_with_panic, ws_get_messages::call_ws_get_messages_with_panic,
+        ws_open::call_ws_open_for_client_key_with_panic,
     },
     clients::{generate_random_client_key, CLIENT_1_KEY, GATEWAY_1},
     messages::{get_next_polling_nonce_from_messages, verify_messages, AppMessage},
@@ -70,7 +70,7 @@ proptest! {
                 text: format!("test{}", i),
             })
             .collect();
-        call_ws_send_with_panic(
+        call_send_with_panic(
             &client_1_key.client_principal,
             messages_to_send.clone(),
         );
@@ -131,7 +131,7 @@ proptest! {
                 text: format!("test{}", i),
             })
             .collect();
-        call_ws_send_with_panic(&client_1_key.client_principal, messages_to_send.clone());
+        call_send_with_panic(&client_1_key.client_principal, messages_to_send.clone());
 
         let mut next_polling_nonce = 0;
         let mut expected_sequence_number = 1;  // `1` because the seq number is incremented before sending on the canister
@@ -179,7 +179,7 @@ proptest! {
                 text: format!("test{}", i),
             })
             .collect();
-        call_ws_send_with_panic(&client_1_key.client_principal, messages_to_send.clone());
+        call_send_with_panic(&client_1_key.client_principal, messages_to_send.clone());
 
         // advance canister time because the messages are deleted only
         // if they're older than the send ack interval;

src/ic-websocket-cdk/src/tests/integration_tests/e_ws_send.rs → src/ic-websocket-cdk/src/tests/integration_tests/e_send.rs

@@ -1,9 +1,9 @@
 use std::ops::Deref;
 
-use crate::{errors::WsError, CanisterWsSendResult};
+use crate::{errors::WsError, CanisterSendResult};
 
 use super::utils::{
-    actor::{ws_open::call_ws_open_for_client_key_with_panic, ws_send::call_ws_send},
+    actor::{send::call_send, ws_open::call_ws_open_for_client_key_with_panic},
     clients::{CLIENT_1_KEY, CLIENT_2_KEY},
     messages::AppMessage,
     test_env::get_test_env,
@@ -18,15 +18,15 @@ fn test_1_fails_if_sending_a_message_to_a_non_registered_client() {
 
     // finally, we can start testing
     let client_2_principal = &CLIENT_2_KEY.client_principal;
-    let res = call_ws_send(
+    let res = call_send(
         client_2_principal,
         vec![AppMessage {
             text: String::from("test"),
         }],
     );
     assert_eq!(
         res,
-        CanisterWsSendResult::Err(
+        CanisterSendResult::Err(
             WsError::ClientPrincipalNotConnected {
                 client_principal: client_2_principal
             }
@@ -42,11 +42,11 @@ fn test_2_should_send_a_message_to_a_registered_client() {
     // second, open a connection for client 1
     call_ws_open_for_client_key_with_panic(CLIENT_1_KEY.deref());
 
-    let res = call_ws_send(
+    let res = call_send(
         &CLIENT_1_KEY.client_principal,
         vec![AppMessage {
             text: String::from("test"),
         }],
     );
-    assert_eq!(res, CanisterWsSendResult::Ok(()));
+    assert_eq!(res, CanisterSendResult::Ok(()));
 }

src/ic-websocket-cdk/src/tests/integration_tests/h_multiple_gateways.rs

@@ -7,9 +7,9 @@ use crate::{
 
 use super::utils::{
     actor::{
-        ws_close::call_ws_close_with_panic, ws_get_messages::call_ws_get_messages_with_panic,
+        send::call_send_with_panic, ws_close::call_ws_close_with_panic,
+        ws_get_messages::call_ws_get_messages_with_panic,
         ws_open::call_ws_open_for_client_key_and_gateway_with_panic,
-        ws_send::call_ws_send_with_panic,
     },
     messages::{get_service_message_content_from_canister_message, verify_messages, AppMessage},
     test_env::get_test_env,
@@ -34,7 +34,7 @@ proptest! {
                 text: format!("test{}", i),
             })
             .collect();
-        call_ws_send_with_panic(
+        call_send_with_panic(
             &client_key.client_principal,
             messages_to_send.clone(),
         );
@@ -108,7 +108,7 @@ proptest! {
             })
             .collect();
         // simulate canister sending other messages to client
-        call_ws_send_with_panic(
+        call_send_with_panic(
             &client_key.client_principal,
             messages_to_send.clone(),
         );

src/ic-websocket-cdk/src/tests/integration_tests/mod.rs

@@ -11,7 +11,7 @@ mod a_ws_open;
 mod b_ws_message;
 mod c_ws_get_messages;
 mod d_ws_close;
-mod e_ws_send;
+mod e_send;
 mod f_close;
 mod g_messages_acknowledgement;
 mod h_multiple_gateways;

src/ic-websocket-cdk/src/tests/integration_tests/utils/actor.rs

@@ -181,30 +181,30 @@ pub mod ws_get_messages {
     }
 }
 
-pub mod ws_send {
-    use crate::{CanisterWsSendResult, ClientPrincipal};
+pub mod send {
+    use crate::{CanisterSendResult, ClientPrincipal};
     use candid::encode_args;
 
     use super::*;
 
     /// (`ClientPrincipal`, `Vec<Vec<u8>>`)
-    type WsSendArguments = (ClientPrincipal, Vec<Vec<u8>>);
+    type SendArguments = (ClientPrincipal, Vec<Vec<u8>>);
 
     /// # Panics
     /// if the call returns a [WasmResult::Reject].
-    pub(crate) fn call_ws_send(
+    pub(crate) fn call_send(
         send_to_principal: &ClientPrincipal,
         messages: Vec<AppMessage>,
-    ) -> CanisterWsSendResult {
+    ) -> CanisterSendResult {
         let messages: Vec<Vec<u8>> = messages.iter().map(|m| encode_one(m).unwrap()).collect();
-        let args: WsSendArguments = (send_to_principal.clone(), messages);
+        let args: SendArguments = (send_to_principal.clone(), messages);
         let canister_id = get_test_env().canister_id;
         let res = get_test_env()
             .pic
             .update_call(
                 canister_id,
                 Principal::anonymous(),
-                "ws_send",
+                "send",
                 encode_args(args).unwrap(),
             )
             .expect("Failed to call canister");
@@ -214,17 +214,17 @@ pub mod ws_send {
         }
     }
 
-    /// Same as [call_ws_send].
+    /// Same as [call_send].
     ///
     /// # Panics
-    /// If [call_ws_send] panics or if the call returns an error variant.
-    pub(crate) fn call_ws_send_with_panic(
+    /// If [call_send] panics or if the call returns an error variant.
+    pub(crate) fn call_send_with_panic(
         send_to_principal: &ClientPrincipal,
         messages: Vec<AppMessage>,
     ) {
-        match call_ws_send(send_to_principal, messages) {
-            CanisterWsSendResult::Ok(_) => {},
-            CanisterWsSendResult::Err(err) => panic!("failed ws_send: {:?}", err),
+        match call_send(send_to_principal, messages) {
+            CanisterSendResult::Ok(_) => {},
+            CanisterSendResult::Err(err) => panic!("failed send: {:?}", err),
         }
     }
 }

src/ic-websocket-cdk/src/types.rs

@@ -41,7 +41,9 @@ pub type CanisterWsCloseResult = Result<(), String>;
 pub type CanisterWsMessageResult = Result<(), String>;
 /// The result of [ws_get_messages](crate::ws_get_messages).
 pub type CanisterWsGetMessagesResult = Result<CanisterOutputCertifiedMessages, String>;
-/// The result of [ws_send](crate::ws_send).
+/// The result of [send](crate::send).
+pub type CanisterSendResult = Result<(), String>;
+#[deprecated(since = "0.3.2", note = "use `CanisterSendResult` instead")]
 pub type CanisterWsSendResult = Result<(), String>;
 /// The result of [close](crate::close).
 pub type CanisterCloseResult = Result<(), String>;
@@ -314,7 +316,7 @@ type OnOpenCallback = fn(OnOpenCallbackArgs);
 /// To deserialize the message, use [candid::decode_one].
 ///
 /// # Example
-/// This example is the deserialize equivalent of the [ws_send's example](fn.ws_send.html#example) serialize one.
+/// This example is the deserialize equivalent of the [send's example](fn.send.html#example) serialize one.
 /// ```rust
 /// use candid::{decode_one, CandidType};
 /// use ic_websocket_cdk::OnMessageCallbackArgs;

src/test_canister/src/lib.rs

@@ -2,10 +2,10 @@ use ic_cdk_macros::*;
 
 use canister::{on_close, on_message, on_open, AppMessage};
 use ic_websocket_cdk::{
-    CanisterCloseResult, CanisterWsCloseArguments, CanisterWsCloseResult,
+    CanisterCloseResult, CanisterSendResult, CanisterWsCloseArguments, CanisterWsCloseResult,
     CanisterWsGetMessagesArguments, CanisterWsGetMessagesResult, CanisterWsMessageArguments,
-    CanisterWsMessageResult, CanisterWsOpenArguments, CanisterWsOpenResult, CanisterWsSendResult,
-    ClientPrincipal, WsHandlers, WsInitParams,
+    CanisterWsMessageResult, CanisterWsOpenArguments, CanisterWsOpenResult, ClientPrincipal,
+    WsHandlers, WsInitParams,
 };
 
 mod canister;
@@ -75,9 +75,9 @@ fn ws_get_messages(args: CanisterWsGetMessagesArguments) -> CanisterWsGetMessage
 //// Debug/tests methods
 // send a message to the client, usually called by the canister itself
 #[update]
-fn ws_send(client_principal: ClientPrincipal, messages: Vec<Vec<u8>>) -> CanisterWsSendResult {
+fn send(client_principal: ClientPrincipal, messages: Vec<Vec<u8>>) -> CanisterSendResult {
     for msg_bytes in messages {
-        match ic_websocket_cdk::ws_send(client_principal, msg_bytes) {
+        match ic_websocket_cdk::send(client_principal, msg_bytes) {
             Ok(_) => {},
             Err(e) => return Err(e),
         }

src/test_canister/test_canister.did

@@ -1,6 +1,6 @@
 import "../src/ic-websocket-cdk/ws_types.did";
 
-type CanisterWsSendResult = variant {
+type CanisterSendResult = variant {
   Ok : null;
   Err : text;
 };
@@ -21,6 +21,6 @@ service : (text, nat64, nat64, nat64) -> {
   "ws_get_messages" : (CanisterWsGetMessagesArguments) -> (CanisterWsGetMessagesResult) query;
 
   // methods used just for debugging/testing
-  "ws_send" : (ClientPrincipal, vec blob) -> (CanisterWsSendResult);
+  "send" : (ClientPrincipal, vec blob) -> (CanisterSendResult);
   "close" : (ClientPrincipal) -> (CanisterCloseResult);
 };