Refactor to simplify user facing API and add Javadoc.

README.md

@@ -40,11 +40,12 @@ The `WasmPlugin` annotation is used to specify the name of the plugin to be used
 ```java
 package io.roastedroot.proxywasm.jaxrs.example;
 
+import com.dylibso.chicory.experimental.aot.AotMachine;
 import com.dylibso.chicory.wasm.Parser;
 import com.dylibso.chicory.wasm.WasmModule;
+import io.roastedroot.proxywasm.Plugin;
+import io.roastedroot.proxywasm.PluginFactory;
 import io.roastedroot.proxywasm.StartException;
-import io.roastedroot.proxywasm.plugin.Plugin;
-import io.roastedroot.proxywasm.plugin.PluginFactory;
 import jakarta.enterprise.context.ApplicationScoped;
 import jakarta.enterprise.inject.Produces;
 import java.nio.file.Path;
@@ -60,10 +61,11 @@ public class App {
     @Produces
     public PluginFactory example() throws StartException {
         return () ->
-                Plugin.builder()
+                Plugin.builder(module)
                         .withName("example")
                         .withPluginConfig("{ \"type\": \"headerTests\" }")
-                        .build(module);
+                        .withMachineFactory(AotMachine::new)
+                        .build();
     }
 }
 ```

pom.xml

@@ -45,6 +45,8 @@
     <surefire-plugin.version>3.5.2</surefire-plugin.version>
     <failsafe-plugin.version>${surefire-plugin.version}</failsafe-plugin.version>
     <jandex.version>3.2.7</jandex.version>
+    <javadoc-plugin.version>3.11.2</javadoc-plugin.version>
+    <dependency-plugin.version>3.8.1</dependency-plugin.version>
 
     <!-- test time versions -->
     <junit.version>5.12.0</junit.version>
@@ -210,6 +212,7 @@
         </plugin>
 
       </plugins>
+
     </pluginManagement>
   </build>
 

proxy-wasm-java-host/pom.xml

@@ -100,6 +100,21 @@
         </configuration>
       </plugin>
 
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>${javadoc-plugin.version}</version>
+        <configuration>
+          <sourceFileExcludes>
+            <sourceFileExclude>**/internal/**</sourceFileExclude>
+          </sourceFileExcludes>
+          <links>
+            <link>https://www.javadoc.io/doc/com.dylibso.chicory/wasm/${chicory.version}/</link>
+            <link>https://www.javadoc.io/doc/com.dylibso.chicory/runtime/${chicory.version}/</link>
+          </links>
+        </configuration>
+      </plugin>
+
     </plugins>
   </build>
 </project>

proxy-wasm-java-host/src/main/java/io/roastedroot/proxywasm/ForeignFunction.java

@@ -1,5 +1,6 @@
 package io.roastedroot.proxywasm;
 
-public interface ForeignFunction {
-    byte[] apply(byte[] data);
-}
+/**
+ * A functional interface that represents a foreign function call in the Proxy-Wasm.
+ */
+public interface ForeignFunction extends java.util.function.Function<byte[], byte[]> {}

proxy-wasm-java-host/src/main/java/io/roastedroot/proxywasm/LogHandler.java

@@ -1,9 +1,35 @@
 package io.roastedroot.proxywasm;
 
