feat!: Add apiKey support to API requests

- Introduced `apiKey` field for secure authentication in configuration and API requests.
- Updated clear and task APIs to accept enhanced request objects.
- Added required tests and assertions for `apiKey` handling across all request types.
- Refactored HTTP operations to include `apiKey` in request headers.
- Introduced new classes for managing authentication details.

Fixes #187

Signed-off-by: Eric Deandrea <[email protected]>

Author: edeandrea

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeClearApi.java

@@ -1,6 +1,7 @@
 package ai.docling.serve.api;
 
-import ai.docling.serve.api.clear.request.ClearRequest;
+import ai.docling.serve.api.clear.request.ClearConvertersRequest;
+import ai.docling.serve.api.clear.request.ClearResultsRequest;
 import ai.docling.serve.api.clear.response.ClearResponse;
 
 /**
@@ -11,23 +12,27 @@
  */
 public interface DoclingServeClearApi {
   /**
-   * Clears all registered converters associated with the API.
-   * This method removes any previously configured or cached converters,
-   * effectively resetting the converter state to an uninitialized state.
-   * After invoking this method, no converters will be available until new ones are added or configured.
+   * Clears all currently configured converters within the Docling Serve API.
+   * This operation removes any registered converters, effectively resetting
+   * the system to a state without active converter configurations.
+   *
+   * @param request an instance of {@link ClearConvertersRequest} containing
+   *                the authentication details required to authorize this operation.
+   * @return a {@link ClearResponse} object indicating the status of the clear
+   *         operation, such as success or failure.
    */
-  ClearResponse clearConverters();
+  ClearResponse clearConverters(ClearConvertersRequest request);
 
   /**
-   * Clears stored results based on the specified {@link ClearRequest}.
+   * Clears stored results based on the specified {@link ClearResultsRequest}.
    * This method removes results that match the criteria provided in the
    * request, such as results older than a specified duration.
    *
-   * @param request an instance of {@link ClearRequest} containing the criteria
+   * @param request an instance of {@link ClearResultsRequest} containing the criteria
    *                for clearing stored results, including the duration threshold
    *                or other parameters.
    * @return a {@link ClearResponse} object indicating the status of the clear
    *         operation, such as success or failure.
    */
-  ClearResponse clearResults(ClearRequest request);
+  ClearResponse clearResults(ClearResultsRequest request);
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/auth/AuthenticatedRequest.java

@@ -0,0 +1,28 @@
+package ai.docling.serve.api.auth;
+
+/**
+ * Represents a request that requires authentication for secure access to resources.
+ *
+ * Implementations of this interface define a contract for providing authentication
+ * details associated with the request. This is used to ensure authorized interaction
+ * with APIs or protected services.
+ *
+ * Methods:
+ * - {@code getAuthentication()}: Retrieves the {@link Authentication} details
+ *   required to authorize the request.
+ */
+public interface AuthenticatedRequest {
+  /**
+   * Retrieves the authentication details associated with the request.
+   *
+   * This method provides the {@link Authentication} object required to authorize
+   * interaction with secure resources or APIs. Implementations should ensure
+   * the returned object contains the necessary credentials for successful
+   * authentication.
+   *
+   * @return an {@link Authentication} instance containing the authentication
+   *         details required for the request, or {@code null} if authentication
+   *         is not applicable.
+   */
+  Authentication getAuthentication();
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/auth/Authentication.java

@@ -0,0 +1,31 @@
+package ai.docling.serve.api.auth;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Represents authentication details required for secure API usage.
+ *
+ * The {@code Authentication} class encapsulates the necessary credentials
+ * for accessing restricted resources, such as an API key. It is designed
+ * to be immutable and thread-safe.
+ *
+ * This class uses Lombok annotations to provide a builder pattern, generate
+ * a getter for its fields, and produce a string representation.
+ *
+ * Features:
+ * - {@code apiKey}: Optional API key to authorize requests.
+ */
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class Authentication {
+  /**
+   * Represents an optional API key used to authenticate requests to a secure service.
+   *
+   * This field is nullable, indicating that the API key may not always be provided
+   * or required, depending on the specific use case or configuration of the client.
+   * When present, the API key is used to authorize access to restricted resources.
+   */
+  @Nullable
+  private String apiKey;
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/auth/package-info.java

@@ -0,0 +1,4 @@
+@NullMarked
+package ai.docling.serve.api.auth;
+
+import org.jspecify.annotations.NullMarked;

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/chunk/request/HierarchicalChunkDocumentRequest.java

@@ -4,11 +4,14 @@
 
 import org.jspecify.annotations.Nullable;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonSetter;
 import com.fasterxml.jackson.annotation.Nulls;
 
+import ai.docling.serve.api.auth.AuthenticatedRequest;
+import ai.docling.serve.api.auth.Authentication;
 import ai.docling.serve.api.chunk.request.options.HierarchicalChunkerOptions;
 import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
 import ai.docling.serve.api.convert.request.source.Source;
@@ -24,7 +27,7 @@
 @lombok.Builder(toBuilder = true)
 @lombok.Getter
 @lombok.ToString
-public class HierarchicalChunkDocumentRequest {
+public class HierarchicalChunkDocumentRequest implements AuthenticatedRequest {
 
   @JsonProperty("sources")
   @JsonSetter(nulls = Nulls.AS_EMPTY)
@@ -48,6 +51,11 @@ public class HierarchicalChunkDocumentRequest {
   @lombok.Builder.Default
   private HierarchicalChunkerOptions chunkingOptions = HierarchicalChunkerOptions.builder().build();
 
+  @JsonIgnore
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Authentication authentication = Authentication.builder().build();
+
   @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
   public static class Builder { }
 

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/chunk/request/HybridChunkDocumentRequest.java

@@ -4,11 +4,14 @@
 
 import org.jspecify.annotations.Nullable;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonSetter;
 import com.fasterxml.jackson.annotation.Nulls;
 
+import ai.docling.serve.api.auth.AuthenticatedRequest;
+import ai.docling.serve.api.auth.Authentication;
 import ai.docling.serve.api.chunk.request.options.HybridChunkerOptions;
 import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
 import ai.docling.serve.api.convert.request.source.Source;
@@ -24,7 +27,7 @@
 @lombok.Builder(toBuilder = true)
 @lombok.Getter
 @lombok.ToString
-public class HybridChunkDocumentRequest {
+public class HybridChunkDocumentRequest implements AuthenticatedRequest {
 
   @JsonProperty("sources")
   @JsonSetter(nulls = Nulls.AS_EMPTY)
@@ -48,6 +51,11 @@ public class HybridChunkDocumentRequest {
   @lombok.Builder.Default
   private HybridChunkerOptions chunkingOptions = HybridChunkerOptions.builder().build();
 
+  @JsonIgnore
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Authentication authentication = Authentication.builder().build();
+
   @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
   public static class Builder { }
 

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/clear/request/ClearConvertersRequest.java

@@ -0,0 +1,30 @@
+package ai.docling.serve.api.clear.request;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+
+import ai.docling.serve.api.auth.AuthenticatedRequest;
+import ai.docling.serve.api.auth.Authentication;
+
+/**
+ * Represents a request to clear or reset configured converters using the Docling Serve API.
+ *
+ * This class provides a mechanism to manage converter configurations through explicit
+ * reset operations. It includes authentication information required to authorize the request.
+ *
+ * Features:
+ * - {@code authentication}: Provides the authentication details needed to validate
+ *   and authorize the reset operation. A default authentication instance is used
+ *   when none is explicitly provided.
+ *
+ * This class is immutable and can be constructed or modified using a builder
+ * that is generated via Lombok annotations.
+ */
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class ClearConvertersRequest implements AuthenticatedRequest {
+  @JsonIgnore
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Authentication authentication = Authentication.builder().build();
+}

…erve/api/clear/request/ClearRequest.java …i/clear/request/ClearResultsRequest.javadocling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/clear/request/ClearRequest.java renamed to docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/clear/request/ClearResultsRequest.java docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/clear/request/ClearRequest.java renamed to docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/clear/request/ClearResultsRequest.java

@@ -2,6 +2,11 @@
 
 import java.time.Duration;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
+
+import ai.docling.serve.api.auth.AuthenticatedRequest;
+import ai.docling.serve.api.auth.Authentication;
+
 /**
  * Represents a request to clear stale data via the Docling Serve Clear API.
  * This class provides a mechanism to specify a threshold duration, after which data
@@ -17,7 +22,7 @@
 @lombok.Builder(toBuilder = true)
 @lombok.Getter
 @lombok.ToString
-public class ClearRequest {
+public class ClearResultsRequest implements AuthenticatedRequest {
   /**
    * Represents the default duration used as a threshold for clearing stale results
    * or data in the Docling Serve Clear API. Results older than this duration
@@ -30,4 +35,9 @@ public class ClearRequest {
   @lombok.NonNull
   @lombok.Builder.Default
   private Duration olderThen = DEFAULT_OLDER_THAN;
+
+  @JsonIgnore
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Authentication authentication = Authentication.builder().build();
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/ConvertDocumentRequest.java

@@ -4,11 +4,14 @@
 
 import org.jspecify.annotations.Nullable;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonSetter;
 import com.fasterxml.jackson.annotation.Nulls;
 
+import ai.docling.serve.api.auth.AuthenticatedRequest;
+import ai.docling.serve.api.auth.Authentication;
 import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
 import ai.docling.serve.api.convert.request.source.Source;
 import ai.docling.serve.api.convert.request.target.Target;
@@ -27,7 +30,7 @@
 @lombok.Builder(toBuilder = true)
 @lombok.Getter
 @lombok.ToString
-public class ConvertDocumentRequest {
+public class ConvertDocumentRequest implements AuthenticatedRequest {
   @JsonProperty("sources")
   @JsonSetter(nulls = Nulls.AS_EMPTY)
   @lombok.Singular
@@ -42,6 +45,11 @@ public class ConvertDocumentRequest {
   @Nullable
   private Target target;
 
+  @JsonIgnore
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Authentication authentication = Authentication.builder().build();
+
   @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
   public static class Builder { }
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/task/request/TaskResultRequest.java

@@ -1,5 +1,10 @@
 package ai.docling.serve.api.task.request;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
+
+import ai.docling.serve.api.auth.AuthenticatedRequest;
+import ai.docling.serve.api.auth.Authentication;
+
 /**
  * Represents a request to retrieve the result of a task.
  *
@@ -15,7 +20,12 @@
 @lombok.Builder(toBuilder = true)
 @lombok.Getter
 @lombok.ToString
-public class TaskResultRequest {
+public class TaskResultRequest implements AuthenticatedRequest {
   @lombok.NonNull
   private String taskId;
+
+  @JsonIgnore
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private Authentication authentication = Authentication.builder().build();
 }