From f28f11ff5d3cd8d15ed52e37f6fa2c77ef138de2 Mon Sep 17 00:00:00 2001 From: mfahampshire Date: Wed, 9 Oct 2024 14:27:06 +0200 Subject: [PATCH] reorg + added FFI table --- .../docs/pages/developers/rust/_meta.json | 9 +-- .../developers/rust/development-status.md | 13 ++-- .../docs/pages/developers/rust/ffi.mdx | 64 +++++++++---------- .../docs/pages/developers/rust/importing.md | 16 +---- .../docs/pages/developers/rust/mixnet.mdx | 11 ++++ .../pages/developers/rust/mixnet/_meta.json | 6 ++ .../developers/rust/{ => mixnet}/examples.md | 0 .../rust/{ => mixnet}/examples/_meta.json | 0 .../rust/{ => mixnet}/examples/builders.md | 0 .../{ => mixnet}/examples/builders/_meta.json | 0 .../examples/builders/builder-with-storage.md | 0 .../{ => mixnet}/examples/builders/builder.md | 0 .../{ => mixnet}/examples/custom-topology.md | 0 .../examples/custom-topology/_meta.json | 0 .../custom-topology/custom-provider.md | 0 .../manually-overwrite-topology.md | 0 .../rust/{ => mixnet}/examples/simple.md | 0 .../rust/{ => mixnet}/examples/socks.md | 0 .../rust/{ => mixnet}/examples/split-send.md | 0 .../rust/{ => mixnet}/examples/storage.md | 0 .../rust/{ => mixnet}/examples/surbs.md | 0 .../rust/{ => mixnet}/message-helpers.md | 0 .../rust/{ => mixnet}/message-types.md | 0 .../rust/{ => mixnet}/troubleshooting.md | 0 .../docs/pages/developers/rust/tcpproxy.mdx | 1 + 25 files changed, 62 insertions(+), 58 deletions(-) create mode 100644 documentation/docs/pages/developers/rust/mixnet.mdx create mode 100644 documentation/docs/pages/developers/rust/mixnet/_meta.json rename documentation/docs/pages/developers/rust/{ => mixnet}/examples.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/_meta.json (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/builders.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/builders/_meta.json (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/builders/builder-with-storage.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/builders/builder.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/custom-topology.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/custom-topology/_meta.json (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/custom-topology/custom-provider.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/custom-topology/manually-overwrite-topology.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/simple.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/socks.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/split-send.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/storage.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/examples/surbs.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/message-helpers.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/message-types.md (100%) rename documentation/docs/pages/developers/rust/{ => mixnet}/troubleshooting.md (100%) create mode 100644 documentation/docs/pages/developers/rust/tcpproxy.mdx diff --git a/documentation/docs/pages/developers/rust/_meta.json b/documentation/docs/pages/developers/rust/_meta.json index d61c3218be..3fca1da31f 100644 --- a/documentation/docs/pages/developers/rust/_meta.json +++ b/documentation/docs/pages/developers/rust/_meta.json @@ -1,11 +1,8 @@ { - "development-status": "Development Status", "importing": "Importing", - "modules": "Modules", - "examples": "Basic Examples", - "message-helpers": "Message Helpers", - "message-types": "Message Types", - "troubleshooting": "Troubleshooting", + "development-status": "Development Status", + "mixnet": "Mixnet Module", + "tcpproxy": "TcpProxy Module", "ffi": "FFI", "tutorials": "Tutorials (Coming Soon)" } diff --git a/documentation/docs/pages/developers/rust/development-status.md b/documentation/docs/pages/developers/rust/development-status.md index a7edbe144c..ad07537bbb 100644 --- a/documentation/docs/pages/developers/rust/development-status.md +++ b/documentation/docs/pages/developers/rust/development-status.md @@ -1,14 +1,17 @@ # Development status The SDK is still somewhat a work in progress: interfaces are fairly stable but still may change in subsequent releases. -In the future the SDK will be made up of several components, each of which will allow developers to interact with different parts of Nym infrastructure. +In the future the SDK will be made up of several modules, each of which will allow developers to interact with different parts of Nym infrastructure. -| Component | Functionality | Released | +| Module | Functionality | Released | |-----------|---------------------------------------------------------------------------------------|----------| | Mixnet | Create / load clients & keypairs, subscribe to Mixnet events, send & receive messages | ✔ī¸ | -| Ecash | Create & verify Ecash credentials | 🛠ī¸ | +| TcpProxy | Utilise the TcpProxyClient and TcpProxyServer abstractions for streaming | ✔ī¸ | +| Ecash | Create & verify Ecash credentials | 🛠ī¸ | | Validator | Sign & broadcast Nyx blockchain transactions, query the blockchain | ❌ | -The `mixnet` component currently exposes the logic of two clients: the [websocket client]() TODO LINK, and the [socks]() TODO client. +The `Mixnet` module currently exposes the logic of two clients: the [websocket client]() TODO LINK, and the [socks]() TODO client. -The `ecash` component is currently being worked on. Right now it exposes logic allowing for the creation of Ecash credentials on the Sandbox testnet. +The `TcpProxy` module exposes functionality to set up client/server instances that expose a localhost TcpSocket to read/write to. + +The `Ecash` module is in progress. Right now it exposes logic allowing for the creation of zk-nym credentials on the Sandbox testnet. diff --git a/documentation/docs/pages/developers/rust/ffi.mdx b/documentation/docs/pages/developers/rust/ffi.mdx index 6e1834aa0a..33cdd16c0a 100644 --- a/documentation/docs/pages/developers/rust/ffi.mdx +++ b/documentation/docs/pages/developers/rust/ffi.mdx @@ -8,44 +8,42 @@ import { Callout } from 'nextra/components' We currently have FFI bindings for Go and C/C++. See the table below to check the coverage of functionality we expect devs would like to see. +The `sdk/ffi` directory has the following structure: + +``` +ffi +├── cpp +├── go +├── README.md +└── shared +``` + +The main functionality of exposed functions will be imported from `sdk/ffi/shared` into `sdk/ffi/` in order to cut down on code duplication, and so that the imported bindings can be language-specific with regards to types and any `unsafe` code that is required, as well as allowing for the use of language-specific FFI libraries in the future (e.g. we are using `uniffi-bindgen-go` for Go, and at the moment have custom C/C++ bindings, which we might in the future replace with `cxx`). + ### Mixnet Module -This is the basic mixnet component of the SDK, exposing client functionality with which people can build custom interfaces with the Mixnet. +This is the basic mixnet component of the SDK, exposing client functionality with which people can build custom interfaces with the Mixnet. These functions are exposed to both Go and C/C++ via the `sdk/ffi/shared/` crate. -| Rust Function | Go | C/C++ | -| :----------------------------------------------- | :--: | ----: | -| `MixnetClient::connect_new()` | ✔ī¸ | ✔ī¸ | -| `MixnetClientBuilder::new_with_default_storage` | ✔ī¸ | ✔ī¸ | -| `MixnetClientBuilder::OTHERS` | | | -| `MixnetClientBuilder::OTHERS` | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | +| `shared/lib.rs` function | Rust Function | +| ------------------------------------------------------------- | ----------------------------------------------------------------------- | +| `init_ephemeral_internal()` | `MixnetClient::connect_new()` | +| `init_default_storage_internal(config_dir: PathBuf)` | `MixnetClientBuilder::new_with_default_storage(config_dir)` | +| `get_self_address_internal()` | `MixnetClient.nym_address()` | +| `send_message_internal(recipient: Recipient, message: &str)` | `MixnetClient.send_plain_message(recipient, message)` | +| `reply_internal(recipient: AnonymousSenderTag, message: &str)`| `MixnetClient.send_reply(recipient, message)` | -> We have also implemented `listen_for_incoming()` which is a wrapper around the Mixnet client's `wait_for_messages()` which is exposed to Go and C/C++. This is a helper method for listening out for and handling incoming messages. +> We have also implemented `listen_for_incoming_internal()` which is a wrapper around the Mixnet client's `wait_for_messages()`. This is a helper method for listening out for and handling incoming messages. ### TcpProxy Module -A connection abstraction TODO LINK which exposes a local TCP socket which developers are able to interact with basically as expected, being able to read/write to/from a bytestream, without really having to take into account the workings of the Mixnet/Sphinx/the message-based TODO LINK format of the underlying client. +A connection abstraction which exposes a local TCP socket which developers are able to interact with basically as expected, being able to read/write to/from a bytestream, without really having to take into account the workings of the Mixnet/Sphinx/the [message-based](../concepts/messages) format of the underlying client. -| Rust Function | Go | C/C++ | -| :----------------- | :--: | ----: | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | +> At the time of writing this functionality is **only** exposed to Go. C/C++ bindings will follow in the future in a larger update to the C FFI. - ----------------- -for copypaste - ❌ ✔ī¸ ----------------- +| `shared/lib.rs` function | Rust Function | +| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| `proxy_client_new_internal(server_address: Recipient, listen_address: &str, listen_port: &str, close_timeout: u64, env: Option)`| `NymProxyClient::new(server_address, listen_address, listen_port, close_timeout, env)`| +| `proxy_client_new_defaults_internal(server_address, env)` | `NymProxyClient::new_with_defaults(server_address, env)` | +| `proxy_client_run_internal()` | `NymProxyClient.run()` | +| `proxy_server_new_internal(upstream_address: &str, config_dir: &str, env: Option)` | `NymProxyServer::new(upstream_address, config_dir, env)` | +| `proxy_server_run_internal()` | `NymProxyServer.run_with_shutdown()` | +| `proxy_server_address_internal()` | `NymProxyServer.nym_address()` | diff --git a/documentation/docs/pages/developers/rust/importing.md b/documentation/docs/pages/developers/rust/importing.md index b2cf1f490c..7a4c9cf918 100644 --- a/documentation/docs/pages/developers/rust/importing.md +++ b/documentation/docs/pages/developers/rust/importing.md @@ -1,11 +1,5 @@ # Installation -The `nym-sdk` crate is **not yet available via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file: - -```toml -nym-sdk = { git = "https://github.com/nymtech/nym" } -``` - -By default the above command will import the current `HEAD` of the default branch, which in our case is `develop`. Assuming instead you wish to pull in another branch (e.g. `master` or a particular release) you can specify this like so: +The `nym-sdk` crate is **not yet available via [crates.io](https://crates.io)**. As such, in order to import the crate you must specify the Nym monorepo in your `Cargo.toml` file. Since the `HEAD` of `master` is always the most recent release, we recommend developers use that for their imports, unless they have a reason to pull in a specific historic version of the code. ```toml # importing HEAD of master branch @@ -14,10 +8,4 @@ nym-sdk = { git = "https://github.com/nymtech/nym", branch = "master" } nym-sdk = { git = "https://github.com/nymtech/nym", branch = "release/2023.3-kinder" } ``` -You can also define a particular git commit to use as your import like so: - -```toml -nym-sdk = { git = "https://github.com/nymtech/nym", rev = "85a7ec9f02ca8262d47eebb6c3b19d832341b55d" } -``` - -Since the `HEAD` of `master` is always the most recent release, we recommend developers use that for their imports, unless they have a reason to pull in a specific historic version of the code. +Work will occur in the future to break the monorepo down into importable features, in order to reduce the number of dependencies imported by developers. diff --git a/documentation/docs/pages/developers/rust/mixnet.mdx b/documentation/docs/pages/developers/rust/mixnet.mdx new file mode 100644 index 0000000000..396bd3563d --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet.mdx @@ -0,0 +1,11 @@ +import { Callout } from 'nextra/components' + +# Mixnet Module + +This module exposes the logic of creating and interacting with clients and Mixnet messages. This is recommended for those wanting to either start playing around with the Mixnet and how it works, or build connection logic. + + + +For developers wanting something more 'plug and play' we recommend the [`TcpProxy` module](./tcpproxy). + + diff --git a/documentation/docs/pages/developers/rust/mixnet/_meta.json b/documentation/docs/pages/developers/rust/mixnet/_meta.json new file mode 100644 index 0000000000..4797072ab7 --- /dev/null +++ b/documentation/docs/pages/developers/rust/mixnet/_meta.json @@ -0,0 +1,6 @@ +{ + "examples": "Basic Examples", + "message-helpers": "Message Helpers", + "message-types": "Message Types", + "troubleshooting": "Troubleshooting" +} diff --git a/documentation/docs/pages/developers/rust/examples.md b/documentation/docs/pages/developers/rust/mixnet/examples.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples.md rename to documentation/docs/pages/developers/rust/mixnet/examples.md diff --git a/documentation/docs/pages/developers/rust/examples/_meta.json b/documentation/docs/pages/developers/rust/mixnet/examples/_meta.json similarity index 100% rename from documentation/docs/pages/developers/rust/examples/_meta.json rename to documentation/docs/pages/developers/rust/mixnet/examples/_meta.json diff --git a/documentation/docs/pages/developers/rust/examples/builders.md b/documentation/docs/pages/developers/rust/mixnet/examples/builders.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/builders.md rename to documentation/docs/pages/developers/rust/mixnet/examples/builders.md diff --git a/documentation/docs/pages/developers/rust/examples/builders/_meta.json b/documentation/docs/pages/developers/rust/mixnet/examples/builders/_meta.json similarity index 100% rename from documentation/docs/pages/developers/rust/examples/builders/_meta.json rename to documentation/docs/pages/developers/rust/mixnet/examples/builders/_meta.json diff --git a/documentation/docs/pages/developers/rust/examples/builders/builder-with-storage.md b/documentation/docs/pages/developers/rust/mixnet/examples/builders/builder-with-storage.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/builders/builder-with-storage.md rename to documentation/docs/pages/developers/rust/mixnet/examples/builders/builder-with-storage.md diff --git a/documentation/docs/pages/developers/rust/examples/builders/builder.md b/documentation/docs/pages/developers/rust/mixnet/examples/builders/builder.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/builders/builder.md rename to documentation/docs/pages/developers/rust/mixnet/examples/builders/builder.md diff --git a/documentation/docs/pages/developers/rust/examples/custom-topology.md b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/custom-topology.md rename to documentation/docs/pages/developers/rust/mixnet/examples/custom-topology.md diff --git a/documentation/docs/pages/developers/rust/examples/custom-topology/_meta.json b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/_meta.json similarity index 100% rename from documentation/docs/pages/developers/rust/examples/custom-topology/_meta.json rename to documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/_meta.json diff --git a/documentation/docs/pages/developers/rust/examples/custom-topology/custom-provider.md b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/custom-provider.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/custom-topology/custom-provider.md rename to documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/custom-provider.md diff --git a/documentation/docs/pages/developers/rust/examples/custom-topology/manually-overwrite-topology.md b/documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/manually-overwrite-topology.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/custom-topology/manually-overwrite-topology.md rename to documentation/docs/pages/developers/rust/mixnet/examples/custom-topology/manually-overwrite-topology.md diff --git a/documentation/docs/pages/developers/rust/examples/simple.md b/documentation/docs/pages/developers/rust/mixnet/examples/simple.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/simple.md rename to documentation/docs/pages/developers/rust/mixnet/examples/simple.md diff --git a/documentation/docs/pages/developers/rust/examples/socks.md b/documentation/docs/pages/developers/rust/mixnet/examples/socks.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/socks.md rename to documentation/docs/pages/developers/rust/mixnet/examples/socks.md diff --git a/documentation/docs/pages/developers/rust/examples/split-send.md b/documentation/docs/pages/developers/rust/mixnet/examples/split-send.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/split-send.md rename to documentation/docs/pages/developers/rust/mixnet/examples/split-send.md diff --git a/documentation/docs/pages/developers/rust/examples/storage.md b/documentation/docs/pages/developers/rust/mixnet/examples/storage.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/storage.md rename to documentation/docs/pages/developers/rust/mixnet/examples/storage.md diff --git a/documentation/docs/pages/developers/rust/examples/surbs.md b/documentation/docs/pages/developers/rust/mixnet/examples/surbs.md similarity index 100% rename from documentation/docs/pages/developers/rust/examples/surbs.md rename to documentation/docs/pages/developers/rust/mixnet/examples/surbs.md diff --git a/documentation/docs/pages/developers/rust/message-helpers.md b/documentation/docs/pages/developers/rust/mixnet/message-helpers.md similarity index 100% rename from documentation/docs/pages/developers/rust/message-helpers.md rename to documentation/docs/pages/developers/rust/mixnet/message-helpers.md diff --git a/documentation/docs/pages/developers/rust/message-types.md b/documentation/docs/pages/developers/rust/mixnet/message-types.md similarity index 100% rename from documentation/docs/pages/developers/rust/message-types.md rename to documentation/docs/pages/developers/rust/mixnet/message-types.md diff --git a/documentation/docs/pages/developers/rust/troubleshooting.md b/documentation/docs/pages/developers/rust/mixnet/troubleshooting.md similarity index 100% rename from documentation/docs/pages/developers/rust/troubleshooting.md rename to documentation/docs/pages/developers/rust/mixnet/troubleshooting.md diff --git a/documentation/docs/pages/developers/rust/tcpproxy.mdx b/documentation/docs/pages/developers/rust/tcpproxy.mdx new file mode 100644 index 0000000000..178c05d288 --- /dev/null +++ b/documentation/docs/pages/developers/rust/tcpproxy.mdx @@ -0,0 +1 @@ +# TcpProxy Module