Javadoc on site (kroxylicious#3534)

* Add on-site javadoc generation for public API modules

Creates a new javadoc aggregator submodule under kroxylicious-docs that
generates unified javadocs for the public API modules.

The javadocs will now be hosted on-site instead of relying on javadoc.io, and are
integrated into the existing documentation release pipeline. Webify.java has
been extended to support copying arbitrary directories, enabling the javadoc
output to be included in the website build.

* Tweak/tidy up package-info.java

I deleted kroxylicious-api/src/main/java/io/kroxylicious/proxy/package-info.java because this package contains only other packages. Documenting that ends up looking pretty weird in the Javadocs, and it's simply not necessary to have it for any other reason.

* docs: make kroxylicious-docs depend on kroxylicious-api-javadoc

Why:
We need the javadoc report generated before we run webify. Currently
maven builds them in the other order because kroxylicious-docs is the
parent of api-javadoc.

So this makes kroxylicious-parent the parent of api-javadoc and puts a
provided dependency from docs -> api-javadoc to ensure they build in the
right order.

Assisted-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Robert Young <robertyoungnz@gmail.com>
Signed-off-by: Tom Bentley <tbentley@redhat.com>
Signed-off-by: Robert Young <robertyoungnz@gmail.com>

Author: tombentley

.github/workflows/publish-snapshot-docs-to-website.yaml

@@ -67,7 +67,7 @@ jobs:
         working-directory: kroxylicious
 
       - name: Build with Maven
-        run: mvn -Dquick -P dist package --pl kroxylicious-docs
+        run: mvn -Dquick -P dist package --pl kroxylicious-docs --am
         working-directory: kroxylicious
 
       - name: Checkout Website

kroxylicious-api/src/main/java/io/kroxylicious/proxy/config/secret/package-info.java

@@ -4,6 +4,12 @@
  * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
  */
 
+/**
+ * <p>Abstraction for providing passwords to proxy configuration.</p>
+ * <p>{@link io.kroxylicious.proxy.config.secret.PasswordProvider} implementations allow
+ * passwords to be sourced from different locations (inline in configuration, external files).
+ * This enables separation of sensitive data from configuration files.</p>
+ */
 @ReturnValuesAreNonnullByDefault
 @DefaultAnnotationForParameters(NonNull.class)
 @DefaultAnnotation(NonNull.class)

kroxylicious-api/src/main/java/io/kroxylicious/proxy/config/tls/package-info.java

@@ -4,6 +4,11 @@
  * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
  */
 
+/**
+ * <p>TLS configuration for proxy connections to clients and upstream clusters.</p>
+ * <p>These configuration classes define keystores, trust stores, and TLS options
+ * for both server-side (client connections) and client-side (upstream cluster connections) TLS.</p>
+ */
 @ReturnValuesAreNonnullByDefault
 @DefaultAnnotationForParameters(NonNull.class)
 @DefaultAnnotation(NonNull.class)

kroxylicious-api/src/main/java/io/kroxylicious/proxy/filter/filterresultbuilder/package-info.java

@@ -4,6 +4,12 @@
  * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
  */
 
+/**
+ * <p>Builder API for constructing filter results.</p>
+ * <p>Filters use these builders (obtained from {@link io.kroxylicious.proxy.filter.FilterContext})
+ * to construct {@link io.kroxylicious.proxy.filter.FilterResult} instances that control
+ * message forwarding, dropping, short-circuiting, and connection management.</p>
+ */
 @ReturnValuesAreNonnullByDefault
 @DefaultAnnotationForParameters(NonNull.class)
 @DefaultAnnotation(NonNull.class)

kroxylicious-api/src/main/java/io/kroxylicious/proxy/filter/metadata/package-info.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright Kroxylicious Authors.
+ *
+ * Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/**
+ * <p>APIs for resolving topic IDs to topic names and handling metadata-related errors.</p>
+ * <p>Filters that need to translate topic IDs (e.g., from Fetch requests) to topic names
+ * can use {@link io.kroxylicious.proxy.filter.metadata.TopicNameMapping} to represent
+ * the results of such resolution, including handling of partial failures.</p>
+ */
+@ReturnValuesAreNonnullByDefault
+@DefaultAnnotationForParameters(NonNull.class)
+@DefaultAnnotation(NonNull.class)
+package io.kroxylicious.proxy.filter.metadata;
+
+import edu.umd.cs.findbugs.annotations.DefaultAnnotation;
+import edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import edu.umd.cs.findbugs.annotations.ReturnValuesAreNonnullByDefault;

kroxylicious-api/src/main/java/io/kroxylicious/proxy/filter/package-info.java

@@ -5,6 +5,37 @@
  */
 
 /**
+ * <p>The protocol filter API.</p>
+ *
+ * <p>An interface is provided for each kind of request and response in the Kafka protocol, e.g. {@link io.kroxylicious.proxy.filter.ProduceRequestFilter}.
+ * Protocol Filter implementations inherit whichever of the per-RPC interfaces they need to intercept.
+ * They can inherit multiple interfaces if necessary.
+ * For filters which needs to intercept most or all of the protocol it is more convenient to inherit
+ * {@link io.kroxylicious.proxy.filter.RequestFilter} and/or {@link io.kroxylicious.proxy.filter.ResponseFilter}.</p>
+ *
+ * <h2 id='assumptions'>Important facts about the Kafka protocol</h2>
+ *
+ * <h3 id='pipelining'>Pipelining</h3>
+ * <p>The Kafka protocol supports pipelining (meaning a client can send multiple requests,
+ * before getting a response for any of them). Therefore when writing a filter implementation
+ * do not assume you won't see multiple requests before seeing any corresponding responses.</p>
+ *
+ * <h3 id='ordering'>Ordering</h3>
+ * <p>A broker does not, in general, send responses in the same order as it receives requests.
+ * Therefore when writing a filter implementation do not assume ordering.</p>
+ *
+ * <h3 id='local_view'>Local view</h3>
+ * <p>A client may obtain information from one broker in a cluster and use it to interact with other
+ * brokers in the cluster (or the same broker, but on a different connection, and therefore a different
+ * channel and filter chain). A classic example would
+ * be a producer or consumer making a metadata connection and {@code Metadata} request to a broker and
+ * then connecting to a partition leader to producer/consume records ({@code Produce} and {@code Fetch} requests).</p>
+ *
+ * <p>So although your filter
+ * <em>implementation</em> might intercept both {@code Metadata} and {@code Produce} request/response
+ * (for example), those requests will not pass through the same <em>instance</em> of your filter
+ * implementation. Therefore it is incorrect, in general, to assume your filter has a global view of
+ * the communication between the client and broker.</p>
  *
  * <h2 id='implementing'>Implementing Filters</h2>
  *

kroxylicious-api/src/main/java/io/kroxylicious/proxy/package-info.java

@@ -20,5 +20,8 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface Plugin {
+    /**
+     * @return The type of configuration associated with the plugin implementation.
+     */
     Class<?> configType();
 }

kroxylicious-api/src/main/java/io/kroxylicious/proxy/plugin/Plugin.java

@@ -5,7 +5,7 @@
  */
 
 /**
- * API for defining plugins within configurtion.
+ * API for defining plugins within configuration.
  *
  * <h2>Terminology</h2>
  * <p>A <em>plugin interface</em> is a Java {@code interface} (or possibly a {@code class)} that can be used

kroxylicious-api/src/main/java/io/kroxylicious/proxy/plugin/package-info.java

@@ -15,6 +15,8 @@
  * For this reason, implementations of this interface should be named for the type of resource
  * (for example {@code Topic}, or {@code ConsumerGroup}) rather than the operations
  * enumerated (so not {@code TopicOperations} or {@code ConsumerGroupOperations}).
+ * The elements of the enumeration are typically verbs, such as {@code READ},
+ * {@code WRITE}, {@code DELETE}, {@code CREATE}, and so on.
  * @param <S> The self type.
  */
 public interface ResourceType<S extends Enum<S> & ResourceType<S>> {