Skip to content

Commit 63e004e

Browse files
chirinochirino
authored
Merge pull request #17 from chirino/dev
Bump proxy-wasm versions.
2 parents 74e48fc + 61f5b13 commit 63e004e

File tree

10 files changed

+256
-77
lines changed

10 files changed

+256
-77
lines changed

‎README.md‎

Lines changed: 88 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@
44
<!-- ALL-CONTRIBUTORS-BADGE:END -->
55

66
[![Version](https://img.shields.io/maven-central/v/io.quarkiverse.proxy-wasm/quarkus-proxy-wasm?logo=apache-maven&style=flat-square)](https://central.sonatype.com/artifact/io.quarkiverse.proxy-wasm/quarkus-proxy-wasm-parent)
7+
[![Javadocs](http://javadoc.io/badge/io.quarkiverse.proxy-wasm/quarkus-proxy-wasm.svg)](http://javadoc.io/doc/io.quarkiverse.proxy-wasm/quarkus-proxy-wasm)
78

8-
The Java implementation for proxy-wasm, enabling developer to run Proxy-Wasm plugins in Java.
9+
The Quarkus implementation for proxy-wasm, enabling developer to run Proxy-Wasm plugins in Java.
910

1011
## Overview
1112

@@ -39,15 +40,13 @@ public class Example {
3940
}
4041
```
4142

42-
And then using the [`Plugin builder`](https://javadoc.io/doc/io.roastedroot/proxy-wasm-java-host/latest/io/roastedroot/proxywasm/Plugin.Builder.html) API to configure the Proxy-Wasm plugin that has a matching name:
43+
And then using the [`PluginFactory builder`](https://javadoc.io/doc/io.roastedroot/proxy-wasm-java-host/latest/io/roastedroot/proxywasm/PluginFactory.Builder.html) API to configure the Proxy-Wasm plugin that has a matching name:
4344

4445
```java
4546
package org.example;
4647

4748
import com.dylibso.chicory.wasm.Parser;
4849
import com.dylibso.chicory.wasm.WasmModule;
49-
import io.roastedroot.proxywasm.StartException;
50-
import io.roastedroot.proxywasm.Plugin;
5150
import io.roastedroot.proxywasm.PluginFactory;
5251
import io.roastedroot.proxywasm.SimpleMetricsHandler;
5352
import jakarta.enterprise.context.ApplicationScoped;
@@ -60,9 +59,8 @@ public class App {
6059
Parser.parse(App.class.getResourceAsStream("coraza-proxy-wasm.wasm"));
6160

6261
@Produces
63-
public PluginFactory waf() throws StartException {
64-
return () ->
65-
Plugin.builder(module)
62+
public PluginFactory waf() {
63+
return PluginFactory.builder(module)
6664
.withName("waf")
6765
.withPluginConfig(" ... the config passed to the plugin ... ")
6866
.withMetricsHandler(new SimpleMetricsHandler())
@@ -71,21 +69,94 @@ public class App {
7169
}
7270
```
7371

74-
### Compiling WASM to Bytecode (Experimental)
72+
### Compiling WASM to Bytecode
7573

76-
By default, wsm modules are executed using the [Chicory](https://chicory.dev/) interpreter. But if you want the wasm to
74+
By default, WASM modules are executed using the [Chicory](https://chicory.dev/) interpreter. But if you want the WASM code to
7775
run a near native speed, you should compile the WASM to Java bytecode using the chicory WASM to bytecode compiler.
78-
Chicory supports compiling the WASM module at either build time or runtime. If you want to compile your Quarkus app to
79-
native, then you MUST compile the WASM module at build (time to avoid the use of runtime reflection). Please refer
80-
to the [Chicory documentation](https://chicory.dev/docs/) for more details on how to compile the WASM module to Java
81-
bytecode. Compiling will produce a machine factory that you should pass as an argument to the [withMachineFactory](https://javadoc.io/doc/io.roastedroot/proxy-wasm-java-host/latest/io/roastedroot/proxywasm/Plugin.Builder.html#withMachineFactory(java.util.function.Function))
82-
method to enable the bytecode execution of the WASM module.
76+
Chicory supports compiling the WASM module at either build time or runtime.
77+
78+
#### Runtime Compilation
79+
80+
To enable runtime compilation, you need just need to add the following dependency to your `pom.xml`:
81+
82+
```xml
83+
<dependency>
84+
<groupId>com.dylibso.chicory</groupId>
85+
<artifactId>compiler</artifactId>
86+
</dependency>
87+
```
88+
89+
You then enable it on the PluginFactory builder by using it as the machine factory:
90+
91+
```java
92+
@Produces
93+
public PluginFactory waf() {
94+
return PluginFactory.builder(module)
95+
.withMachineFactory(MachineFactoryCompiler::compile)
96+
.withName("waf")
97+
.withPluginConfig(CONFIG)
98+
.withMetricsHandler(new SimpleMetricsHandler())
99+
.build();
100+
}
101+
```
102+
103+
Please refer to the [Chicory Runtime Compilation documentation](https://chicory.dev/docs/usage/runtime-compiler)
104+
for more details.
105+
106+
#### Build time Compilation
107+
108+
If you want to compile your Quarkus app to native, then you MUST compile the WASM module at build time to avoid the use
109+
of runtime reflection.
110+
111+
To compile your WASM module at build time, add the Chicory compiler Maven plugin to your `pom.xml`:
112+
113+
```xml
114+
<plugin>
115+
<groupId>com.dylibso.chicory</groupId>
116+
<artifactId>chicory-compiler-maven-plugin</artifactId>
117+
<executions>
118+
<execution>
119+
<id>wasm-shim</id>
120+
<goals>
121+
<goal>compile</goal>
122+
</goals>
123+
<configuration>
124+
<name>org.example.internal.WasmShim</name>
125+
<wasm>src/main/resources/plugin.wasm</wasm>
126+
</configuration>
127+
</execution>
128+
</executions>
129+
</plugin>
130+
```
131+
132+
This will generate a `WasmShim` class that provides both a `load()` method to get the `WasmModule` and a `create()`
133+
method for the machine factory. Update your plugin factory to use the compiled module:
134+
135+
```java
136+
@Produces
137+
public PluginFactory waf() {
138+
return PluginFactory.builder(WasmShim.load())
139+
.withMachineFactory(WasmShim::create)
140+
.withName("waf")
141+
.withPluginConfig(CONFIG)
142+
.withMetricsHandler(new SimpleMetricsHandler())
143+
.build();
144+
}
145+
```
146+
147+
Please refer to the [Chicory Build time Compilation documentation](https://chicory.dev/docs/usage/build-time-compiler)
148+
for more details.
83149

84150
## Docs
85151

86152
* [Usage Guide](./docs/modules/ROOT/pages/index.adoc)
87153
* [Proxy-Wasm JavaDocs](https://javadoc.io/doc/io.roastedroot/proxy-wasm-java-host/latest/io/roastedroot/proxywasm/package-summary.html)
88154

155+
## Examples
156+
157+
* [Coraza Example](integration-tests/corazawaf-example) - Quarkus app that uses the Coraza WAF Proxy-Wasm plugin to filter requests.
158+
* [Kuadrant Example](integration-tests/kuadrant-example) - Quarkus app that uses the Kuadrant Proxy-Wasm plugin to filter requests.
159+
89160
### Docs and SDKs for plugin authors:
90161

91162
* [ABI specification](https://github.com/istio-ecosystem/wasm-extensions[Proxy-Wasm)
@@ -96,9 +167,9 @@ method to enable the bytecode execution of the WASM module.
96167

97168
### Popular Proxy-Wasm plugins:
98169

99-
* [Coraza WAF](link:https://github.com/corazawaf/coraza-proxy-wasm)
100-
* [Kuadrant](link:https://github.com/Kuadrant/wasm-shim/)
101-
170+
* [Coraza WAF](https://github.com/corazawaf/coraza-proxy-wasm)
171+
* [Kuadrant](https://github.com/Kuadrant/wasm-shim/)
172+
* [Higress](https://higress.cn/en/plugin/)
102173

103174
## Building
104175

‎deployment/src/main/java/io/quarkiverse/proxywasm/deployment/ProxyWasmProcessor.java‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,41 @@
1313
import io.roastedroot.proxywasm.jaxrs.ProxyWasm;
1414
import io.roastedroot.proxywasm.jaxrs.cdi.ProxyWasmFeature;
1515

16-
class ProxyWasmProcessor {
16+
/**
17+
* Quarkus build-time processor for the Proxy-Wasm extension.
18+
* This processor configures the necessary components for the Proxy-Wasm integration
19+
* including CDI beans, JAX-RS annotations, and feature registration.
20+
*/
21+
public class ProxyWasmProcessor {
1722

1823
private static final String FEATURE = "proxy-wasm";
1924

25+
/**
26+
* Registers the proxy-wasm feature with Quarkus.
27+
*
28+
* @return A FeatureBuildItem representing the proxy-wasm feature.
29+
*/
2030
@BuildStep
2131
FeatureBuildItem feature() {
2232
return new FeatureBuildItem(FEATURE);
2333
}
2434

35+
/**
36+
* Registers additional CDI beans required for Proxy-Wasm functionality.
37+
*
38+
* @return An AdditionalBeanBuildItem containing the required beans.
39+
*/
2540
@BuildStep
2641
AdditionalBeanBuildItem resources() {
2742
return new AdditionalBeanBuildItem(
2843
ProxyWasmFeature.class, VertxServerAdaptor.class, VertxHttpRequestAdaptor.class);
2944
}
3045

46+
/**
47+
* Registers the ProxyWasm annotation as a JAX-RS resource method annotation.
48+
*
49+
* @return An AdditionalJaxRsResourceMethodAnnotationsBuildItem containing the ProxyWasm annotation.
50+
*/
3151
@BuildStep
3252
public AdditionalJaxRsResourceMethodAnnotationsBuildItem annotations() {
3353
return new AdditionalJaxRsResourceMethodAnnotationsBuildItem(

‎docs/modules/ROOT/pages/index.adoc‎

Lines changed: 79 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Popular Proxy-Wasm plugins:
2222

2323
* link:https://github.com/corazawaf/coraza-proxy-wasm[Coraza WAF]
2424
* link:https://github.com/Kuadrant/wasm-shim/[Kuadrant]
25+
* link:https://higress.cn/en/plugin/[Higress]
2526
2627
Reference Docs for Java Developers:
2728

@@ -104,7 +105,6 @@ package org.example;
104105
import com.dylibso.chicory.wasm.Parser;
105106
import com.dylibso.chicory.wasm.WasmModule;
106107
import io.roastedroot.proxywasm.StartException;
107-
import io.roastedroot.proxywasm.Plugin;
108108
import io.roastedroot.proxywasm.PluginFactory;
109109
import io.roastedroot.proxywasm.SimpleMetricsHandler;
110110
import jakarta.enterprise.context.ApplicationScoped;
@@ -132,9 +132,8 @@ public class App {
132132
133133
// creates a plugin factory that loads the wasm module and configuration
134134
@Produces
135-
public PluginFactory waf() throws StartException {
136-
return () ->
137-
Plugin.builder(module)
135+
public PluginFactory waf() {
136+
return PluginFactory.builder(module)
138137
.withName("waf") <2>
139138
.withPluginConfig(CONFIG)
140139
.withMetricsHandler(new SimpleMetricsHandler()) <3>
@@ -175,12 +174,80 @@ public class App {
175174
}
176175
----
177176

178-
=== Compiling WASM to Bytecode (Experimental)
177+
=== Compiling WASM to Bytecode
179178

180-
By default, WASM modules are executed using the link:https://chicory.dev/[Chicory] interpreter. But if you want the WASM to
181-
run a near native speed, you should compile the WASM to Java bytecode using the chicory WASM to bytecode compiler.
182-
Chicory supports compiling the WASM module at either build time or runtime. If you want to compile your Quarkus app to
183-
native, then you MUST compile the WASM module at build (time to avoid the use of runtime reflection). Please refer
184-
to the link:https://chicory.dev/docs/[Chicory documentation] for more details on how to compile the WASM module to Java
185-
bytecode. Compiling will produce a machine factory that you should pass as an argument to the link:https://javadoc.io/doc/io.roastedroot/proxy-wasm-java-host/latest/io/roastedroot/proxywasm/Plugin.Builder.html#withMachineFactory(java.util.function.Function)[withMachineFactory]
186-
method to enable the bytecode execution of the WASM module.
179+
By default, WASM modules are executed using the https://chicory.dev/[Chicory] interpreter.
180+
But if you want the WASM code to run at near native speed, you should compile the WASM to Java bytecode using the Chicory WASM to bytecode compiler.
181+
Chicory supports compiling the WASM module at either build time or runtime.
182+
183+
==== Runtime Compilation
184+
185+
To enable runtime compilation, you just need to add the following dependency to your `pom.xml`:
186+
187+
[source,xml]
188+
----
189+
<dependency>
190+
<groupId>com.dylibso.chicory</groupId>
191+
<artifactId>compiler</artifactId>
192+
</dependency>
193+
----
194+
195+
You then enable it on the PluginFactory builder by using it as the machine factory:
196+
197+
[source,java]
198+
----
199+
@Produces
200+
public PluginFactory waf() {
201+
return PluginFactory.builder(module)
202+
.withMachineFactory(MachineFactoryCompiler::compile)
203+
.withName("waf")
204+
.withPluginConfig(CONFIG)
205+
.withMetricsHandler(new SimpleMetricsHandler())
206+
.build();
207+
}
208+
----
209+
210+
Please refer to the https://chicory.dev/docs/usage/runtime-compiler[Chicory Runtime Compilation documentation] for more details.
211+
212+
==== Build time Compilation
213+
214+
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.
215+
216+
To compile your WASM module at build time, add the Chicory compiler Maven plugin to your `pom.xml`:
217+
218+
[source,xml]
219+
----
220+
<plugin>
221+
<groupId>com.dylibso.chicory</groupId>
222+
<artifactId>chicory-compiler-maven-plugin</artifactId>
223+
<executions>
224+
<execution>
225+
<id>wasm-shim</id>
226+
<goals>
227+
<goal>compile</goal>
228+
</goals>
229+
<configuration>
230+
<name>org.example.internal.WasmShim</name>
231+
<wasm>src/main/resources/plugin.wasm</wasm>
232+
</configuration>
233+
</execution>
234+
</executions>
235+
</plugin>
236+
----
237+
238+
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:
239+
240+
[source,java]
241+
----
242+
@Produces
243+
public PluginFactory waf() {
244+
return PluginFactory.builder(WasmShim.load())
245+
.withMachineFactory(WasmShim::create)
246+
.withName("waf")
247+
.withPluginConfig(CONFIG)
248+
.withMetricsHandler(new SimpleMetricsHandler())
249+
.build();
250+
}
251+
----
252+
253+
Please refer to the https://chicory.dev/docs/usage/build-time-compiler[Chicory Build time Compilation documentation] for more details.

‎integration-tests/corazawaf-example/pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,13 +71,13 @@
7171
<plugins>
7272
<plugin>
7373
<groupId>com.dylibso.chicory</groupId>
74-
<artifactId>aot-maven-plugin-experimental</artifactId>
74+
<artifactId>chicory-compiler-maven-plugin</artifactId>
7575
<version>${chicory.version}</version>
7676
<executions>
7777
<execution>
7878
<id>wasm-shim</id>
7979
<goals>
80-
<goal>wasm-aot-gen</goal>
80+
<goal>compile</goal>
8181
</goals>
8282
<configuration>
8383
<name>org.example.internal.CorazaWAF</name>

‎integration-tests/corazawaf-example/src/main/java/org/example/App.java‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,9 @@
88
import jakarta.enterprise.context.ApplicationScoped;
99
import jakarta.enterprise.inject.Produces;
1010

11-
import org.example.internal.CorazaWAFModule;
12-
13-
import com.dylibso.chicory.wasm.WasmModule;
11+
import org.example.internal.CorazaWAF;
1412

1513
import io.roastedroot.proxywasm.LogHandler;
16-
import io.roastedroot.proxywasm.Plugin;
1714
import io.roastedroot.proxywasm.PluginFactory;
1815
import io.roastedroot.proxywasm.SimpleMetricsHandler;
1916

@@ -31,8 +28,6 @@ public App() {
3128
// Default constructor
3229
}
3330

34-
private static WasmModule module = CorazaWAFModule.load();
35-
3631
static final String CONFIG;
3732

3833
static {
@@ -54,9 +49,9 @@ public App() {
5449
*/
5550
@Produces
5651
public PluginFactory waf() {
57-
return () -> Plugin.builder(module)
52+
return PluginFactory.builder(CorazaWAF.load())
53+
.withMachineFactory(CorazaWAF::create)
5854
.withName("waf")
59-
.withMachineFactory(CorazaWAFModule::create)
6055
.withShared(true)
6156
.withLogger(DEBUG ? LogHandler.SYSTEM : null)
6257
.withPluginConfig(CONFIG)

‎integration-tests/integration-tests/pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,13 @@
4747
<plugins>
4848
<plugin>
4949
<groupId>com.dylibso.chicory</groupId>
50-
<artifactId>aot-maven-plugin-experimental</artifactId>
50+
<artifactId>chicory-compiler-maven-plugin</artifactId>
5151
<version>${chicory.version}</version>
5252
<executions>
5353
<execution>
5454
<id>wasm-shim</id>
5555
<goals>
56-
<goal>wasm-aot-gen</goal>
56+
<goal>compile</goal>
5757
</goals>
5858
<configuration>
5959
<name>org.example.internal.MainWasm</name>

0 commit comments

Comments
 (0)