From 13e8a9fca7dc45cf3f50f2eca5df059e0f33394e Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Wed, 9 Oct 2024 20:15:18 +0200 Subject: [PATCH] first pass new ws client --- .../pages/developers/clients/websocket.md | 12 +++---- .../developers/clients/websocket/setup.md | 14 +------- .../developers/clients/websocket/usage.md | 34 ++++++++++--------- 3 files changed, 24 insertions(+), 36 deletions(-) diff --git a/documentation/docs/pages/developers/clients/websocket.md b/documentation/docs/pages/developers/clients/websocket.md index add7ef24dc..66488ab21f 100644 --- a/documentation/docs/pages/developers/clients/websocket.md +++ b/documentation/docs/pages/developers/clients/websocket.md @@ -1,13 +1,11 @@ # Websocket Client -> The Nym Websocket Client was built in the [building nym](../binaries/building-nym.md) section. If you haven't yet built Nym and want to run the code on this page, go there first. +You can run this client as a standalone process and pipe traffic into it to be sent through the mixnet. This is useful if you're building an application in a language other than Typescript or Rust and cannot utilise one of the SDKs. -## Current version -``` - -``` +You can find the code for this client [here](https://github.com/nymtech/nym/tree/master/clients/native). -You can run this client as a standalone process and pipe traffic into it to be sent through the mixnet. This is useful if you're building an application in a language other than Typescript or Rust and cannot utilise one of the SDKs. +## Download or compile client -You can find the code for this client [here](https://github.com/nymtech/nym/tree/develop/clients/native). +If you are using OSX or a Debian-based operating system, you can download the `nym-socks5-client` binary from our [Github releases page](https://github.com/nymtech/nym/releases). +If you are using a different operating system, or want to build from source, simply use `cargo build --release` from the root of the Nym monorepo. diff --git a/documentation/docs/pages/developers/clients/websocket/setup.md b/documentation/docs/pages/developers/clients/websocket/setup.md index e682e87175..39503c771f 100644 --- a/documentation/docs/pages/developers/clients/websocket/setup.md +++ b/documentation/docs/pages/developers/clients/websocket/setup.md @@ -1,4 +1,4 @@ -# Setup & Run +# Setup & Run ## Viewing command help @@ -8,12 +8,6 @@ You can check that your binaries are properly compiled with: ./nym-client --help ``` -~~~admonish example collapsible=true title="Console output" -``` - -``` -~~~ - The two most important commands you will issue to the client are: * `init` - initalise a new client instance. @@ -35,12 +29,6 @@ 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" -``` - -``` -~~~ - 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. diff --git a/documentation/docs/pages/developers/clients/websocket/usage.md b/documentation/docs/pages/developers/clients/websocket/usage.md index ecc157d98d..5af5cc1dbd 100644 --- a/documentation/docs/pages/developers/clients/websocket/usage.md +++ b/documentation/docs/pages/developers/clients/websocket/usage.md @@ -3,14 +3,10 @@ The Nym native client exposes a websocket interface that your code connects to. Once you have a websocket connection, interacting with the client involves piping messages down the socket and listening for incoming messages. -# Message Requests -There are a number of message types that you can send up the websocket as defined [here](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/requests.rs): +## Message Requests +There are a number of message types that you can send up the websocket as defined [here](https://github.com/nymtech/nym/blob/master/clients/native/websocket-requests/src/responses.rs#L48). -```rust,noplayground -{{#include ../../../../../clients/native/websocket-requests/src/requests.rs:55:97}} -``` - -## Getting your own address +### Getting your own address When you start your app, it is best practice to ask the native client to tell you what your own address is (from the generated configuration files . If you are running a service, you need to do this in order to know what address to give others. In a client-side piece of code you can also use this as a test to make sure your websocket connection is running smoothly. To do this, send: ```json @@ -32,7 +28,7 @@ See [here](https://github.com/nymtech/nym/blob/93cc281abc2cc951023b51746fa6f2ead > Note that all the pieces of native client example code begin with printing the selfAddress. Examples exist for Rust, Go, Javascript, and Python. -## Sending text +### Sending text If you want to send text information through the mixnet, format a message like this one and poke it into the websocket: ```json @@ -75,7 +71,7 @@ See ['Replying to SURB Messages'](#replying-to-surb-messages) below for an examp Deciding on the amount of SURBs to generate and send along with outgoing messages depends on the expected size of the reply. You might want to send a lot of SURBs in order to make sure you get your response as quickly as possible (but accept the minor additional latency when sending, as your client has to generate and encrypt the packets), or you might just send a few (e.g. 20) and then if your response requires more SURBs, send them along, accepting the additional latency in getting your response. -## Sending binary data +### Sending binary data You can also send bytes instead of JSON. For that you have to send a binary websocket frame containing a binary encoded Nym [`ClientRequest`](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/requests.rs#L25) containing the same information. @@ -83,7 +79,7 @@ Nym [`ClientRequest`](https://github.com/nymtech/nym/blob/develop/clients/native You can find examples of sending and receiving binary data in the [code examples](https://github.com/nymtech/nym/tree/master/clients/native/examples), and an example project from the Nym community [BTC-BC](https://github.com/sgeisler/btcbc-rs/): Bitcoin transaction transmission via Nym, a client and service provider written in Rust. -## Replying to SURB messages +### Replying to SURB messages Each bucket of `replySURBs`, when received as part of an incoming message, has a unique session identifier, which **only identifies the bucket of pre-addressed packets**. This is necessary to make sure that your app is replying to the correct people with the information meant for them in a situation where multiple clients are sending requests to a single service. Constructing a reply with SURBs looks something like this (where `senderTag` was parsed from the incoming message) @@ -96,7 +92,7 @@ Constructing a reply with SURBs looks something like this (where `senderTag` was } ``` -## Error messages +### Error messages Errors from the app's client, or from the gateway, will be sent down the websocket to your code in the following format: ```json @@ -106,12 +102,18 @@ Errors from the app's client, or from the gateway, will be sent down the websock } ``` -## LaneQueueLength +### LaneQueueLength This is currently only used in the [Socks Client](../socks5-client.md) to keep track of the number of Sphinx packets waiting to be sent to the mixnet via being slotted amongst cover traffic. As this value becomes larger, the client signals to the application it should slow down the speed with which it writes to the proxy. This is to stop situations arising whereby an app connected to the client appears as if it has sent (e.g.) a bunch of messages and is awaiting a reply, when they in fact have not been sent through the mixnet yet. -# Message Responses -Responses to your messages are defined [here](https://github.com/nymtech/nym/blob/develop/clients/native/websocket-requests/src/responses.rs): +## Message Responses +Responses to your messages are defined [here](https://github.com/nymtech/nym/blob/master/clients/native/websocket-requests/src/responses.rs#L47): -```rust,noplayground -{{#include ../../../../../clients/native/websocket-requests/src/responses.rs:48:53}} +```rust +#[derive(Debug)] +pub enum ServerResponse { + Received(ReconstructedMessage), + SelfAddress(Box), + LaneQueueLength { lane: u64, queue_length: usize }, + Error(error::Error), +} ```