This project serves as an example/template for building an application using WebAssembly Component Model (and in this case, an app for Ziverge's Golem Cloud). It is my recommendation on how to structure such a project.
Before I start the walkthrough and explain the project structure, make sure you have set up Rust's toolchain and installed cargo-component. Please refer to Golem Cloud documentation for instructions.
The core business logic of our application goes into the lib module, where our code can be organized into logical units and only a select set of functions (and structs) are exposed as public APIs. This is quite common in Rust applications.
Like most Rust apps, we can write unit tests in each sub-module as well as integration tests in a separate tests module.
To run tests at the project's root, simply do cargo nextest run -p lib. (I highly recommend using cargo-nextest as the test runner.) Note the -p parameter at the end of the command -- we are passing the name of this module as the value.
We can also check test coverage by running cargo tarpaulin -p lib. (Run cargo install cargo-tarpaulin to add the sub-command.)
This one is optional. However, I feel it's beneficial to build a console app, which not only provides us a way to system-test our APIs defined in the lib module but, rather importantly, it can guide us through the process of designing the APIs, especially in the early iterations. While calling the APIs in a console app might be slightly different than calling them from the Wasm component (because the execution flow may likely be different), we can still try to mimic, as much as possible, the cloud API flow (exposed by the Wasm component -- we're speaking in the context of running it on Golem Cloud here). By doing so, this console app shall give us a very close feel of how our APIs will work. This will provide a fast feedback loop and allow us to iterate quicker and with more confidence; at the same time it should help minimize the potential of a bad API design.
To run the console app at the project root, do cargo run -p app. Again, we will pass the -p parameter and specify the app module. If you want to produce a binary of the console app, running cargo build -p app will produce the executable as target/debug/app (or target/release/app if the --release flag is included in the build command).
Now that we have tests and the console app to guide the implementation, we should have a very good idea of how our APIs will look like. Thereby, we shall express our APIs in the wit file. Next, we will add some boilerplate code in the wasm module to glue the Rust bindings to our Wasm implementation. Please refer to the code in wasm\lib.rs as well as Golem's documentation. The implementation in the Wasm module should be fairly trivial and quite similar to that of the console app.
To build the Wasm assembly, run cargo component build --release -p wasm at the root of our project directory. This will produce the target/wasm32-wasi/release/wasm.wasm file in this case.
As a quick reference, here are the steps to run this app on Golem Cloud. For details of various commands, please refer to Golem CLI documentation as well as its built-in help.
Upload this app and run it on Golem Cloud:
- Download the latest version of Golem CLI by signing up for the Developer Preview.
- Install Golem CLI by running
cargo install golem-cli. - Run
golem-cli account getto go through the authorization process if you haven't done so. cdto the root of our project directory.- Run the following command to upload the binary.
golem-cli template add --template-name fib target/wasm32-wasi/release/wasm.wasm- Next, run this command to create a worker for our app.
golem-cli worker add --worker-name fib-wrkr-1 --template-name fib- Let's define a shell alias to invoke the instance. For example:
alias fib='golem-cli worker invoke-and-await --worker-name fib-wrkr-1 --template-name fib --function $*'Note:
invoke-and-awaitis akin to Akka'saskpattern whereas theinvokecommand is fire-and-forget.
- At last let's run our app! 🎉
- Run the
nextcommand to get the next Fibonacci number. Repeat it a few times to verify that it produces the correct Fibonacci sequence.
fib golem:fib/api/next --parameters '[]'- Run the
resetcommand to start over from 0.
fib golem:fib/api/reset --parameters '[]'Congratulations! We have written, deployed and executed our first Golem app!
Now that we know our app is running as expected, we can test out the promise of Golem Cloud that apps are resilient and their states are preserved between interruptions.
We can interrupt our app by executing:
golem-cli worker interrupt --worker-name fib-wrkr-1 --template-name fib(or simulate a crash with golem-cli worker simulated-crash --worker-name fib-wrkr-1 --template-name fib).
After that, run fib golem:fib/api/next --parameters '[]' again and verify that the Fibonacci number continues from that of the last invocation.
I can tell you there is a bug somewhere in this implementation. Can you identify it as an exercise? If so, give it a shot at fixing it. PRs are welcome! 🙂 I have something in mind for the fix (I actually have a reason why I don't want to fix it 😝) but I'm interested in other solutions.
Thanks for reading 🙏 and have fun writing Golem apps!
This project is definitely very very simple! For (slightly) more complex apps, check out my other Golem's projects here and here.