ic-websocket-cdk-mo

This repository contains the Motoko implementation of IC WebSocket CDK and is basically a mirror of the Rust CDK. For more information about IC WebSockets, see IC WebSocket Gateway.

Installation

You can install the library using mops:

mops add ic-websocket-cdk

Usage

Refer to the ic-websockets-pingpong-mo and/or 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 your message type here
type MyMessageType = record {
  some_field : text;
};

service : {
  "ws_open" : (CanisterWsOpenArguments) -> (CanisterWsOpenResult);
  "ws_close" : (CanisterWsCloseArguments) -> (CanisterWsCloseResult);
  "ws_message" : (CanisterWsMessageArguments, opt MyMessageType) -> (CanisterWsMessageResult);
  "ws_get_messages" : (CanisterWsGetMessagesArguments) -> (CanisterWsGetMessagesResult) query;
};

This snipped is copied from the service.example.did file and the types imported are defined in the ws_types.did file.

To define your message type, you can use the Candid reference docs. We suggest you to define your message type using a variant, so that you can support different messages over the same websocket instance and make it safe for future updates.

Note: dfx should already generate the Candid interface for you, so you don't need to write any .did file yourself.

Development

The ic-websocket-cdk library implementation can be found in the src folder.

Testing

You need Rust toolchain to run the tests.

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, linked to this repo through the 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:

./scripts/test.sh

License

MIT License. See LICENSE.

Contributing

Feel free to open issues and pull requests.