DEV Community: Jarrod Overson

Async Streams in WebAssembly with WasmRS

Jarrod Overson — Wed, 11 Jan 2023 18:32:15 +0000

TL;DR: WasmRS is an implementation of RSocket for WebAssembly giving you reactive, async streams in and out of WASM modules.
GitHub | Protocol details | Rust source | Go source

WebAssembly has immense potential but it is hardly user-friendly. It's making strides but what we have to work with today is a slog. Baseline WebAssembly only works with integers and floating point values. Your typical "Hello world" is a cumbersome mess of reading raw memory and dealing with bytes. Once you figure out how to transfer complex data structures and make calls in both directions, you are left high and dry if your application needs to do anything asynchronous. When you eventually rig together an async WebAssembly solution, you're stuck when dealing with big data without streams. After streams, you'll eventually need to solve for back pressure. After back press... well you get the point.

And that's the story of how we got to WasmRS.

What's WasmRS?

WasmRS is an implementation of the RSocket protocol in WebAssembly with some reactive stream concepts thrown in for usability. With WasmRS you treat WebAssembly modules like tiny services you open bidirectional sockets into.

WasmRS uses RSocket framing and aligns terminology where possible to keep it familiar. RSocket defines four request types the protocol can handle:

Fire & Forget: a request that is sent where the response is ignored.
RequestResponse: an asynchronous request with a single payload returning a single payload.
RequestStream: a request with a single payload that returns a stream of payloads.
RequestChannel: a request that takes a stream that returns a stream.

If you are interested in the protocol details, check out the wasmRS protocol documentation here.

How do I use it?

Using wasmRS directly is a bit like using WebAssembly directly. There's a lot of boilerplate and many esoteric details to get right before you get what you want. If you're the sort that likes those details, check out the baseline Rust implementation in the repository. If you're like me, the details are great but getting started rapidly is more important.

Luckily, we've got apex templates to get us going.

Apexlang is a project template and code generation tool suite that automates much of the boilerplate and getting started headache for projects.

We can use the apex CLI and the project templates in nanobus/iota to whip up a new project with one line.

apex new git@github.com:nanobus/iota.git -p templates/rust example

The apex new command is like git clone plus templating. It makes kickstarting projects easy and keeps being useful with code generation you'll see below.

Hello, World!

Tip: This section bootstraps you into building with wasmRS. To get straight to streams, skip to the next section.

The example/ directory we just created is filled with a handful of new files. Most are rust-specific but take special note of the apex.axdl file. That's Apexlang and is what the apex CLI uses to keep generating code and documentation during the life of your project.

Edit the apex.axdl to look like this:

namespace "example"

interface MyApi @service {
  greet(target: string): string
}

Above, we define a service called MyApi that has one action, greet, that takes an argument and returns a string. The target argument is who to greet.

Now run apex generate to automagically generate a bunch of new files.

Note: The project template includes a justfile. The just tool is a task runner modeled after the good parts of make. If you have just installed, you can run apex generate with the task just codegen

$ apex generate
INFO Writing file ./src/actions/my_api/greet.rs (mode:644)
INFO Writing file ./src/lib.rs (mode:644)
INFO Writing file ./src/error.rs (mode:644)
INFO Writing file ./src/actions/mod.rs (mode:644)
INFO Formatting file ./src/error.rs
INFO Formatting file ./src/lib.rs
INFO Formatting file ./src/actions/mod.rs
INFO Formatting file ./src/actions/my_api/greet.rs

These new files include wasmRS boilerplate, scaffolding, and samples to get you started quickly.

The file ./src/actions/my_api/greet.rs contains a stub for our greet action.

use crate::actions::my_api_service::greet::*;

pub(crate) async fn task(input: Inputs) -> Result<Outputs, crate::Error> {
    todo!("Add implementation");
}

Turn our greeter into an appropriate 'Hello World!" by returning a string like below:

use crate::actions::my_api_service::greet::*;

pub(crate) async fn task(input: Inputs) -> Result<Outputs, crate::Error> {
    Ok(format!("Hello, {}!", input.target))
}

And build!

cargo build --target=wasm32-unknown-unknown

You'll find your new .wasm file at target/wasm32-unknown-unknown/release/example.wasm.

