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:
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 WebTransport)
- TCP and Unix Domain Socket transports carry invocations one after another over a connection. QUIC, WebTransport and HTTP/2 multiplex many concurrent invocations over a single long-lived connection and are the recommended choice for sustained high call rates (see
SPEC.md).
- Wasm reactor components, that need to run in a Wasm runtime. Those can be served, for example, using
wrpc-wasmtime, which serves their exports using wRPC.
Requirements
- For Rust components and wRPC applications:
rust >= 1.97
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 component
We will use the following Rust component:
Build the 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
Serve Wasm hello server via TCP
wrpc-wasmtime tcp serve ./target/wasm32-wasip2/release/hello_component_server.wasm
Call the Wasm hello server using a native wRPC hello client via TCP:
cargo run -p hello-tcp-client
Serve native wRPC hello server via TCP:
cargo run -p hello-tcp-server [::1]:7762
Call native wRPC hello server using native wRPC hello client via TCP:
cargo run -p hello-tcp-client [::1]:7762
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.