Quarkus Proxy-WASM Extension

The Java implementation for proxy-wasm, enabling developer to run Proxy-Wasm plugins in Java.

Overview

Proxy-Wasm is a plugin system for network proxies. It lets you write plugins that can act as request filters in a portable, sandboxed, and language-agnostic way, thanks to WebAssembly.

This Quarkus extension allows you to use Proxy-Wasm plugins to filter requests to Jakarta REST (formerly known as JAX-RS) endpoints.

Adding a Proxy-Wasm plugin to a JAX-RS for a "waf" proxy-wasm module is as simple as adding a @ProxyWasm annotation to a method or class:

package org.example;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import io.roastedroot.proxywasm.jaxrs.ProxyWasm;

@Path("/example")
public class Example {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @ProxyWasm("waf")
    public String hello() {
        return "hello";
    }
}

And then using the Plugin builder API to configure the Proxy-Wasm plugin that has a matching name:

package org.example;

import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.wasm.WasmModule;
import io.roastedroot.proxywasm.StartException;
import io.roastedroot.proxywasm.Plugin;
import io.roastedroot.proxywasm.PluginFactory;
import io.roastedroot.proxywasm.SimpleMetricsHandler;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.Produces;

@ApplicationScoped
public class App {

    private static WasmModule module =
        Parser.parse(App.class.getResourceAsStream("coraza-proxy-wasm.wasm"));

    @Produces
    public PluginFactory waf() throws StartException {
        return () ->
                Plugin.builder(module)
                        .withName("waf")
                        .withPluginConfig(" ... the config passed to the plugin ... ")
                        .withMetricsHandler(new SimpleMetricsHandler())
                        .build();
    }
}

Compiling WASM to Bytecode (Experimental)

By default, wsm modules are executed using the Chicory interpreter. But if you want the wasm to run a near native speed, you should compile the WASM to Java bytecode using the chicory WASM to bytecode compiler. Chicory supports compiling the WASM module at either build time or runtime. If you want to compile your Quarkus app to native, then you MUST compile the WASM module at build (time to avoid the use of runtime reflection). Please refer to the Chicory documentation for more details on how to compile the WASM module to Java bytecode. Compiling will produce a machine factory that you should pass as an argument to the withMachineFactory method to enable the bytecode execution of the WASM module.

Docs

• Usage Guide
• Proxy-Wasm JavaDocs

Docs and SDKs for plugin authors:

• ABI specification
• C++ SDK
• Rust SDK
• Go SDK
• AssemblyScript SDK

Popular Proxy-Wasm plugins:

• Coraza WAF
• Kuadrant

Building

To build the project, you need to have Maven installed. You can build the project using the following command:

mvn clean install

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Hiram Chirino 💻 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!