Skip to content

roastedroot/proxy-wasm-java-host

Repository files navigation

Proxy-Wasm Java Host

VersionJavadocs

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

Docs

If your using Quarkus, see the Quarkus Proxy-Wasm Extension docs.

Building

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

mvn clean install

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";
    }
}

Configuring the Plugin with CDI

Configuring the Proxy-Wasm plugin is easy in a CDI container like Quarkus or TomEE. You produce it with a @ApplicationScoped @Produces method, which returns a PluginFactory instance.

Below is an example that uses the PluginFactory.builder() API to create a PluginFactory:

package org.example;

import com.dylibso.chicory.wasm.Parser;
import com.dylibso.chicory.wasm.WasmModule;
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() {
        return PluginFactory.builder(module)
                        .withName("waf")
                        .withPluginConfig(" ... the config passed to the plugin ... ")
                        .withMetricsHandler(new SimpleMetricsHandler())
                        .build();
    }
}

Non-CDI Configuration

Setting up non-CDI is also possible, but more complicated. If anyone is interested helping document this, please send in a PR. Here is link to where we configure the ProxyWasmFeature for a Jersey based test case.

Compiling WASM to Bytecode

By default, WASM modules are executed using the Chicory interpreter. But if you want the WASM code 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.

Runtime Compilation

To enable runtime compilation, you need just need to add the following dependency to your pom.xml:

<dependency>
  <groupId>com.dylibso.chicory</groupId>
  <artifactId>compiler</artifactId>
</dependency>

You then enable it on the PluginFactory builder by using it as the machine factory:

@Produces
public PluginFactory waf() {
    return PluginFactory.builder(module)
                    .withMachineFactory(MachineFactoryCompiler::compile)
                    .withName("waf")
                    .withPluginConfig(CONFIG)
                    .withMetricsHandler(new SimpleMetricsHandler())
                    .build();
}

Please refer to the Chicory Runtime Compilation documentation for more details.

Build time Compilation

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.

To compile your WASM module at build time, add the Chicory compiler Maven plugin to your pom.xml:

<plugin>
    <groupId>com.dylibso.chicory</groupId>
    <artifactId>chicory-compiler-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>wasm-shim</id>
            <goals>
                <goal>compile</goal>
            </goals>
            <configuration>
                <name>org.example.internal.WasmShim</name>
                <wasm>src/main/resources/plugin.wasm</wasm>
            </configuration>
        </execution>
    </executions>
</plugin>

This will generate a WasmShim class that provides both a load() method to get the WasmModule and a create() method for the machine factory. Update your plugin factory to use the compiled module:

@Produces
public PluginFactory waf() {
    return PluginFactory.builder(WasmShim.load())
                    .withMachineFactory(WasmShim::create)
                    .withName("waf")
                    .withPluginConfig(CONFIG)
                    .withMetricsHandler(new SimpleMetricsHandler())
                    .build();
}

Please refer to the Chicory Build time Compilation documentation for more details.

JavaDocs

Examples

Docs and SDKs for plugin authors:

Popular Proxy-Wasm plugins:

Building

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

mvn clean install

About

A proxy-wasm host implementation for Java

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages