The Java host implementation for proxy-wasm, enabling developer to run Proxy-Wasm plugins in Java.
If your using Quarkus, see the Quarkus Proxy-Wasm Extension docs.
To build the project, you need to have Maven installed. You can build the project using the following command:
mvn clean installProxy-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 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();
}
}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.
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.
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.
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.
- TomEE Integration Test - A simple webapp run against TomEE with a Proxy-Wasm plugin.
To build the project, you need to have Maven installed. You can build the project using the following command:
mvn clean install