Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nginx/unit-wasm
Development libraries for writing WebAssembly modules for NGINX Unit
https://github.com/nginx/unit-wasm
c library nginx nginx-unit rust wasm webassembly
Last synced: about 1 month ago
JSON representation
Development libraries for writing WebAssembly modules for NGINX Unit
- Host: GitHub
- URL: https://github.com/nginx/unit-wasm
- Owner: nginx
- License: apache-2.0
- Created: 2023-07-17T16:51:28.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-02T02:22:04.000Z (4 months ago)
- Last Synced: 2024-09-28T13:03:10.033Z (about 1 month ago)
- Topics: c, library, nginx, nginx-unit, rust, wasm, webassembly
- Language: C
- Homepage: https://unit.nginx.org/
- Size: 116 KB
- Stars: 38
- Watchers: 12
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# C & Rust Library & Examples for Building WebAssembly Modules for NGINX Unit
This provides a C library (lbunit-wasm) and Rust crates based on that library
to aid in the creation of WebAssembly modules in C and Rust.
It also has some demo WebAssembly modules written in C and Rust.
1. [C & Rust Library & Examples for Building WebAssembly Modules for NGINX Unit](#c---rust-library---examples-for-building-webassembly-modules-for-nginx-unit)
2. [Repository Layout](#repository-layout)
3. [Setup a Suitable Environment](#setup-a-suitable-environment)
1. [Fedora](#fedora)
2. [Debian / Ubuntu](#debian--ubuntu)
4. [Quickstart in Developing Rust WebAssembly Modules for Unit](#quickstart-in-developing-rust-webassembly-modules-for-unit)
5. [Working With the Repository](#working-with-the-repository)
6. [Using With Unit](#using-with-unit)
7. [Consuming the C Library](#consuming-the-c-library)
8. [License](#license)
## Repository Layout
**src/c** contains the main libunit-wasm library.
**src/rust** contains the rust version of the above.
**examples/c** contains some demo WebAssembly modules that show both the raw
interface to Unit (\*-raw.c) and also the use of libunit-wasm (luw-\*.c).
**examples/rust** contains rust versions of the above C demo modules and more.
**examples/docker** contains docker files for building Unit with WebAssembly
support and the C examples.
## Setup a Suitable Environment
To make full use of this repository you will require numerous tools/packages.
Exactly what you need and how to get it will depend on your Operating System.
This has been primarily developed and tested on Fedora & Ubuntu Linux.
### Fedora
On Fedora make sure you have the following installed
```
# dnf install make clang llvm compiler-rt lld wasi-libc-devel \
wasi-libc-static cargo rust rustfmt rust-std-static \
rust-std-static-wasm32-unknown-unknown \
rust-std-static-wasm32-wasi
```
One last item you will need is the libclang wasm32-wasi runtime library, this
can be done with
```
# wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/libclang_rt.builtins-wasm32-wasi-20.0.tar.gz | tar --strip-components=1 -xvzf - -C $(dirname $(clang -print-runtime-dir))
```
This will install the following, path may vary slightly
```
/usr/lib64/clang/16/lib/wasi/libclang_rt.builtins-wasm32.a
```
The above should also work (perhaps with slight alterations) on recent
CentOS/RHEL etc...
**NOTE:** If you get a major Clang version update, you may need to repeat
that last task.
### Debian / Ubuntu
Install the following as normal
```
# apt install wasi-libc make clang llvm lld
```
For the rest you will likely need to use [rustup](https://rustup.rs). Caveat
Emptor.
After you've completed the _rustup_ installation by following the on screen
instructions as yourself (defaults are fine), do the following
```shell
$ rustup target add wasm32-wasi
```
You will also need to grab the wasi-sysroot, this is essentially a C library
targeting WebAssembly (it is based partly on cloudlibc and musl libc) and
is required for building server side WebAssembly modules.
It's up to you where you put this.
```shell
$ wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/wasi-sysroot-20.0.tar.gz | tar -xzf -
```
And finally similarly as Fedora (this requires a recentish clang)
```
# wget -O- https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/libclang_rt.builtins-wasm32-wasi-20.0.tar.gz | tar --strip-components=1 -xvzf - -C $(dirname $(clang -print-runtime-dir))
```
## Quickstart in Developing Rust WebAssembly Modules for Unit
1) Setup a suitable build environment as above.
2) Create a new rust project
```shell
$ cargo init --lib my-wasm-example
```
3) Add the [unit-wasm crate](https://crates.io/crates/unit-wasm) as dependency
```shell
$ cd my-wasm-example
$ cargo add unit-wasm
```
4) Set the crate type
```shell
$ printf '\n[lib]\ncrate-type = ["cdylib"]\n' >>Cargo.toml
```
5) Create an example application
To do this you can simply take a copy of our echo-request demo in this
repository
```shell
$ wget -O src/lib.rs https://raw.githubusercontent.com/nginx/unit-wasm/main/examples/rust/echo-request/src/lib.rs
```
6) Build it!
```shell
$ cargo build --target wasm32-wasi
```
You should now have a *target/wasm32-wasi/debug/my_wasm_example.wasm* file
(yes, hyphens will be turned to underscores)
You can now use this in Unit with the following config
```JSON
{
"listeners": {
"[::1]:8888": {
"pass": "applications/my-wasm-example"
}
},
"applications": {
"my-wasm-example": {
"type": "wasm",
"module": "/path/to/my-wasm-example/target/wasm32-wasi/debug/my_wasm_example.wasm",
"request_handler": "uwr_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler",
"module_init_handler": "uwr_module_init_handler",
"module_end_handler": "uwr_module_end_handler"
}
}
}
```
and curl command
```shell
$ curl http://localhost:8888/
```
7) Start writing your own Wasm modules in Rust!
To help you get started, you can check out the Rust examples under
[examples/rust](https://github.com/nginx/unit-wasm/tree/main/examples/rust)
and also the
[API-Rust.md](https://github.com/nginx/unit-wasm/blob/main/API-Rust.md)
for an overview of the API.
## Working With the Repository
The project uses good old _make(1)_ as the build system.
Typing _make help_ will show the list of available targets and the various
make variables you can set. E.g
```
$ make help
Available Targets:
default /
libunit-wasm - Builds libunit-wasm C library
examples - Builds the above as well as C examples
examples-raw - Builds raw (non libunit-wasm) C examples
rust - Builds the libunit-wasm rust crate
examples-rust _ Builds the above and rust examples
all - Builds all the above
docker - Builds demo docker images
clean - Removes auto generated artifacts
tags - Generate ctags
Variables:
make CC= - Specify compiler to use
Defaults to clang
make WASI_SYSROOT= - Specify the path to the WASI sysroot
Defaults to autodetected
make V=1 - Enables verbose output
make D=1 - Enables debug builds (-O0)
make E=1 - Enables Werror
```
If you have previously followed the steps outlined above in
[Setup a Suitable Environment](#setup-a-suitable-environment)
You can build the libunit-wasm C library, C example Wasm modules, the Rust
crates that provides Rust bindings for the libunit-wasm and the Rust example
Wasm modules.
E.g
```shell
$ make # Build just the C library
$ make examples # Build the C library and C examples
$ make rust # Build the Rust crates
$ make examples-rust # Build the Rust examples
$ make all # Build all the above
```
The C and Rust example Wasm modules will be located at
```
examples/c/luw-echo-request.wasm
examples/c/luw-upload-reflector.wasm
examples/rust/echo-request/target/wasm32-wasi/debug/rust_echo_request.wasm
examples/rust/hello-world/target/wasm32-wasi/debug/rust_hello_world.wasm
examples/rust/upload-reflector/target/wasm32-wasi/debug/rust_upload_reflector.wasm
```
**NOTE:** To build the C library and examples you will need to specify the
wasi-sysroot.
E.g
```shell
$ make WASI_SYSROOT=/path/to/wasi-sysroot all
```
**However** if you are on Fedora and installed the _wasi-*_ packages listed
above in the [Setup a Suitable Environment](#fedora) then the wasi-sysroot
path will be autodetected and set by the Makefile. You can override the
autodetection by explicitly specifying it as above.
## Using With Unit
If you have all the above built, you are now ready to test it out with Unit.
We won't go into the details of building Unit from source and enabling the Unit
WebAssembly language module here (see the
[HOWTO.md](https://github.com/nginx/unit-wasm/blob/main/HOWTO.md) in the
repository root for more details) but will instead assume you already have a
Unit with the WebAssembly language module already running, perhaps installed
via a package.
Create the following Unit config (editing the module paths as appropriate)
```JSON
{
"listeners": {
"[::1]:8888": {
"pass": "routes"
}
},
"settings": {
"http": {
"max_body_size": 8589934592
}
},
"routes": [
{
"match": {
"uri": "/echo*"
},
"action": {
"pass": "applications/luw-echo-request"
}
},
{
"match": {
"uri": "/upload*"
},
"action": {
"pass": "applications/luw-upload-reflector"
}
},
{
"match": {
"uri": "/large-upload*"
},
"action": {
"pass": "applications/large-upload"
}
},
{
"match": {
"uri": "/rust-echo*"
},
"action": {
"pass": "applications/rust-echo-request"
}
},
{
"match": {
"uri": "/rust-upload*"
},
"action": {
"pass": "applications/rust-upload-reflector"
}
},
{
"match": {
"uri": "/rust-large-upload*"
},
"action": {
"pass": "applications/rust-large-upload"
}
},
{
"match": {
"uri": "/rust-hello-world*"
},
"action": {
"pass": "applications/rust-hello-world"
}
}
],
"applications": {
"luw-echo-request": {
"type": "wasm",
"module": "/path/to/unit-wasm/examples/c/luw-echo-request.wasm",
"request_handler": "luw_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler",
"module_init_handler": "luw_module_init_handler",
"module_end_handler": "luw_module_end_handler"
},
"luw-upload-reflector": {
"type": "wasm",
"module": "/path/to/unit-wasm/examples/c/luw-upload-reflector.wasm",
"request_handler": "luw_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler",
"request_end_handler": "luw_request_end_handler",
"response_end_handler": "luw_response_end_handler"
},
"large-upload": {
"type": "wasm",
"module": "/path/to/unit-wasm/examples/c/large-upload.wasm",
"request_handler": "luw_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler",
"module_init_handler": "luw_module_init_handler",
"module_end_handler": "luw_module_end_handler",
"response_end_handler": "luw_response_end_handler",
"access": {
"filesystem": [
"/var/tmp"
]
}
},
"rust-echo-request": {
"type": "wasm",
"module": "/path/to/unit-wasm/examples/rust/echo-request/target/wasm32-wasi/debug/rust_echo_request.wasm",
"request_handler": "uwr_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler",
"module_init_handler": "uwr_module_init_handler",
"module_end_handler": "uwr_module_end_handler"
},
"rust-upload-reflector": {
"type": "wasm",
"module": "/path/to/unit-wasm/examples/rust/upload-reflector/rust_upload_reflector.wasm",
"request_handler": "uwr_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler",
"request_end_handler": "uwr_request_end_handler",
"response_end_handler": "uwr_response_end_handler"
},
"rust-large-upload": {
"type": "wasm",
"module": "/path/to/src/unit-wasm/examples/rust/large-upload/target/wasm32-wasi/debug/rust_large_upload.wasm",
"request_handler": "uwr_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler",
"module_init_handler": "uwr_module_init_handler",
"module_end_handler": "uwr_module_end_handler",
"response_end_handler": "uwr_response_end_handler",
"access": {
"filesystem": [
"/var/tmp"
]
}
},
"rust-hello-world": {
"type": "wasm",
"module": "/path/to/unit-wasm/examples/rust/hello-world/target/wasm32-wasi/debug/rust_hello_world.wasm",
"request_handler": "uwr_request_handler",
"malloc_handler": "luw_malloc_handler",
"free_handler": "luw_free_handler"
}
}
}
```
Load this config then you should be ready to try it.
```
$ curl -X POST -d "Hello World" --cookie "mycookie=hmmm" http://localhost:8888/echo/?q=a
*** Welcome to WebAssembly on Unit! [libunit-wasm (0.1.0/0x00010000)] ***
[Request Info]
REQUEST_PATH = /echo/?q=a
METHOD = POST
VERSION = HTTP/1.1
QUERY = q=a
REMOTE = ::1
LOCAL_ADDR = ::1
LOCAL_PORT = 8080
SERVER_NAME = localhost
[Request Headers]
Host = localhost:8080
User-Agent = curl/8.0.1
Accept = */*
Cookie = mycookie=hmmm
Content-Length = 11
Content-Type = application/x-www-form-urlencoded
[POST data]
Hello World
```
```
$ curl -v -X POST --data-binary @audio.flac -H "Content-Type: audio/flac" http://localhost:8888/upload-reflector/ -o wasm-test.dat
...
> Content-Type: audio/flac
> Content-Length: 60406273
...
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 115M 100 57.6M 100 57.6M 47.6M 47.6M 0:00:01 0:00:01 --:--:-- 95.2M
...
< Content-Type: audio/flac
< Content-Length: 60406273
...
$ sha1sum audio.flac wasm-test.dat
ef5c9c228544b237022584a8ac4612005cd6263e audio.flac
ef5c9c228544b237022584a8ac4612005cd6263e wasm-test.dat
```
## Consuming the C Library
If **unit/unit-wasm.h** and **libunit.a** are installed into standard
include/library directories then
Include the libunit-wasm header file
```C
....
#include
...
```
Link against libunit-wasm
```shell
$ clang ... -o myapp.wasm myapp.c -lunit-wasm
```
See [API-C.md](https://github.com/nginx/unit-wasm/blob/main/API-C.md) for an
overview of the API.
## License
This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).