http-wasm Guest Library

This library provides a Rust implementation for the Wasm Guest ABI and interfaces with http-wasm.

It is designed for writing Traefik plugins in Rust, and works with any http-wasm compatible runtime.

Design Goals

Not opinionated, the focus is to provide a very thin wrapper around the host functions.
Minimal dependency footprint: only the log crate is used at runtime (can be deactivated)
Low-level Byte abstraction to enable all use-cases.
Memory-efficient data handling suitable for constrained Wasm environments.

Caveat

To avoid heap allocations on hot paths (logging, reading from the host), buffers are preallocated and reused. For reading large payloads, an overflow path is implemented that allocates the needed buffer on the heap. The maximum size of these buffers is 16MB, values larger are truncated. Log messages are formatted into a fixed-size 2048-byte static buffer; messages exceeding this limit will be truncated.

Credits

Initial reference code from http-wasm-rust
API inspired by http-wasm-guest-tinygo

Usage

Add the dependency to your project:

cargo add http-wasm-guest

Implement the Guest trait and register the plugin. See the examples for complete code.

use http_wasm_guest::{
    Guest,
    host::{Request, Response},
    register,
};
struct Plugin {}

impl Guest for Plugin {
    fn handle_request(&self, request: &Request, _response: &Response) -> (bool, i32) {
        request.header.add(b"X-Custom-Header", b"FooBar");
        (true, 0)
    }
}

fn main() {
    let plugin = Plugin {};
    register(plugin);
}

Test

Prerequisites

To run the examples using the run.sh script, you will need the following tools and resources installed on your system:

Podman: Used for running rootless containers and pods (a drop-in replacement for Docker).
Buildah: Used for building container images.
Rust toolchain: With the wasm32-wasip1 target installed.
Network access: To pull the traefik:v3.6 and traefik/whoami container images if not already present locally.
Sufficient permissions: To run containerized workloads (may require appropriate user group membership).

You can install Podman and Buildah using your system's package manager. For example, on Ubuntu:

sudo apt update
sudo apt install podman buildah

Make sure you have the WASM target for Rust:

rustup target add wasm32-wasip1

Running the Example

You can run the examples via the provided run.sh script. This creates a running container for the traefik-server with the plugin configured and the whois-service wired into the router.

$ ./run.sh header
[lots of logging output]

Interpreting Example Output

After running the example, you can test the plugin by sending a request to the local server:

$ curl  http://whoami.localhost:8080
Hostname: pensive_curran
IP: 127.0.0.1
IP: ::1
RemoteAddr: [::1]:53364
GET / HTTP/1.1
Host: whoami.localhost:8080
User-Agent: curl/8.18.0
Accept: */*
Accept-Encoding: gzip
X-Custom-Header: FooBar
[more output]

Look for the presence of the X-Custom-Header: FooBar line in the output. This indicates that your plugin is running and modifying the request as expected. You can modify and re-run the examples to experiment with different plugin behaviors.

Troubleshooting

Common Issues When Building for WASM

Missing WASM Target:
If you see errors about unknown target or missing standard library, make sure you have added the WASM target:
```
rustup target add wasm32-wasip1
```
Build Fails with Linking Errors:
Ensure you are using the correct target triple (wasm32-wasip1) and not wasm32-unknown-unknown or others.
Plugin Not Loaded or No Effect:
- Double-check that your .wasm file is being mounted and referenced correctly in your server/proxy configuration.
- Review logs for errors about plugin loading or execution.
Crate Features or Dependency Issues:
Some crates do not support WASM targets. Keep dependencies minimal and check for WASM compatibility.
Debugging WASM Plugins:
Use logging (log crate) to emit messages from your plugin. Ensure the host runtime is configured to display or capture logs.

http-wasm-guest 0.11.3