-
Notifications
You must be signed in to change notification settings - Fork 236
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4107 from nymtech/feature/websocket-client-usage-…
…docs Feature/websocket client usage docs
- Loading branch information
Showing
7 changed files
with
253 additions
and
210 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| # Configuration | ||
|
|
||
| ## Default listening port | ||
| The Nym native client exposes a websocket interface that your code connects to. To program your app, choose a websocket library for whatever language you're using. The **default** websocket port is `1977`, you can override that in the client config if you want. | ||
|
|
||
| You can either set this via the `--port` flag at `init` or `run`, or you can manually edit `~/.nym/clients/<CLIENT-ID>/config/config.toml`. | ||
|
|
||
| > Remember to restart your client if you change your listening port via editing your config file. | ||
| ## Choosing a Gateway | ||
| By default your client will choose a random gateway to connect to. | ||
|
|
||
| However, there are several options for choosing a gateway, if you do not want one that is randomly assigned to your client: | ||
| * If you wish to connect to a specific gateway, you can specify this with the `--gateway` flag when running `init`. | ||
| * You can also choose a gateway based on its location relative to your client. This can be done by appending the `--latency-based-routing` flag to your `init` command. This command means that to select a gateway, your client will: | ||
| * fetch a list of all available gateways | ||
| * send few ping messages to all of them, and measure response times. | ||
| * create a weighted distribution to randomly choose one, favouring ones with lower latency. | ||
|
|
||
| > Note this doesn't mean that your client will pick the closest gateway to you, but it will be far more likely to connect to gateway with a 20ms ping rather than 200ms | ||
| ## Configuring your client | ||
| When you initalise a client instance, a configuration directory will be generated and stored in `$HOME_DIR/.nym/clients/<client-name>/`. | ||
|
|
||
| ``` | ||
| tree $HOME/<user>/.nym/clients/example-client | ||
| ├── config | ||
| │ └── config.toml | ||
| └── data | ||
| ├── ack_key.pem | ||
| ├── gateway_shared.pem | ||
| ├── private_encryption.pem | ||
| ├── private_identity.pem | ||
| ├── public_encryption.pem | ||
| └── public_identity.pem | ||
| ``` | ||
|
|
||
| The `config.toml` file contains client configuration options, while the two `pem` files contain client key information. | ||
|
|
||
| The generated files contain the client name, public/private keypairs, and gateway address. The name `<client_id>` in the example above is just a local identifier so that you can name your clients. | ||
|
|
||
| ### Configuring your client for Docker | ||
| By default, the native client listens to host `127.0.0.1`. However this can be an issue if you wish to run a client in a Dockerized environment, where it can be convenenient to listen on a different host such as `0.0.0.0`. | ||
|
|
||
| You can set this via the `--host` flag during either the `init` or `run` commands. | ||
|
|
||
| Alternatively, a custom host can be set in the `config.toml` file under the `socket` section. If you do this, remember to restart your client process. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| # Examples | ||
| The Nym monorepo includes websocket client example code for Rust, Go, Javacript, and Python, all of which can be found [here](https://github.com/nymtech/nym/tree/master/clients/native/examples). | ||
|
|
||
| > Rust users can run the examples with `cargo run --example <rust_file>.rs`, as the examples are not organised in the same way as the other examples, due to already being inside a Cargo project. | ||
| All of these code examples will do the following: | ||
| * connect to a running websocket client on port `1977` | ||
| * format a message to send in either JSON or Binary format. Nym messages have defined JSON formats. | ||
| * send the message into the websocket. The native client packages the message into a Sphinx packet and sends it to the mixnet | ||
| * wait for confirmation that the message hit the native client | ||
| * wait to receive messages from other Nym apps | ||
|
|
||
| By varying the message content, you can easily build sophisticated service provider apps. For example, instead of printing the response received from the mixnet, your service provider might take some action on behalf of the user - perhaps initiating a network request, a blockchain transaction, or writing to a local data store. | ||
|
|
||
| > You can find an example of building both frontend and service provider code with the websocket client in the [Simple Service Provider Tutorial](https://nymtech.net/developers/tutorials/simple-service-provider/simple-service-provider.html) in the Developer Portal. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # Setup & Run | ||
|
|
||
| ## Viewing command help | ||
|
|
||
| You can check that your binaries are properly compiled with: | ||
|
|
||
| ``` | ||
| ./nym-client --help | ||
| ``` | ||
|
|
||
| ~~~admonish example collapsible=true title="Console output" | ||
| ``` | ||
| <!-- cmdrun ../../../../../target/release/nym-client --help --> | ||
| ``` | ||
| ~~~ | ||
|
|
||
| The two most important commands you will issue to the client are: | ||
|
|
||
| * `init` - initalise a new client instance. | ||
| * `run` - run a mixnet client process. | ||
|
|
||
| You can check the necessary parameters for the available commands by running: | ||
|
|
||
| ``` | ||
| ./nym-client <command> --help | ||
| ``` | ||
|
|
||
| ## Initialising your client | ||
|
|
||
| Before you can use the client, you need to initalise a new instance of it. Each instance of the client has its own public/private keypair, and connects to its own gateway node. Taken together, these 3 things (public/private keypair + gateway node identity key) make up an app's identity. | ||
|
|
||
| Initialising a new client instance can be done with the following command: | ||
|
|
||
| ``` | ||
| ./nym-client init --id example-client | ||
| ``` | ||
|
|
||
| ~~~admonish example collapsible=true title="Console output" | ||
| ``` | ||
| <!-- cmdrun ../../../../../target/release/nym-client init --id example-client --> | ||
| ``` | ||
| ~~~ | ||
|
|
||
| The `--id` in the example above is a local identifier so that you can name your clients; it is **never** transmitted over the network. | ||
|
|
||
| There is an optional `--gateway` flag that you can use if you want to use a specific gateway. The supplied argument is the `Identity Key` of the gateway you wish to use, which can be found on the [mainnet Network Explorer](https://explorer.nymtech.net/network-components/gateways) or [Sandbox Testnet Explorer](https://sandbox-explorer.nymtech.net/network-components/gateways) depending on which network you are on. | ||
|
|
||
| Not passing this argument will randomly select a gateway for your client. | ||
|
|
||
| ## Running your client | ||
| You can run the initalised client by doing this: | ||
|
|
||
| ``` | ||
| ./nym-client run --id example-client | ||
| ``` | ||
|
|
||
| When you run the client, it immediately starts generating (fake) cover traffic and sending it to the mixnet. | ||
|
|
||
| When the client is first started, it will reach out to the Nym network's validators, and get a list of available Nym nodes (gateways, mixnodes, and validators). We call this list of nodes the network _topology_. The client does this so that it knows how to connect, register itself with the network, and know which mixnodes it can route Sphinx packets through. |
Oops, something went wrong.