The example shows one of the important Registry use-cases — services advertisement and discovery. So it is about discovery and usage by clients with the same Aqua code transparently without any knowledge about particular peer and service ids.

In the beginning, we will deploy a Rust echo service and call it with the Fluence CLI. Then we will start a JS/TS client with echo service and run it.

Secondly, we will use Registry to call registered services with exactly one piece of code without peer and service identifiers. And finally, we will show how to remove service records.

Note

If you face any dependencies issue, you can try to use fluence dependency to install any version of aqua, marine and mrepl available in npm and cargo registries:

$ fluence dependency
? Select dependency (Use arrow keys)
  NPM dependencies:
❯ aqua
  Cargo dependencies:
  marine
  mrepl

Set up environment

Install fluence cli:
```
npm i -g @fluencelabs/cli
```

Initialize Fluence project:

fluence init .

Output:

Successfully initialized Fluence project template at <your-path-to-registry-repo>/example

Install dependencies:
```
npm i
```
You can use VSCode with Aqua extension for syntax highlighting and better developer experience.

Add echo service in Rust

If you have Apple Silicon you should install marine manually, or you can ignore this step otherwise:
```
# for m1:
cargo install marine --root ~/.fluence/cargo
```

Add echo service:

fluence service add echoService

output:

$ fluence service add echoService
Added echoService to fluence.yaml

Following code returns a peer id of the host and an initial message:

#[marine]
pub fn echo(msg: String) -> String {
    format!("{}: {}", marine_rs_sdk::get_call_parameters().host_id, msg)
}

Test echo service locally with REPL

If you have Apple Silicon you should install mrepl manually, or you can ignore this step otherwise:
```
# for m1:
cargo install mrepl --root ~/.fluence/cargo
```

Run the following command to start REPL:

fluence service repl echoService

output:

$ fluence service repl echoService
Making sure service and modules are downloaded and built... done
Welcome to the Marine REPL (version 0.18.0)
Minimal supported versions
sdk: 0.6.0
interface-types: 0.20.0

app service was created with service id = 070fd906-a9e4-44af-963d-81a75526379c
elapsed time 55.397166ms

1>

Call echo function of echoService module and pass msg to it:

call echoService echo ["msg"]

output:

 1> call echoService echo ["msg"]
 result: String(": msg")
 elapsed time: 9.207542ms

Peer id is empty because that is default for Marine REPL.

You can always test your services before deployment with REPL. Check out documentation for more details.

Deploy service and test it on remote peer

Deploy service:

fluence deploy

Output, please note that peer ids and service ids may differ:

$ fluence deploy
Making sure all services are downloaded... done
Making sure all modules are downloaded and built... done

Going to deploy services described in ~/Documents/dev/fluencelabs/registry/example/fluence.yaml:

echoService:
get: echoService
deploy:
    - deployId: default


? Do you want to deploy all of these services? Yes
Deploying:
service: echoService
deployId: default
on: 12D3KooWCMr9mU894i8JXAFqpgoFtx6qnV1LFPSfVc3Y34N4h4LS
... done
Compiling ~/Documents/dev/fluencelabs/registry/example/.fluence/aqua/deployed.app.aqua... done

Currently deployed services listed in ~/Documents/dev/fluencelabs/registry/example/.fluence/app.yaml:

echoService:
default:
    - blueprintId: fd21793bae96d1519599346591bfe7ea75614d9fe7f7c824b279e5a2dc841ee0
    serviceId: 785487e4-de08-4fa4-bdfd-df981ec66da7
    peerId: 12D3KooWCMr9mU894i8JXAFqpgoFtx6qnV1LFPSfVc3Y34N4h4LS

The following code declares a module, imports App and EchoService, and defines a method to call echo:

module Main

import App from "deployed.app.aqua"
import EchoService from "services/echoService.aqua"
export App, echo

func echo(msg: string) -> string:
    services <- App.services()

    on services.echoService.default[0].peerId:
        EchoService services.echoService.default[0].serviceId
        res <- EchoService.echo(msg)
    <- res

Let’s test our echo service:

 fluence run -f 'echo("hi")'

Output:

$ fluence run -f 'echo("hi")'
Running:
  function: echo("hi")
  relay: /dns4/kras-08.fluence.dev/tcp/19001/wss/p2p/12D3KooWFtf3rfCDAfWwt6oLZYZbDfn9Vn7bv7g6QjjQxUUEFVBt
... done

Result:

[
  [
    "12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi: hi"
  ]
]

We've successfully built and deployed a service written in Rust, and called it from our Aqua code using the Fluence CLI.

Run echo service in JS/TS:

Check out src/aqua/export.aqua with an export of EchoService API to JS/TS:

module Export
import "services/echoService.aqua"
export EchoService

The following code registers a local EchoService:

// register local service with service id "echo"
await registerEchoService(serviceId, {echo: (msg) => {
    console.log("Received message:", msg);
    return peerId + ": " + msg
}});

The following code is calling our local JS/TS peer with EchoService:

func echoJS(peer: string, relay: string, serviceId: string, msg: string) -> string:
    on peer via relay:
        EchoService serviceId
        res <- EchoService.echo(msg)
    <- res

Start the client with our service: npm run start

...
> example@1.0.0 start
> node src/echo.js

📗 created a fluence peer 12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN with relay 12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi
Copy this code:
fluence run -f 'echoJS("12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN", "12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi", "echo", "msg")'

Open a new terminal in the same registry example directory, and execute the following command to check echo service:

$ fluence run -f 'echoJS("12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN", "12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi", "echo", "msg")'
Running:
  function: echoJS("12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN", "12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi", "echo", "msg")
  relay: /dns4/kras-09.fluence.dev/tcp/19001/wss/p2p/12D3KooWD7CvsYcpF9HE9CCV9aY3SJ317tkXVykjtZnht2EbzDPm