+/**
+ * Interface for handling logging sent form the guest of Proxy-WASM environment.
+ * <p>
+ * This interface provides methods to log messages at different levels and to retrieve the current
+ * log level.
+ */
 public interface LogHandler {
 
-    LogHandler DEFAULT = new LogHandler() {};
+    /**
+     * A default, no-operation {@code LogHandler}.
+     * It ignores all log messages and reports {@link LogLevel#CRITICAL} as the current log level,
+     * effectively disabling logging.
+     *
+     * <p>Useful as a placeholder or when logging is explicitly disabled.
+     */
+    LogHandler DEFAULT =
+            new LogHandler() {
+                @Override
+                public LogLevel getLogLevel() throws WasmException {
+                    // since we are not logging anything, we can return the highest log level
+                    return LogLevel.CRITICAL;
+                }
+            };
 
+    /**
+     * A simple {@code LogHandler} that logs all messages to {@link System#out}.
+     * Messages are prefixed with their corresponding {@link LogLevel}.
+     * The effective log level for this handler is {@link LogLevel#TRACE},
+     * meaning all messages will be printed.
+     */
     LogHandler SYSTEM =
             new LogHandler() {
                 @Override
@@ -12,8 +38,21 @@ public void log(LogLevel level, String message) throws WasmException {
                 }
             };
 
+    /**
+     * Logs a message at the specified log level.
+     *
+     * @param level the log level
+     * @param message the message to log
+     * @throws WasmException the result to provide the plugin
+     */
     default void log(LogLevel level, String message) throws WasmException {}
 
+    /**
+     * Gets the current log level.
+     *
+     * @return the current log level
+     * @throws WasmException the result to provide the plugin
+     */
     default LogLevel getLogLevel() throws WasmException {
         return LogLevel.TRACE;
     }

proxy-wasm-java-host/src/main/java/io/roastedroot/proxywasm/LogLevel.java

@@ -1,43 +1,57 @@
 package io.roastedroot.proxywasm;
 
 /**
- * Represents log levels for proxy WASM.
- * Converted from Go's LogLevel type.
+ * Represents log levels used within the Proxy-WASM ABI specification.
+ * These levels correspond to the values expected by the host environment
+ * when logging messages from a WASM module.
+ * <p>
+ * Converted from Go's LogLevel type in the proxy-wasm-go-sdk.
  */
 public enum LogLevel {
-    // The values follow the same order as in the Go code using iota (0-based incrementing)
+
+    /** Trace log level. Value: 0 */
     TRACE(0),
+    /** Debug log level. Value: 1 */
     DEBUG(1),
+    /** Info log level. Value: 2 */
     INFO(2),
+    /** Warn log level. Value: 3 */
     WARN(3),
+    /** Error log level. Value: 4 */
     ERROR(4),
+    /** Critical log level. Value: 5 */
     CRITICAL(5);
 
+    /** The integer representation of the log level, as defined by the Proxy-WASM ABI. */
     private final int value;
 
     /**
      * Constructor for LogLevel enum.
      *
-     * @param value The integer value of the log level
+     * @param value The integer value corresponding to the log level in the ABI.
      */
     LogLevel(int value) {
         this.value = value;
     }
 
     /**
-     * Get the integer value of this log level.
+     * Get the integer value of this log level as defined by the Proxy-WASM ABI.
      *
-     * @return The integer value
+     * @return The integer value representing the log level.
      */
     public int value() {
         return value;
     }
 
     /**
-     * Convert an integer value to a LogLevel.
+     * Convert an integer value to its corresponding LogLevel enum constant.
+     * This is useful for interpreting log level values received from the host
+     * or specified in configurations.
      *
-     * @param value The integer value to convert
-     * @return The corresponding LogLevel, or null if not found
+     * @param value The integer value to convert.
+     * @return The corresponding LogLevel enum constant.
+     * @throws IllegalArgumentException if the provided integer value does not
+     *                                  match any known LogLevel.
      */
     public static LogLevel fromInt(int value) {
         for (LogLevel level : values()) {

proxy-wasm-java-host/src/main/java/io/roastedroot/proxywasm/MetricType.java

@@ -1,38 +1,54 @@
 package io.roastedroot.proxywasm;
 
 /**
- * Represents the type of metric in proxy WASM.
+ * Represents the types of metrics that can be defined and manipulated
+ * via the Proxy-WASM ABI.
  */
 public enum MetricType {
+    /**
+     * A metric that only increments.
+     * Value: 0
+     */
     COUNTER(0),
+    /**
+     * A metric that can be arbitrarily set.
+     * Value: 1
+     */
     GAUGE(1),
+    /**
+     * A metric that accumulates observations into predefined buckets
+     * and a sum of observations.
+     * Value: 2
+     */
     HISTOGRAM(2);
 
+    /** The integer representation of the metric type, as defined by the Proxy-WASM ABI. */
     private final int value;
 
     /**
      * Constructor for MetricType enum.
      *
-     * @param value The integer value of the metric type
+     * @param value The integer value corresponding to the metric type in the ABI.
      */
     MetricType(int value) {
         this.value = value;
     }
 
     /**
-     * Get the integer value of this metric type.
+     * Get the integer value of this metric type as defined by the Proxy-WASM ABI.
      *
-     * @return The integer value
+     * @return The integer value representing the metric type.
      */
     public int getValue() {
         return value;
     }
 
     /**
-     * Convert an integer value to a MetricType.
+     * Convert an integer value to its corresponding MetricType enum constant.
      *
-     * @param value The integer value to convert
-     * @return The corresponding MetricType or null if the value doesn't match any MetricType
+     * @param value The integer value to convert.
+     * @return The corresponding MetricType enum constant, or {@code null} if the
+     *         provided integer value does not match any known MetricType.
      */
     public static MetricType fromInt(int value) {
         for (MetricType type : values()) {

proxy-wasm-java-host/src/main/java/io/roastedroot/proxywasm/MetricsHandler.java

@@ -1,25 +1,79 @@
 package io.roastedroot.proxywasm;
 
+import io.roastedroot.proxywasm.internal.WasmResult;
+
+/**
+ * Defines the contract for handling metrics operations initiated by a Proxy-WASM module.
+ * Implementations of this interface are responsible for interacting with the underlying
+ * metrics system of the host environment (Prometheus etc.).
+ *
+ * <p>The host environment provides implementations of these methods to allow WASM modules
+ * to define, manipulate, and retrieve metric values.
+ */
 public interface MetricsHandler {
 
+    /**
+     * A default, non-functional instance of {@code MetricsHandler}.
+     * This instance throws {@link WasmException} with {@link WasmResult#UNIMPLEMENTED}
+     * for methods that define or retrieve metrics, and returns {@link WasmResult#UNIMPLEMENTED}
+     * for methods that modify or remove metrics.
+     * Useful as a placeholder or base when only a subset of metrics functionality is needed.
+     */
     MetricsHandler DEFAULT = new MetricsHandler() {};
 
+    /**
+     * Defines a new metric.
+     *
+     * @param metricType The type of the metric (e.g., Counter, Gauge, Histogram).
+     * @param name       The name of the metric.
+     * @return A unique identifier (metric ID) for the newly defined metric.
+     * @throws WasmException If the metric cannot be defined (e.g., name conflict, unsupported type,
+     *                       or if the operation is unimplemented by the host).
+     */
     default int defineMetric(MetricType metricType, String name) throws WasmException {
         throw new WasmException(WasmResult.UNIMPLEMENTED);
     }
 
+    /**
+     * Removes or deletes a previously defined metric.
+     *
+     * @param metricId The unique identifier of the metric to remove.
+     * @return A {@link WasmResult} indicating the outcome of the operation (e.g., OK, NOT_FOUND, UNIMPLEMENTED).
+     */
     default WasmResult removeMetric(int metricId) {
         return WasmResult.UNIMPLEMENTED;
     }
 
+    /**
+     * Records a value for a metric (typically used for Gauges or Histograms).
+     *
+     * @param metricId The unique identifier of the metric.
+     * @param value    The value to record.
+     * @return A {@link WasmResult} indicating the outcome of the operation (e.g., OK, BAD_ARGUMENT, UNIMPLEMENTED).
+     */
     default WasmResult recordMetric(int metricId, long value) {
         return WasmResult.UNIMPLEMENTED;
     }
 
+    /**
+     * Increments a metric's value (typically used for Counters).
+     *
+     * @param metricId The unique identifier of the metric.
+     * @param value    The amount to increment by (can be negative to decrement, although convention is usually positive).
+     * @return A {@link WasmResult} indicating the outcome of the operation (e.g., OK, BAD_ARGUMENT, UNIMPLEMENTED).
+     */
     default WasmResult incrementMetric(int metricId, long value) {
         return WasmResult.UNIMPLEMENTED;
     }
 
+    /**
+     * Retrieves the current value of a metric.
+     *
+     * @param metricId The unique identifier of the metric.
+     * @return The current value of the metric.
+     * @throws WasmException If the metric cannot be retrieved (e.g., metric not found, type mismatch,
+     *                       or if the operation is unimplemented by the host).
+     */
     default long getMetric(int metricId) throws WasmException {
         throw new WasmException(WasmResult.UNIMPLEMENTED);
     }