Skip to main content

Usage

Subo includes the WebAssembly toolchain for Suborbital projects.

The Suborbital Development Platform aims for Wasm to be a first-class citizen. subo is the toolchain for building Wasm Runnables for Reactr and Atmo. The subo CLI can build Wasm Runnables, and can package several Wasm Runnables into a deployable Bundle.

Building a Runnable in languages other than Go is designed to be simple and powerful:

impl runnable::Runnable for Example {
fn run(&self, input: Vec<u8>) -> Option<Vec<u8>> {
let in_string = String::from_utf8(input).unwrap();

Some(String::from(format!("hello {}", in_string)).as_bytes().to_vec())
}
}

subo will package your Runnable into a Wasm module that can be used by Reactr or Atmo and run just like any other Runnable! You can see examples of Runnables in the test project.

Create a project

To create a new project for Atmo or Reactr, use subo create project <name>. This will create a new folder which contains a Directive.yaml and an example Runnable.

Full options for create project:

create a new project for Atmo or Reactr

Usage:
subo create project <name> [flags]

Flags:
--branch string git branch to download templates from (default "main")
-h, --help help for project
--update-templates update with the newest templates

Create a Runnable

To create a new Runnable, use the create runnable command:

> subo create runnable <name>

Rust is chosen by default, but if you prefer Swift, just pass --lang=swift! You can now use the Runnable API to build your function. A directory is created for each Runnable, and each contains a .runnable.yaml file that includes some metadata.

The full options for create runnable:

Usage:
subo create <name> [flags]

Flags:
--branch string git branch to download templates from (default "main")
--dir string the directory to put the new runnable in (default "/Users/cohix-16/Workspaces/suborbital/subo")
-h, --help help for create
--lang string the language of the new runnable (default "rust")
--namespace string the namespace for the new runnable (default "default")
--update-templates update with the newest runnable templates

Building Wasm Runnables

It is reccomended that Docker be installed to build Wasm Runnables. See below if you do not have Docker installed.

To build your Runnable into a Wasm module for Reactr or Atmo, use the build command:

> subo build .

If the current working directory is a Runnable, subo will build it. If the current directory contains many runnables, subo will build them all. Any directory with a .runnable.yaml file is considered a Runnable and will be built. Building Runnables is not fully tested on Windows.

Bundles

By default, subo will write all of the Runnables in the current directory into a Bundle. Atmo uses Runnable Bundles to help you build powerful web services by composing Runnables declaratively. If you want to skip bundling, you can pass --no-bundle to subo build

The resulting Bundle can also be used with a Reactr instance by calling h.HandleBundle({path/to/bundle}). See the Reactr Wasm instructions for details.

The full options for build:

Usage:
subo build [dir] [flags]

Flags:
--builder-tag string use the provided tag for builder images
--docker build your project's Dockerfile. It will be tagged {identifier}:{appVersion}
-h, --help help for build
--langs strings build only Runnables for the listed languages (comma-separated)
--make string execute the provided make target before building the project Bundle
--mountpath string if passed, the Docker builders will mount their volumes at the provided path
--native use native (locally installed) toolchain rather than Docker
--no-bundle if passed, a .wasm.zip Bundle will not be generated
--relpath subo build if passed, the Docker builders will run subo build using the provided path, relative to '--mountpath'

Building without Docker

If you prefer not to use Docker, you can use the --native flag. This will cause subo to use your local machine's toolchain to build Runnables instead of Docker containers. You will need to install the toolchains yourself:

subo is continually evolving alongside Reactr and Atmo.

Suborbital Runnable API

Reactr and Atmo provide an API which gives Wasm Runnables the ability to access resources and communicate with the host application. This API currently has capabilities such as:

  • The ability to make HTTP requests
  • Structured logging
  • Access to persistent cache
  • Access to a static filesystem

This API will soon have:

  • The ability to render templates
  • Database access
  • Access to blob storage