2. Hosted Services
Last updated
Was this helpful?
Last updated
Was this helpful?
In the previous example, we used a local, browser-native service to facilitate the string generation and communication with another browser. The real power of the Fluence solution, however, is that services can be hosted on one or more nodes, easily reused and composed into decentralized applications with Aqua.
In case you haven't set up your development environment, follow the setup instructions and clone the examples repo:
In this section, we develop a simple HelloWorld
service and host it on a peer-to-peer node of the Fluence testnet. In your IDE or terminal, change to the 2-hosted-services
directory and open the src/main.rs
file:
Fluence hosted services are comprised of WebAssembly modules implemented in Rust and compiled to wasm32-wasi. Let's have look at our code:
At the core of our implementation is the hello
function which takes a string parameter and returns the HelloWorld
struct consisting of the msg
and reply
field, respectively. We can use the build.sh
script in the scripts
directory, ./scripts/build.sh
, to compile the code to the wasi32-wasm target from the VSCode terminal:
In addition to some housekeeping, the build.sh
script gives the compile instructions with marine, marine build --release
, and copies the resulting Wasm module, hello_world.wasm
, to the artifacts
directory for easy access.
So far, so good. Of course, we want to test our code and we have a couple of test functions in our main.rs
file:
To run our tests, we can use the familiar cargo test
. However, we don't really care all that much about our native Rust functions being tested but want to test our WebAssembly functions. This is where the extra code in the test module comes into play. In short., we are running cargo test
against the exposed interfaces of the hello_world.wasm
module and in order to do that, we need the marine_test
macro and provide it with both the modules directory, i.e., the artifacts
directory, and the location of the Config.toml
file. Note that the Config.toml
file specifies the module metadata and optional module linking data. Moreover, we need to call our Wasm functions from the module namespace, i.e. hello_world.hello
instead of the standard hello
-- see lines 13 and 19 above, which we specify as an argument in the test function signature (lines 11 and 17, respectively).
In order to able able to use the macro, install the marine-rs-sdk-test
crate as a dev dependency:
[dev-dependencies] marine-rs-sdk-test = "
<version>"
From the IDE or terminal, we now run our tests with thecargo +nightly test --release
command. Please note that if nightly
is your default, you don't need it in your cargo test
command.
Well done -- our tests check out. Before we deploy our service to the network, we can interact with it locally using the Marine REPL. In your VSCode terminal the 2-hosted-services
directory run:
which puts us in the REPL:
We can explore the available interfaces with the i
command and see that the interfaces we marked with the marine
macro in our Rust code above are indeed exposed and available for consumption. Using the call
command, still in the REPL, we can access any available function in the module namespace, e.g., call hello_word hello [<string arg>]
. You can exit the REPL with the ctrl-c
command.
In anticipation of future needs, note that marine
allows us to export the Wasm interfaces ready for use in Aqua. In your VSCode terminal, navigate to the `2-hosted-services` directory
Which gives us the Aqua-ready interfaces:
That can be piped directly into an aqua file , e.g., `marine aqua my_wasm.wasm >> my_aqua.aqua
.
Looks like all is in order with our module and we are ready to deploy our HelloWorld
service to the world by means of the Fluence peer-to-peer network. For this to happen, we need two things: the peer id of our target node(s) and a way to deploy the service. The latter can be accomplished with the aqua
command line tool and with respect to the former, we can get a peer from one of the Fluence testnets with aqua
. In your VSCode terminal:
Which gets us a list of network peers:
Let's use the peer12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi
as our deployment target and deploy our service from the VSCode terminal.
To do so we first need to generate a secret key
. Run:
Replace <YOUR_SECRET_KEY>
with the generated secret key and while in the quickstart/2-hosted-services
directory run:
Which gives us a unique service id:
Take note of the service id, 09d9a052-8ccd-4627-9b3a-b72fe6571c87 in this example but different for you, as we need it to use the service with Aqua.
Congratulations, we just deployed our first reusable service to the Fluence network and we can admire our handiwork on the Fluence Developer Hub:
With our newly created service ready to roll, let's move on and put it to work.