... done

Result:

"12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN: msg"

We've successfully started JS/TS peer with an EchoService and tested it with Fluence CLI.

Register both services in Registry

As service providers we would like all our echo services to be discoverable without specifying particular peer and service ids, in order to achieve that we should use Registry to advertise our services.

Firstly, we need to create a resource. A resource represents a group of services and has a corresponding resource id for its discovery. Secondly, we need to register the service records on this resource id. So the echo services can be discovered and resolved by the resource id only.

The following code registers resource with label echo:

func registerResource() -> ?string:
    resource_id, error <- createResource("echo")
    <- resource_id

Let’s register resource:
```
fluence run -f 'registerResource()'
```
output:
```
$ fluence run -f 'registerResource()'
Running:
  function: registerResource()
  relay: /dns4/kras-01.fluence.dev/tcp/19001/wss/p2p/12D3KooWKnEqMfYo9zvfHmqTLpLdiHXPe4SVqUWcWHDJdFGrSmcA
... done

Result:

[
  "5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB"
]
```
So the resource id is 5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB. Please note that the resource id might be different in your case.

Using the resource id we can access any registered service. There can be more registered echo services on different peers that we can use transparently.

This code registers deployed service by given resource_id:

func registerService(resource_id: string) -> *bool:
    results: *bool
    services <- App.services()
    for srv <- services.echoService.default:
        results <- registerServiceRecord(resource_id, "" ,srv.peerId, ?[srv.serviceId])
    <- results

fluence run -f 'registerService("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB")'

output:

$ fluence run -f 'registerService("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB")'
Running:
  function: registerService("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB")
  relay: /dns4/kras-05.fluence.dev/tcp/19001/wss/p2p/12D3KooWCMr9mU894i8JXAFqpgoFtx6qnV1LFPSfVc3Y34N4h4LS
... done

Result:

[
  [
    true
  ]
]

Next, we need to register JS service. For that we have Aqua imports and exports in src/aqua/export.aqua:

import registerServiceRecord from "@fluencelabs/registry/resources-api.aqua"
export registerServiceRecord

In src/echo.ts we should pass resource id as cmd argument:

let [success, error] = await registerServiceRecord(process.argv[2], "echo", peerId, serviceId);
console.log("registration result: ", success);

So, stop the previous JS client from the step 5 and run npm run start 5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB (Note: resource_id is from the step 2) output:

...
Copy this code to call this service:
fluence run -f 'echoJS("12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN", "12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi", "echo", "msg")'
registration result:  true

We've successfully registered both services, JS/TS and Rust, in Registry and now we can access them only with resource_id without knowledge of particular peer and service ids.

Call services with Registry (using resource_id)

In src/aqua/main.aqua defined echoAll to resolve services and call sequentially:

func echoAll(resource_id: string, msg: string) -> *string:
    -- 2 is the min number of peers we want to ask
    records <- resolveResource(resource_id, 2)
    results: *string
    for r <- records:
        on r.metadata.peer_id via r.metadata.relay_id:
            EchoService r.metadata.service_id!
            results <- EchoService.echo(msg)
    <- results

Let’s run all registered echo services with only resource id:

fluence run -f 'echoAll("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB", "hi")'

output:

$ fluence run -f 'echoAll("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB", "hi")'
Running:
function: echoAll("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB", "hi")
relay: /dns4/kras-06.fluence.dev/tcp/19001/wss/p2p/12D3KooWDUszU2NeWyUVjCXhGEt1MoZrhvdmaQQwtZUriuGN1jTr
... done

Result:

[
    [
        "12D3KooWFEwNWcHqi9rtsmDhsYcDbRUCDXH84RC4FW6UfsFWaoHi: hi",
        "12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN: hi"
    ]
]

Remove service record

If we want to remove a service record from resource, we should use unregisterService method from Resources API:

func unregisterEchoService(resource_id: string) -> *bool:
    results: *bool
    services <- App.services()
    for srv <- services.echoService.default:
        results <- unregisterService(resource_id, srv.peerId)
    <- results

Let's unregister our deployed EchoService:

fluence run -f 'unregisterEchoService("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB")'

output:

$ fluence run -f 'unregisterEchoService("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB")'
Running:
    function: unregisterEchoService("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB")
    relay: /dns4/kras-05.fluence.dev/tcp/19001/wss/p2p/12D3KooWCMr9mU894i8JXAFqpgoFtx6qnV1LFPSfVc3Y34N4h4LS
... done

Result:

[
    [
        true
    ]
]

Let’s run again echoAll method:

fluence run -f 'echoAll("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB", "hi")'

output:

$ fluence run -f 'echoAll("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB", "hi")'
Running:
function: echoAll("5pYpWB3ozi6fi1EjNs9X5kE156aA6iLECxTuVdJgUaLB", "hi")
relay: /dns4/kras-06.fluence.dev/tcp/19001/wss/p2p/12D3KooWDUszU2NeWyUVjCXhGEt1MoZrhvdmaQQwtZUriuGN1jTr
... done

Result:

[
    [
        "12D3KooWCmnhnGvKTqEXpVLzdrYu3TkQ3HcLyArGJpLPooJQ69dN: hi"
    ]
]

So now we know how to add and remove service records for Resource and use it for advertising and discovering services in runtime.

README.md Unescape Escape

Services advertisement and discovery

Overview

Note

Set up environment

Add echo service in Rust

Test echo service locally with REPL

Deploy service and test it on remote peer

Run echo service in JS/TS:

Register both services in Registry

Call services with Registry (using resource_id)

Remove service record

README.md