Skip to content

Latest commit

 

History

History
258 lines (174 loc) · 8.45 KB

README.md

File metadata and controls

258 lines (174 loc) · 8.45 KB
Raw

wRPC

Component-native transport-agnostic RPC protocol and framework based on WebAssembly Interface Types (WIT)

A Bytecode Alliance hosted project

build status Documentation Status

About

wRPC facilitates execution of arbitrary functionality defined in WIT over network or other means of communication.

Main use cases for wRPC are:

  • out-of-tree WebAssembly runtime plugins
  • distributed WebAssembly component communication

Even though wRPC is designed for Wasm components first and foremost, it is fully usable outside of WebAssembly context and can serve as a general-purpose RPC framework.

wRPC uses component model value definiton encoding on the wire.

wRPC supports both dynamic (based on e.g. runtime WebAssembly component type introspection) and static use cases.

For static use cases, wRPC provides WIT binding generators for:

  • Rust
  • Go

wRPC fully supports the unreleased native WIT stream and future data types along with all currently released WIT functionality.

See specification for more info.

Installation

  • Using cargo:

    cargo install wrpc

  • Using nix:

    nix profile install github:bytecodealliance/wrpc

    or, without installing:

    nix shell github:bytecodealliance/wrpc

  • You can also download individual binaries from the release page

Quickstart

wRPC usage examples for different programming languages can be found at examples.

There are 2 different kinds of examples:

  • Native wRPC applications, tied to a particular wRPC transport (like Unix Domain Sockets, TCP, QUIC or NATS.io)
  • Generic Wasm components, that need to run in a Wasm runtime. Those can be executed, for example, using wrpc-wasmtime, to polyfill imports at runtime and serve exports using wRPC.

Requirements

  • For Rust components and wRPC applications: rust >= 1.82

  • For NATS.io transport: nats-server >= 2.10.20 or docker >= 24.0.6 (or any other OCI runtime)

Nix users can run nix develop anywhere in the repository to get all dependencies correctly set up

hello example

In this example we will serve and invoke a simple hello application.

Rust components

We will use the following two Rust components:

We will have to build these components first:

  • Build Wasm hello client:

    cargo build --release -p hello-component-client --target wasm32-wasip2

    Output is in target/wasm32-wasip2/release/hello-component-client.wasm

  • Build Wasm hello server:

    cargo build --release -p hello-component-server --target wasm32-wasip2

    Output is in target/wasm32-wasip2/release/hello_component_server.wasm

    NB: Rust uses _ separators in the filename, because a component is built as a reactor-style library

Using TCP transport

We will use the following two Rust wRPC applications using TCP transport:

[::1]:7761 is used as the default address

  1. Serve Wasm hello server via TCP

    wrpc-wasmtime tcp serve ./target/wasm32-wasip2/release/hello_component_server.wasm
    • Sample output:

    INFO wrpc_wasmtime_cli: serving instance function name="hello"

  2. Call Wasm hello server using a Wasm hello client via TCP:

    wrpc-wasmtime tcp run ./target/wasm32-wasip2/release/hello-component-client.wasm
    • Sample output in the client:

    hello from Rust

    • Sample output in the server:

    INFO wrpc_wasmtime_cli: serving instance function invocation

    INFO wrpc_wasmtime_cli: successfully served instance function invocation

  3. Call the Wasm hello server using a native wRPC hello client via TCP:

    cargo run -p hello-tcp-client

  4. Serve native wRPC hello server via TCP:

    cargo run -p hello-tcp-server [::1]:7762

  5. Call native wRPC hello server using native wRPC hello client via TCP:

    cargo run -p hello-tcp-client [::1]:7762

  6. Call native wRPC hello server using Wasm hello client via TCP:

    wrpc-wasmtime tcp run --import [::1]:7762 ./target/wasm32-wasip2/release/hello-component-client.wasm

Using NATS.io transport

We will use the following two Rust wRPC applications using NATS.io transport:

  1. Run NATS.io (more thorough documentation available here):

    • using standalone binary:
    nats-server
    docker run --rm -it --name nats-server -p 4222:4222 nats:2.10.20-alpine3.20

  2. Serve Wasm hello server via NATS.io

    wrpc-wasmtime nats serve --export rust ./target/wasm32-wasip2/release/hello_component_server.wasm
    • Sample output:

    INFO async_nats: event: connected

    INFO wrpc_wasmtime_cli: serving instance function name="hello"

  3. Call Wasm hello server using a Wasm hello client via NATS.io:

    wrpc-wasmtime nats run --import rust ./target/wasm32-wasip2/release/hello-component-client.wasm
    • Sample output in the client:

    INFO async_nats: event: connected

    hello from Rust

    • Sample output in the server:

    INFO wrpc_wasmtime_cli: serving instance function invocation

    INFO wrpc_wasmtime_cli: successfully served instance function invocation

  4. Call the Wasm hello server using a native wRPC hello client via NATS.io:

    cargo run -p hello-nats-client rust

  5. Serve native wRPC hello server via NATS.io:

    cargo run -p hello-nats-server native

  6. Call both the native wRPC hello server and Wasm hello server using native wRPC hello client via NATS.io:

    cargo run -p hello-nats-client rust native

  7. Call native wRPC hello server using Wasm hello client via NATS.io:

    wrpc-wasmtime nats run --import native ./target/wasm32-wasip2/release/hello-component-client.wasm

Repository structure

This repository contains (for all supported languages):

  • core libraries and abstractions
  • binding generators
  • WebAssembly runtime integrations
  • wRPC transport implementations

wit-bindgen-wrpc aims to closely match UX of wit-bindgen and therefore includes a subtree merge of the project, which is occasionally merged into this tree.

  • wRPC binding generators among other tests, are tested using the wit-bindgen test suite
  • wit-bindgen documentation is reused where applicable

Contributing

👋 Welcome, new contributors!

Whether you're a seasoned developer or just getting started, your contributions are valuable to us. Don't hesitate to jump in, explore the project, and make an impact. To start contributing, please check out our Contribution Guidelines.