Merge pull request #3 from omnia-network/release/0.3.1

release/0.3.1

.github/workflows/tests.yml

@@ -5,11 +5,16 @@ on:
     branches:
       - main
   pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
 
 jobs:
   test:
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
-
     steps:
       - uses: actions/checkout@v4
         with:

README.md

@@ -2,7 +2,7 @@
 
 [![mops](https://oknww-riaaa-aaaam-qaf6a-cai.raw.ic0.app/badge/mops/ic-websocket-cdk)](https://mops.one/ic-websocket-cdk)
 
-This repository contains the Motoko implementation of IC WebSocket CDK. For more information about IC WebSockets, see [IC WebSocket Gateway](https://github.com/omnia-network/ic-websocket-gateway).
+This repository contains the Motoko implementation of IC WebSocket CDK and is basically a mirror of the [Rust CDK](https://github.com/omnia-network/ic-websocket-cdk-rs). For more information about IC WebSockets, see [IC WebSocket Gateway](https://github.com/omnia-network/ic-websocket-gateway).
 
 ## Installation
 
@@ -14,16 +14,16 @@ mops add ic-websocket-cdk
 
 ## Usage
 
-Refer to the [ic-websockets-pingpong-mo](https://github.com/iamenochchirima/ic-websockets-pingpong-mo) repository for an example of how to use this library.
+Refer to the [ic-websockets-pingpong-mo](https://github.com/iamenochchirima/ic-websockets-pingpong-mo) and/or [ic-websockets-chat-mo](https://github.com/iamenochchirima/ic-websockets-chat-mo) repositories for examples of how to use this library.
 
 ### Candid interface
 In order for the frontend clients and the Gateway to work properly, the canister must expose some specific methods in its Candid interface, between the custom methods that you've implemented for your logic. A valid Candid interface for the canister is the following:
 
 ```
 import "./ws_types.did";
 
-// define here your message type
-type MyMessageType = {
+// define your message type here
+type MyMessageType = record {
   some_field : text;
 };
 
@@ -53,7 +53,7 @@ Clone the repo with submodules:
 git clone --recurse-submodules https://github.com/omnia-network/ic-websocket-cdk-mo.git
 ```
 
-Integration tests are imported from the [IC WebSocket Rust CDK](https://github.com/omnia-network/ic-websocket-cdk-rs.git), linked to this repo from the `ic-websocket-cdk-rs` submodule in the [tests](./tests/) folder.
+Integration tests are imported from the [IC WebSocket Rust CDK](https://github.com/omnia-network/ic-websocket-cdk-rs.git), linked to this repo through the [`ic-websocket-cdk-rs`](./tests/ic-websocket-cdk-rs) submodule.
 
 There's a script that runs the integration tests, taking care of installing dependencies and setting up the local environment. To run the script, execute the following command:
 

did/service.example.did

@@ -1,7 +1,7 @@
 import "./ws_types.did";
 
 // define your message type here
-type MyMessageType = {
+type MyMessageType = record {
   some_field : text;
 };
 

did/ws_types.did

@@ -1,4 +1,5 @@
 type ClientPrincipal = principal;
+type GatewayPrincipal = principal;
 type ClientKey = record {
   client_principal : ClientPrincipal;
   client_nonce : nat64;
@@ -22,10 +23,12 @@ type CanisterOutputCertifiedMessages = record {
   messages : vec CanisterOutputMessage;
   cert : blob;
   tree : blob;
+  is_end_of_queue : bool;
 };
 
 type CanisterWsOpenArguments = record {
   client_nonce : nat64;
+  gateway_principal : GatewayPrincipal;
 };
 
 type CanisterWsOpenResult = variant {

mops.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ic-websocket-cdk"
-version = "0.3.0"
+version = "0.3.1"
 description = "IC WebSocket Motoko CDK"
 repository = "https://github.com/omnia-network/ic-websocket-cdk-mo"
 keywords = ["ic", "websocket", "motoko", "cdk"]

scripts/test.sh

@@ -11,4 +11,4 @@ export TEST_CANISTER_WASM_PATH="$(pwd)/bin/test_canister.wasm"
 
 cd tests/ic-websocket-cdk-rs
 
-RUST_BACKTRACE=1 cargo test --package ic-websocket-cdk --lib -- tests::integration_tests --test-threads 1
+cargo test --package ic-websocket-cdk --lib -- tests::integration_tests --test-threads 1

src/Constants.mo

@@ -0,0 +1,21 @@
+module {
+  /// The label used when constructing the certification tree.
+  public let LABEL_WEBSOCKET : Blob = "websocket";
+  /// The default maximum number of messages returned by [ws_get_messages] at each poll.
+  public let DEFAULT_MAX_NUMBER_OF_RETURNED_MESSAGES : Nat = 50;
+  /// The default interval at which to send acknowledgements to the client.
+  public let DEFAULT_SEND_ACK_INTERVAL_MS : Nat64 = 300_000; // 5 minutes
+  /// The default timeout to wait for the client to send a keep alive after receiving an acknowledgement.
+  public let DEFAULT_CLIENT_KEEP_ALIVE_TIMEOUT_MS : Nat64 = 60_000; // 1 minute
+
+  /// The initial nonce for outgoing messages.
+  public let INITIAL_OUTGOING_MESSAGE_NONCE : Nat64 = 0;
+  /// The initial sequence number to expect from messages coming from clients.
+  /// The first message coming from the client will have sequence number `1` because on the client the sequence number is incremented before sending the message.
+  public let INITIAL_CLIENT_SEQUENCE_NUM : Nat64 = 1;
+  /// The initial sequence number for outgoing messages.
+  public let INITIAL_CANISTER_SEQUENCE_NUM : Nat64 = 0;
+
+  /// The number of messages to delete from the outgoing messages queue every time a new message is added.
+  public let MESSAGES_TO_DELETE_COUNT : Nat = 5;
+};

src/Errors.mo

@@ -0,0 +1,88 @@
+import Principal "mo:base/Principal";
+import Nat64 "mo:base/Nat64";
+
+import Types "Types";
+
+module {
+  public type WsError = {
+    #AnonymousPrincipalNotAllowed;
+    #ClientKeyAlreadyConnected : {
+      client_key : Types.ClientKey;
+    };
+    #ClientKeyMessageMismatch : {
+      client_key : Types.ClientKey;
+    };
+    #ClientKeyNotConnected : {
+      client_key : Types.ClientKey;
+    };
+    #ClientNotRegisteredToGateway : {
+      client_key : Types.ClientKey;
+      gateway_principal : Types.GatewayPrincipal;
+    };
+    #ClientPrincipalNotConnected : {
+      client_principal : Types.ClientPrincipal;
+    };
+    #DecodeServiceMessageContent : {
+      err : Text;
+    };
+    #ExpectedIncomingMessageToClientNumNotInitialized : {
+      client_key : Types.ClientKey;
+    };
+    #GatewayNotRegistered : {
+      gateway_principal : Types.GatewayPrincipal;
+    };
+    #InvalidServiceMessage;
+    #IncomingSequenceNumberWrong : {
+      expected_sequence_num : Nat64;
+      actual_sequence_num : Nat64;
+    };
+    #OutgoingMessageToClientNumNotInitialized : {
+      client_key : Types.ClientKey;
+    };
+  };
+
+  public func to_string(err : WsError) : Text {
+    switch (err) {
+      case (#AnonymousPrincipalNotAllowed) {
+        "Anonymous principal is not allowed";
+      };
+      case (#ClientKeyAlreadyConnected({ client_key })) {
+        "Client with key " # Types.clientKeyToText(client_key) # " already has an open connection";
+      };
+      case (#ClientKeyMessageMismatch({ client_key })) {
+        "Client with principal " # Principal.toText(client_key.client_principal) # " has a different key than the one used in the message";
+      };
+      case (#ClientKeyNotConnected({ client_key })) {
+        "Client with key " # Types.clientKeyToText(client_key) # " doesn't have an open connection";
+      };
+      case (#ClientNotRegisteredToGateway({ client_key; gateway_principal })) {
+        "Client with key " # Types.clientKeyToText(client_key) # " was not registered to gateway " # Principal.toText(gateway_principal);
+      };
+      case (#ClientPrincipalNotConnected({ client_principal })) {
+        "Client with principal " # Principal.toText(client_principal) # " doesn't have an open connection";
+      };
+      case (#DecodeServiceMessageContent({ err })) {
+        "Error decoding service message content: " # err;
+      };
+      case (#ExpectedIncomingMessageToClientNumNotInitialized({ client_key })) {
+        "Expected incoming message to client num not initialized for client key " # Types.clientKeyToText(client_key);
+      };
+      case (#GatewayNotRegistered({ gateway_principal })) {
+        "Gateway with principal " # Principal.toText(gateway_principal) # " is not registered";
+      };
+      case (#InvalidServiceMessage) {
+        "Invalid service message";
+      };
+      case (#IncomingSequenceNumberWrong({ expected_sequence_num; actual_sequence_num })) {
+        "Expected incoming sequence number " # Nat64.toText(expected_sequence_num) # " but got " # Nat64.toText(actual_sequence_num);
+      };
+      case (#OutgoingMessageToClientNumNotInitialized({ client_key })) {
+        "Outgoing message to client num not initialized for client key " # Types.clientKeyToText(client_key);
+      };
+    };
+  };
+
+  public func to_string_result(err : WsError) : Types.Result<(), Text> {
+    #Err(to_string(err));
+  };
+};