Worker to Worker communication for Rust components

See the Worker to Worker communication page for a general overview of how workers can invoke each other in Golem.

Setting up

For doing worker to worker communication between Golem components implemented in Rust, in addition to the Rust compiler and the cargo-component tool described in the setup page, we need two additional dependencies:

• The golem-cli tool which automates some steps of setting up the communication between workers.
• The cargo-make crate task runner used to further automate the build steps.

Install cargo-make by running:

$ cargo install cargo-make

Creating a project with two components

A project building two Golem components where one can call the other can be set up with the following primary steps:

[workspace]
resolver = "2"
 
# list the two components here
members = [
    "component1",
    "component2"
]
 
# common release profile for all components
[profile.release]
opt-level = "s"
lto = true
strip = true

$ cargo component build
...
Creating component target/wasm32-wasi/debug/component2.wasm
Creating component target/wasm32-wasi/debug/component1.wasm

$ golem-cli stubgen initialize-workspace --targets component1 --callers component2
...
Writing updated Cargo.toml to "/Users/vigoo/tmp/doc-temp/rpc/Cargo.toml"
Done

$ cargo make build-flow
...
Error: no dependencies of component `target/wasm32-wasi/debug/component2.wasm` were found
[cargo-make] ERROR - Error while executing command, exit code: 1
[cargo-make] WARN - Build Failed.

// ...
world component2 {
  import demo:component1-stub/stub-component1; // new line added
  export api;
}

Writing blocking remote calls

For each exported function in the target component, the generated stub contains two exported variants:

• A blocking variant, prefixed with blocking-, which does not return until the remote worker finished processing the call.
• A non-blocking variant, which returns a pollable result immediately (unless for remote functions without any return value, in which case it just triggers the invocation but does not return anything)

To use the blocking variants we need to construct a resource from the generated stub, passing the remote Golem URI of the target worker to the constructor.

Taking the rust-minimal-actor example as the target component, which has the following exported interface:

package demo:component1;
 
interface api {
  add: func(value: u64);
  get: func() -> u64;
}
 
world component1 {
  export api;
}

The generated stub will contain the following functions:

package demo:component1-stub;
 
interface stub-component1 {
  use golem:rpc/types@0.1.0.{uri};
  use wasi:io/poll@0.2.0.{pollable};
 
  resource future-get-result {
    subscribe: func() -> pollable;
    get: func() -> option<u64>;
  }
  resource api {
    constructor(location: uri);
    blocking-add: func(value: u64);
    add: func(value: u64);
    blocking-get: func() -> u64;
    get: func() -> future-get-result;
  }
 
}
 
world wasm-rpc-stub-component1 {
  export stub-component1;
}

To use this generated api resource, the following steps are needed in the caller component (component2 in the example):

use crate::bindings::golem::rpc::types::Uri;
use crate::bindings::demo::component1_stub::stub_component1::*;

let component_id =
    std::env::var("TARGET_COMPONENT_ID").expect("TARGET_COMPONENT_ID not set");
let target_uri = Uri {
    value: format!("urn:worker:{component_id}/target-worker"),
};

let target_uri = Uri {
    value: format!("urn:worker:{component_id}"),
};

let remote_api = Api::new(&target_uri);
remote_api.blocking_get()

Writing non-blocking remote calls

Using the non-blocking variants of the generated stub functions requires the same steps as the blocking variants, but the returned value is a special future which needs to be subscribed to and polled using the low-level WASI poll interface.

The following snippet demonstrates how to get the value of three counters simultaneously, assuming that counter1, counter2 and counter3 are all insteances of the generated stub's Api resource:

// Making the non-blocking calls
let future_value1 = counter1.get_value();
let future_value2 = counter2.get_value();
let future_value3 = counter3.get_value();
 
let futures = &[&future_value1, &future_value2, &future_value3];
 
// Subscribing to get the results
let poll_value1 = future_value1.subscribe();
let poll_value2 = future_value2.subscribe();
let poll_value3 = future_value3.subscribe();
 
let mut values = [0u64; 3];
let mut remaining = vec![&poll_value1, &poll_value2, &poll_value3];
let mut mapping = vec![0, 1, 2];
 
// Repeatedly poll the futures until all of them are ready
while !remaining.is_empty() {
    let poll_result = bindings::wasi::io::poll::poll(&remaining);
 
    // poll_result is a list of indexes of the futures that are ready
    for idx in &poll_result {
        let counter_idx = mapping[*idx as usize];
        let future = futures[counter_idx];
        let value = future
            .get()
            .expect("future did not return a value because after marked as completed");
        values[counter_idx] = value;
    }
 
    // Removing the completed futures from the list
    remaining = remaining
        .into_iter()
        .enumerate()
        .filter_map(|(idx, item)| {
            if poll_result.contains(&(idx as u32)) {
                None
            } else {
                Some(item)
            }
        })
        .collect();
 
    // Updating the index mapping
    mapping = mapping
        .into_iter()
        .enumerate()
        .filter_map(|(idx, item)| {
            if poll_result.contains(&(idx as u32)) {
                None
            } else {
                Some(item)
            }
        })
        .collect();
}
 
// values contains the results of the three calls

Deploying the resulting components

To build deployable WASM files of the involved components, use

$ cargo make release-build-flow
...
Creating component target/wasm32-wasi/release/component1.wasm
Creating component target/wasm32-wasi/release/component2.wasm
Creating component target/wasm32-wasi/release/component1_stub.wasm
...
Writing composed component to "target/wasm32-wasi/release/component2_composed.wasm"
Done

In this example, where component1 was the target, and component2 was the caller, the following artifacts are to be deployed:

• target/wasm32-wasi/release/component1.wasm is the target component which itself does not perform any remote procedure calls
• target/wasm32-wasi/release/component2_composed.wasm is the version of component2 composed with the RPC stubs, ready to be deployed to Golem

Adding new connections in a workspace

When during development new components are added to the workspace, and/or new connections need to be estabilished between them, running the golem-cli stubgen initialize-workspace command again will regenerate the build steps in the cargo makefile. Make sure to list all the targets and callers, not just the new ones.

There is currently no automated way to remove connections from the workspace. If this is needed, the generated stub subprojects and their WIT definitions from the caller component's wit/deps must be removed manually.