ic-websocket-cdk-rs

This repository contains the Rust implementation of IC WebSocket CDK. For more information about IC WebSockets, see IC WebSocket Gateway.

Installation

You can install the library by running:

cargo add ic-websocket-cdk

Usage

Refer to the ic_websocket_example repository for an example of how to use the 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 = {
  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 of your types.

To automatically generate the Candid interfaces for your canister, have a look at this article.

Development

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

Testing

There are two types of tests available:

• Unit tests: tests for CDK functions, written in Rust and available in the unit_tests folder.
• Integration tests: for these tests the CDK is deployed to a test canister. These tests are written in Rust and use PocketIC under the hood. They are available in the integration_tests folder.

There's a script that runs all the tests together, taking care of setting up the environment (Linux only!) and deploying the canister. 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.