Skip to content

Commit a0d0db9

Browse files
chirinochirino
committed
Provide some usage docs in the README.
Signed-off-by: Hiram Chirino <hiram@hiramchirino.com>
1 parent e446a20 commit a0d0db9

File tree

1 file changed

+184
-4
lines changed

1 file changed

+184
-4
lines changed

‎README.md‎

Lines changed: 184 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
# Proxy-Wasm Java Host
22

3-
[![Version](https://img.shields.io/maven-central/v/io.roastedroot/proxy-wasm-jaxrs?logo=apache-maven&style=flat-square)](https://central.sonatype.com/artifact/io.roastedroot/proxy-wasm-java-host-parent)
3+
[![Version](https://img.shields.io/maven-central/v/io.roastedroot/proxy-wasm-jaxrs?logo=apache-maven&style=flat-square)](https://central.sonatype.com/artifact/io.roastedroot/proxy-wasm-java-host-parent)[![Javadocs](http://javadoc.io/badge/io.roastedroot/proxy-wasm-jaxrs.svg)](http://javadoc.io/doc/io.roastedroot/proxy-wasm-jaxrs)
44

5-
The Java host implementation for Proxy-Wasm, enabling developers to run Proxy-Wasm plugins in JAX-RS.
5+
The Java host implementation for proxy-wasm, enabling developer to run Proxy-Wasm plugins in Java.
66

77
## Docs
88

9-
TODO: still need to document how to use in non-cdi containers.
10-
119
If your using Quarkus, see the [Quarkus Proxy-Wasm Extension](https://docs.quarkiverse.io/quarkus-proxy-wasm/dev/index.html) docs.
1210

1311
## Building
@@ -17,3 +15,185 @@ To build the project, you need to have Maven installed. You can build the projec
1715
```bash
1816
mvn clean install
1917
```
18+
19+
## Overview
20+
21+
Proxy-Wasm is a plugin system for network proxies. It lets you write plugins that can act as request filters in a
22+
portable, sandboxed, and language-agnostic way, thanks to WebAssembly.
23+
24+
This Quarkus extension allows you to use Proxy-Wasm plugins to filter requests to Jakarta REST (formerly known as JAX-RS)
25+
endpoints.
26+
27+
Adding a Proxy-Wasm plugin to a JAX-RS for a "waf" proxy-wasm module is as simple as adding a `@ProxyWasm` annotation
28+
to a method or class:
29+
30+
```java
31+
package org.example;
32+
33+
import jakarta.ws.rs.GET;
34+
import jakarta.ws.rs.Path;
35+
import jakarta.ws.rs.Produces;
36+
import jakarta.ws.rs.core.MediaType;
37+
import io.roastedroot.proxywasm.jaxrs.ProxyWasm;
38+
39+
@Path("/example")
40+
public class Example {
41+
42+
@GET
43+
@Produces(MediaType.TEXT_PLAIN)
44+
@ProxyWasm("waf")
45+
public String hello() {
46+
return "hello";
47+
}
48+
}
49+
```
50+
51+
### Configuring the Plugin with CDI
52+
53+
Configuring the Proxy-Wasm plugin is easy in a CDI container like Quarkus or TomEE. You produce it with
54+
a `@ApplicationScoped` `@Produces` method, which returns a `PluginFactory` instance.
55+
56+
Below is an example that uses the [`PluginFactory.builder()`](https://javadoc.io/doc/io.roastedroot/proxy-wasm-java-host/latest/io/roastedroot/proxywasm/PluginFactory.Builder.html) API to create a `PluginFactory`:
57+
58+
```java
59+
package org.example;
60+
61+
import com.dylibso.chicory.wasm.Parser;
62+
import com.dylibso.chicory.wasm.WasmModule;
63+
import io.roastedroot.proxywasm.PluginFactory;
64+
import io.roastedroot.proxywasm.SimpleMetricsHandler;
65+
import jakarta.enterprise.context.ApplicationScoped;
66+
import jakarta.enterprise.inject.Produces;
67+
68+
@ApplicationScoped
69+
public class App {
70+
71+
private static WasmModule module =
72+
Parser.parse(App.class.getResourceAsStream("coraza-proxy-wasm.wasm"));
73+
74+
@Produces
75+
public PluginFactory waf() {
76+
return PluginFactory.builder(module)
77+
.withName("waf")
78+
.withPluginConfig(" ... the config passed to the plugin ... ")
79+
.withMetricsHandler(new SimpleMetricsHandler())
80+
.build();
81+
}
82+
}
83+
```
84+
85+
### Non-CDI Configuration
86+
87+
Setting up non-CDI is also possible, but more complicated. If anyone is interested helping document this, please
88+
send in a PR. Here is link to where we [configure the ProxyWasmFeature](https://github.com/roastedroot/proxy-wasm-java-host/blob/main/proxy-wasm-jaxrs/src/test/java/io/roastedroot/proxywasm/jaxrs/example/tests/BaseTest.java#L34)
89+
for a Jersey based test case.
90+
91+
### Compiling WASM to Bytecode
92+
93+
By default, WASM modules are executed using the [Chicory](https://chicory.dev/) interpreter. But if you want the WASM code to
94+
run a near native speed, you should compile the WASM to Java bytecode using the chicory WASM to bytecode compiler.
95+
Chicory supports compiling the WASM module at either build time or runtime.
96+
97+
#### Runtime Compilation
98+
99+
To enable runtime compilation, you need just need to add the following dependency to your `pom.xml`:
100+
101+
```xml
102+
<dependency>
103+
<groupId>com.dylibso.chicory</groupId>
104+
<artifactId>compiler</artifactId>
105+
</dependency>
106+
```
107+
108+
You then enable it on the PluginFactory builder by using it as the machine factory:
109+
110+
```java
111+
@Produces
112+
public PluginFactory waf() {
113+
return PluginFactory.builder(module)
114+
.withMachineFactory(MachineFactoryCompiler::compile)
115+
.withName("waf")
116+
.withPluginConfig(CONFIG)
117+
.withMetricsHandler(new SimpleMetricsHandler())
118+
.build();
119+
}
120+
```
121+
122+
Please refer to the [Chicory Runtime Compilation documentation](https://chicory.dev/docs/usage/runtime-compiler)
123+
for more details.
124+
125+
#### Build time Compilation
126+
127+
If you want to compile your Quarkus app to native, then you MUST compile the WASM module at build time to avoid the use
128+
of runtime reflection.
129+
130+
To compile your WASM module at build time, add the Chicory compiler Maven plugin to your `pom.xml`:
131+
132+
```xml
133+
<plugin>
134+
<groupId>com.dylibso.chicory</groupId>
135+
<artifactId>chicory-compiler-maven-plugin</artifactId>
136+
<executions>
137+
<execution>
138+
<id>wasm-shim</id>
139+
<goals>
140+
<goal>compile</goal>
141+
</goals>
142+
<configuration>
143+
<name>org.example.internal.WasmShim</name>
144+
<wasm>src/main/resources/plugin.wasm</wasm>
145+
</configuration>
146+
</execution>
147+
</executions>
148+
</plugin>
149+
```
150+
151+
This will generate a `WasmShim` class that provides both a `load()` method to get the `WasmModule` and a `create()`
152+
method for the machine factory. Update your plugin factory to use the compiled module:
153+
154+
```java
155+
@Produces
156+
public PluginFactory waf() {
157+
return PluginFactory.builder(WasmShim.load())
158+
.withMachineFactory(WasmShim::create)
159+
.withName("waf")
160+
.withPluginConfig(CONFIG)
161+
.withMetricsHandler(new SimpleMetricsHandler())
162+
.build();
163+
}
164+
```
165+
166+
Please refer to the [Chicory Build time Compilation documentation](https://chicory.dev/docs/usage/build-time-compiler)
167+
for more details.
168+
169+
## JavaDocs
170+
171+
* [Proxy-Wasm JavaDocs](http://javadoc.io/doc/io.roastedroot/proxy-wasm-jaxrs)
172+
173+
## Examples
174+
175+
* [TomEE Integration Test](integration-tests/tomee) - A simple webapp run against TomEE with a Proxy-Wasm plugin.
176+
177+
### Docs and SDKs for plugin authors:
178+
179+
* [ABI specification](https://github.com/istio-ecosystem/wasm-extensions[Proxy-Wasm)
180+
* [C++ SDK](https://github.com/proxy-wasm/proxy-wasm-cpp-sdk[Proxy-Wasm)
181+
* [Rust SDK](https://github.com/proxy-wasm/proxy-wasm-rust-sdk[Proxy-Wasm)
182+
* [Go SDK](https://github.com/proxy-wasm/proxy-wasm-go-sdk[Proxy-Wasm)
183+
* [AssemblyScript SDK](https://github.com/solo-io/proxy-runtime[Proxy-Wasm)
184+
185+
### Popular Proxy-Wasm plugins:
186+
187+
* [Coraza WAF](https://github.com/corazawaf/coraza-proxy-wasm)
188+
* [Kuadrant](https://github.com/Kuadrant/wasm-shim/)
189+
* [Higress](https://higress.cn/en/plugin/)
190+
191+
192+
## Building
193+
194+
To build the project, you need to have Maven installed. You can build the project using the following command:
195+
196+
```bash
197+
mvn clean install
198+
```
199+

0 commit comments

Comments
 (0)