[][src]Crate gfaas

This crate allows you to distributed heavy-workload functions to the Golem Network (or any other compatible backend when support for it is added in the future).

Quick start

The usage is pretty straightforward. In your Cargo.toml, put gfaas as your dependency

# Cargo.toml
gfaas = "0.3"

You can now annotate some heavy-workload function to be distributed on the Golem Network like so

This example is not tested
use gfaas::remote_fn;

fn hello(input: String) -> String {
    // let's make the input all-caps

async fn main() {
    let input = "hey there gfaas";
    let output = hello("hey there gfaas".to_string()).await.unwrap();
    assert_eq!(input.to_uppercase(), output)

In order to compile your code you'll need to use our custom wrapper on top of cargo called gfaas. You can install the tool with cargo-install like so

cargo install gfaas-cli

Then, you can use gfaas like you would use cargo. So, to build and run on Golem Network, you'd execute

gfaas run

Notes about gfaas::remote_fn

When you annotate a function with gfaas::remote_fn attribute, it gets expanded into a full-fledged async function which is fallible. So for instance, the following function

This example is not tested
use gfaas::remote_fn;

fn hello(input: String) -> String;

expands into

This example is not tested
async fn hello(input: String) -> Result<String, gfaas::Error>;

Therefore, it is important to remember that you need to run the function in an async block and in order to get the result of your function back, you need to unpack it from the outer Result type.

The asyncness and the Result are there due to the nature of any distributed computation run on top of some network of nodes: it may fail due to reasons not related to your app such as network downtime, etc.

Furthermore, the input and output arguments of your function have to be serializable, and so they are expected to derive serde::Serialize and serde::Deserialize traits.

Specifying Golem's configuration parameters

You can currently set the following configuration parameters directly via gfaas::remote_fn attribute:

  • (maximum) budget in NGNT (defaults to 100):
This example is not tested
#[remote_fn(budget = 100)]
fn hello(input: String) -> String;
  • timeout in seconds (defaults to 10 minutes):
This example is not tested
#[remote_fn(timeout = 600)]
fn hello(input: String) -> String;
  • subnet tag (defaults to "devnet-alpha.2"):
This example is not tested
#[remote_fn(subnet = "devnet-alpha.2")]
fn hello(input: String) -> String;

Of course, nobody stops you from setting any number of parameters at once

This example is not tested
#[remote_fn(budget = 10, subnet = "my_subnet")]
fn hello(input: String) -> String;

Notes about gfaas build tool and adding dependecies for your functions

The reason that a custom wrapper around cargo is needed, is because the function annotated with gfaas::remote_fn, under-the-hood is actually automatically cross-compiled into a WASI binary.

In addition, since the functions are cross-compiled to WASI, you need to install wasm32-wasi target in your used Rust toolchain. Furthermore, for that same reason, not all crates are compatible with WASI yet, but you can manually specify which crates you want your functions to depend on by adding a [gfaas_dependencies] section to your Cargo.toml

# Cargo.toml
author = "Jakub Konka"

actix = "1"

log = "0.4"

Notes on running your app locally (for testing)

It is well known that prior to launching our app on some distributed network of nodes, it is convenient to first test the app locally in search of bugs and errors. This is also possible with gfaas. In order to force your app to run locally, simply pass run_local=true as argument to gfaas::remote_fn attribute

This example is not tested
#[remote_fn(run_local = true)]
fn hello(input: String) -> String;

This will spawn all of your annotated functions in separate threads on your machine locally, so you can verify that everything works as expected prior to launching the tasks on the Golem Network.


A couple illustrative examples of how to use this crate can be found in the examples/ directory. All examples require gfaas build tool to be built.



This is a private module. The stability of this API is not guaranteed and may change without notice in the future.



Re-export of anyhow::Error which is the default type returned by the expanded gfaas::remote_fn-annotated function.

Attribute Macros


The bread and butter of this crate.