The included justfile has a build command that runs the cargo step above and puts the built .wasm files in a build/ directory. It also runs the codegen task before building to ensure files are up-to-date.
$ just build
$ ls build/
example.wasm

We'll need a suitable runner to see our WebAssembly run on the command line. For that, we can use NanoBus or the wasmrs-request binary.

Running our WebAssembly with `wasmrs-request`

To use the wasmrs-request tool, first install it with the command:

cargo install wasmrs-request

Then run:

wasmrs-request ./build/example.wasm example.MyApi greet '{"target":"World"}'

Output:

Hello, World!

Running our WebAssembly with NanoBus

Info: NanoBus is a framework for wiring components like wasmRS modules together into applications. If you want to turn a module like this into a web service or CLI app, check it out!

To use NanoBus we need a configuration that points to our .wasm file. Make an iota.yaml that looks like this:

id: example
version: 0.0.1
main: target/wasm32-unknown-unknown/release/example.wasm
# Or, if you're using `just build`:
# main: build/example.wasm

Run nanobus invoke with a piped payload to witness our Hello World executed in all its glory.

echo '{"target":"World"}' | nanobus invoke iota.yaml example.MyApi::greet

Output:

"Hello, World!"

Streams!

Now that you're familiar with building wasmRS WebAssembly and running it with NanoBus or wasmrs-request, let's get to streaming.

Your system's command line is a great place to experiment. Every CLI process's input and output is a stream.

Let's add a reverse method to our API that takes a stream of string and outputs a stream of string. This will let us pipe a file to our action and see the contents reversed, ready to pipe to another CLI process.

namespace "example"

interface MyApi @service {
  greet(target: string): string
  reverse(input: stream string): stream string
}

Run apex generate (or just codegen) to generate the new code:

$ apex generate
INFO Writing file ./src/actions/my_api/reverse.rs (mode:644)
INFO Writing file ./src/actions/mod.rs (mode:644)
INFO Formatting file ./src/actions/my_api/reverse.rs
INFO Formatting file ./src/actions/mod.rs

Notice how apex intelligently rewrites only some files and doesn't clobber your existing action. Generated files that shouldn't be edited typically have a header or warning calling it out. You're safe to edit others.

Our new stub looks a little different than the simple Request/Response stub above:

use crate::actions::my_api_service::reverse::*;

pub(crate) async fn task(
    mut input: FluxReceiver<Inputs, PayloadError>,
    outputs: Flux<Outputs, PayloadError>,
) -> Result<Flux<Outputs, PayloadError>, crate::Error> {
    todo!("Add implementation");
}

WasmRS uses terminology from RSocket and reactive-streams to stay consistent. A Flux is like a rust Stream mixed with a channel. You can push to it, pass it around, pipe one to another, and await values. A FluxReceiver is a Flux that you can only receive values from. It's like the receiving end of a channel implemented as a Stream.

To work with our streams, we await values from our input stream and push to our output stream. This example reverses each line of the input and sends it to the output.

use crate::actions::my_api_service::reverse::*;

pub(crate) async fn task(
  mut input: FluxReceiver<Inputs, PayloadError>,
  outputs: Flux<Outputs, PayloadError>,
) -> Result<Flux<Outputs, PayloadError>, crate::Error> {
  while let Some(line) = input.next().await {
    match line {
      Ok(line) => {
        outputs.send(line.chars().rev().collect()).unwrap();
      }
      Err(e) => outputs.error(PayloadError::application_error(e.to_string())).unwrap(),
    }
  }
  outputs.complete();
  Ok(outputs)
}

To build it, we can use the justfile again:

cargo build --release --target=wasm32-unknown-unknown
# or `just build`

To run it with wasmrs-request, we use the same path and action arguments as above with the addition of the --channel flag and piped input.

cat Cargo.toml |  wasmrs-request --channel ./build/example.wasm example.MyApi reverse

Now anything you pipe to our reverse action will come out reversed!

]egakcap[
"elpmaxe" = eman
"0.1.0" = noisrev
"1202" = noitide

]bil[
]"bilydc"[ = epyt-etarc

]esaeler.eliforp[
"slobmys" = pirts
1 = stinu-negedoc
eslaf = gubed
eurt = otl
"z" = level-tpo
"troba" = cinap

]seicnedneped[
"2.0" = tseug-srmsaw
"0.1" = rorresiht
} ]"evired"[ = serutaef ,eslaf = serutaef-tluafed ,"1" = noisrev { = edres
"1.0" = tiart-cnysa
"0.82.0" = ajnijinim

]seicnedneped-ved[

Streaming data is critical for large payloads. Dealing with an enormous file or an asynchronous stream of text would be difficult to impossible without streaming concepts. WasmRS lets you take WebAssembly to new levels.

Where to go next?

WasmRS is the protocol we're using for iota dependencies. Iotas are libraries, microservices, and WebAssembly modules that use a common protocol so they can be swapped out, integrated, composed, and tested without changing your application.

WasmRS is independent, generic and un-opinionated. You can use wasmRS in your own projects, use the iota code generators and run iotas yourself, or use wasmRS in completely new ways. The iota implementation is our opinionated implementation. Take what you want and leave what you don't.

Attribution

Photo by Jason Pischke on Unsplash

Apexlang: Project Templates & Code Generation

Jarrod Overson — Fri, 06 Jan 2023 18:02:14 +0000

TL;DR:

The apex CLI let you create projects from templates and the Apexlang IDL lets you generate code, documentation, schemas, and more from a single source. Quick links: Github Repo & apexlang.io homepage

How often do you start projects the same way? With the same boilerplate, same dependencies, same configuration, same everything? If you’re like me, you get your settings dialed in and reuse them in a base project template repeatedly. Eventually you might find yourself creating git repos or scripts to make this process buttery smooth.

Tools like yeoman, degit, and cargo generate kept me happy for years. They add basic templating capabilities to the standard git clone but they stop there. You’ll be hard pressed to find tools that go beyond setting up a directory structure.

That’s where Apexlang comes in. Apexlang is a code generation and templating tool suite. It started as an interface definition language (IDL) for WebAssembly called WIDL but was too useful to be hidden away. It now contains the base functionality of tools like degit combined with the code generation capability of tools like protoc and smithy. And unlike tools like protoc and smithy, code generators are written in TypeScript and are easier to get started with.

With Apexlang you get your boilerplate along with code, documentation, schemas, and more all generated automatically, continuously, and easily.

Check it out

$ apex new git@github.com:apexlang/codegen.git -p templates/nodejs my-project
Cloning into '/var/folders/pg/h7s94pd90w54hcbjpkvm58240000gn/T/77f11564'...
remote: Enumerating objects: 256, done.
remote: Counting objects: 100% (256/256), done.
remote: Compressing objects: 100% (210/210), done.
remote: Total 256 (delta 54), reused 135 (delta 18), pack-reused 0
Receiving objects: 100% (256/256), 150.38 KiB | 6.27 MiB/s, done.
Resolving deltas: 100% (54/54), done.
 ? Please enter the project description ›
INFO Writing file my-project/package.json (mode:100644)
INFO Writing file my-project/apex.yaml (mode:100644)
INFO Writing file my-project/apex.axdl (mode:100644)
INFO Writing file my-project/.gitignore (mode:100644)
INFO Writing file my-project/tsconfig.json (mode:100644)
INFO Writing file my-project/.vscode/settings.json (mode:100644)
INFO Writing file my-project/.vscode/tasks.json (mode:100644

The apex new command clones a repository to use as a template. The -p option above tells apex to use a sub-directory and you can use -b to specify a branch if necessary. The final argument is the directory to create.

The template itself has configuration defined in .template files like this one. Any file apex finds with a .tmpl extension is treated as a text file to render with data defined in the .template configuration along with user or environment variables.

Cloning projects and rendering templates is useful, but it's the tip of the iceberg.

The example above is a bare-bones TypeScript & node.js template. It includes an apex.axdl definition and an apex.yaml configuration file. These files are what drives apex after the initial project creation.

This templates' yaml configuration is simple. It points to the Apexlang definition file (an .axdl file) and specifies the code generator plugin to use.

spec: apex.axdl
plugins:
  - 'https://raw.githubusercontent.com/apexlang/codegen/main/src/typescript/plugin.ts'

Plugins dynamically generate further configuration based on the Apexlang definition. Yeah, apex uses Apexlang to configure apex configuration.

Plugins are TypeScript files that export a single function. The function takes in the current config along with an Apexlang spec, and spits out a new configuration.

The axdl file is where the magic is defined. It’s an interface definition language that looks a lot like GraphQL:

namespace "greeting.v1"

interface Greeter {
  sayHello(to: Person): string
}

type Person {
  firstName: string
  lastName: string
}

It models the parts you need to describe most APIs for languages and services.

With a configuration and an .axdl file, we can start generating code:

$ apex generate
INFO Writing file ./src/api.ts (mode:644)
INFO Writing file ./src/interfaces.ts (mode:644)
apex generate creates two newfiles, api.ts and interfaces.ts.

src/interfaces.ts illustrates how apex translates Apexlang types to TypeScript code. Apexlang interfaces become TypeScript interfaces and Apexlang types become TypeScript classes.

export interface Greeter {
  sayHello(to: Person): string;
}

export class Person {
  firstName: string;
  lastName: string;
  constructor({
    firstName = "",
    lastName = ""
  }: { firstName?: string; lastName?: string } = {}) {
    this.firstName = firstName;
    this.lastName = lastName;
  }
}

In src/api.ts, we get a boilerplate implementation of our interfaces that we can fill out with business logic. All the imports are handled for you and apex leaves you ready to start coding.

import { Greeter, Person } from "./interfaces";

class GreeterImpl implements Greeter {
  sayHello(to: Person): string {
    return "";
  }
}

We can also add documentation to our .axdl file and it will render as comments in the code.

namespace "greeting.v1"

"A simple greeting service"
interface Greeter {
  "Say hello to a Person"
  sayHello(to: Person): string
}
"An instance of a person"
type Person {
  "The person's first name"
  firstName: string
  "The person's last name"
  lastName: string
}
apex generate now produces this:

// A simple greeting service
export interface Greeter {
  // Say hello to a Person
  sayHello(to: Person): string;
}

// An instance of a person
export class Person {
  // The person's first name
  firstName: string;
  // The person's last name
  lastName: string;
  [rest snipped...]
}

More generators!

Writing what looks like code to generate a single instance of other code isn’t that exciting. You could have written the TypeScript by hand. But apex is more than just a code generator. It’s a code generation framework. It’s a templating framework. It’s a documentation framework. It’s a schema framework. It’s a configuration framework. It’s a framework for frameworks.

We can just as easily generate markdown documentation for our API by adding in a custom generates section. (These are what plugins generate for you but you can add your own manually.)

generates:
  API.md:
    module: https://deno.land/x/apex_codegen/markdown/mod.ts
    config:
      title: 'My Awesome Project'

The generates block is keyed with the file to be generated (i.e. API.md) and the generator configuration. In this case we're delegating to the markdown module of the official Apexlang codegen project.

This is the markdown we generate:

# My Awesome Project

Namespace: **`greeting.v1`**

## Interfaces

### **Greeter**

A simple greeting service

- **`sayHello(to: Person) -> string`**: Say hello to a Person

## Types

### **Person**

An instance of a person

- **`firstName: string`** : The person's first name
- **`lastName: string`** : The person's last name

There are generators for C#, Go, TinyGo, Rust, Java, Protobuf, OpenAPI, JSONSchema, Python, and more. If you work in shops with many teams and languages, you must look into Apexlang. It’s a game changer. Specify your interfaces once and generate scaffolding, boilerplate, documentation, bindings, everything from there. You can inherit from the existing Apexlang generators or create entirely new ones. It’s just TypeScript running on Deno and you can host your templates and generators anywhere.

What’s next?

I didn’t start Apexlang but I recognized the value immediately when using it as WIDL. The original author (Phil Kedy) and I have joined up as part of Candle to build tools that make everything about software easier. Once you start it’s hard to stop. We use Apexlang heavily on NanoBus, our WebAssembly-oriented developer platform.

We’re in the process of fully converting Apexlang and its dependencies from a go/node hybrid to deno and WebAssembly. The apex CLI, parsers, and code generators are now fully deno but there may be some rough edges as we iron out the wrinkles.

We hang out in our discord server and are always happy to chat about Apexlang, WebAssembly, go, rust, or anything else. Come say hi!