Enhance Error Handling in VSecMHttpClient with Custom Exceptions and refactoring Javadocs (#1240)

* Updated Javadoc comments in VSecMHttpClient

* Updated Javadoc comments in service/FetchService

* Improved exception handling for client

* Javadoc refactored

* Exception folder created

Author: Doguhannilt

sdk-java/src/main/java/org/vsecm/client/VSecMHttpClient.java

@@ -26,35 +26,62 @@
  */
 public class VSecMHttpClient {
     private static final Logger LOGGER = Logger.getLogger(VSecMHttpClient.class.getName());
+
+    /**
+     * The path to the SPIFFE socket used to communicate with the SPIFFE Workload API.
+     * This socket provides access to the X.509 SVID (SPIFFE Verifiable Identity Document)
+     * used for mutual TLS authentication.
+     */
     private static final String SPIFFE_SOCKET_PATH = "unix:///spire-agent-socket/spire-agent.sock";
 
     /**
-     * Creates an instance of {@link HttpClient} with SPIFFE-based SSL context.
-     * This client can be used for secure HTTP communication.
+     * Creates and configures an {@link HttpClient} instance with SPIFFE-based mutual TLS.
+     * This client is used for secure communication with SPIFFE-enabled services.
+     *
+     * @return An instance of {@link HttpClient} configured with mutual TLS using SPIFFE credentials.
      *
-     * @return A configured {@link HttpClient} instance ready for secure communication.
-     * @throws RuntimeException if there's an issue configuring the SSL context,
-     *                          encapsulating any underlying exceptions.
+     * @throws VSecMHttpClientException.SocketPathError If the SPIFFE socket path is inaccessible.
+     * @throws VSecMHttpClientException.X509FetchError If fetching X.509 SVIDs fails.
+     * @throws VSecMHttpClientException.SSLContextError If SSLContext configuration fails.
+     * @throws RuntimeException If an unknown error occurs during client initialization.
+     *
+     * @see #configureSSLContext()
      */
     public HttpClient client() {
         try {
             SSLContext sslContext = configureSSLContext();
             return HttpClient.newBuilder().sslContext(sslContext).build();
         } catch (Exception e) {
             LOGGER.log(Level.SEVERE, "Failed to fetch secrets", e);
-            throw new RuntimeException(e);
+
+            if (e instanceof SocketEndpointAddressException) {
+                throw VSecMHttpClientException.socketPathError("SPIFFE socket path is inaccessible: " + e.getMessage());
+            } else if (e instanceof X509SourceException) {
+                throw VSecMHttpClientException.x509FetchError("Failed to fetch X.509 SVIDs: " + e.getMessage());
+            } else if (e instanceof NoSuchAlgorithmException || e instanceof KeyManagementException) {
+                throw VSecMHttpClientException.sslContextError("SSLContext configuration failed: " + e.getMessage());
+            } else {
+                throw new RuntimeException("Unknown error occurred: " + e.getMessage(), e);
+            }
         }
     }
 
     /**
-     * Configures and returns an {@link SSLContext} suitable for SPIFFE based secure communication.
+     * Configures and returns an {@link SSLContext} instance using SPIFFE credentials.
+     * This method creates a secure SSL context that is configured with X.509 SVIDs
+     * obtained from the SPIFFE Workload API to enable mutual TLS for communication.
      *
-     * @return An {@link SSLContext} configured with SPIFFE X.509 SVIDs for mutual TLS.
-     * @throws SocketEndpointAddressException If the SPIFFE Workload API socket endpoint address is incorrect.
-     * @throws X509SourceException If there's an issue fetching or processing the X.509 SVIDs.
-     * @throws NoSuchAlgorithmException If the SSL context cannot be instantiated due to a missing algorithm.
-     * @throws KeyManagementException If there's an issue initializing the {@link SSLContext} with SPIFFE SVIDs.
+     * @return A configured {@link SSLContext} that supports mutual TLS using SPIFFE identities.
+     * @throws SocketEndpointAddressException If there is an issue with the SPIFFE socket path,
+     *                                         typically indicating that the SPIFFE Workload API is inaccessible.
+     * @throws X509SourceException If there is an error fetching or processing the X.509 SVIDs from the SPIFFE Workload API.
+     * @throws NoSuchAlgorithmException If the SSLContext cannot be instantiated due to a missing or unsupported algorithm.
+     * @throws KeyManagementException If there is an issue initializing the SSLContext, typically indicating a problem
+     *                                with key management or protocol setup.
+     * @see DefaultX509Source
+     * @see SpiffeSslContextFactory
      */
+
     private SSLContext configureSSLContext() throws SocketEndpointAddressException, X509SourceException, NoSuchAlgorithmException, KeyManagementException {
         DefaultX509Source.X509SourceOptions sourceOptions = DefaultX509Source.X509SourceOptions
                 .builder()

sdk-java/src/main/java/org/vsecm/client/VSecMHttpClientException.java

@@ -0,0 +1,63 @@
+package org.vsecm.client;
+
+/**
+ * Custom exception class for handling errors in the VSecMHttpClient class.
+ * Each error code corresponds to a specific type of failure encountered during
+ * the HTTP client setup and SSL context configuration.
+ */
+public class VSecMHttpClientException extends RuntimeException {
+
+    // Error codes for different failure cases
+    public static final int ERROR_CODE_SOCKET_PATH = 1000;
+    public static final int ERROR_CODE_X509_FETCH = 1001;
+    public static final int ERROR_CODE_SSL_CONTEXT = 1002;
+    public static final int ERROR_CODE_KEY_MANAGEMENT = 1003;
+
+    private final int errorCode;
+
+    /**
+     * Constructor for the custom exception.
+     *
+     * @param errorCode The specific error code representing the type of failure.
+     * @param message The detailed error message.
+     */
+    public VSecMHttpClientException(int errorCode, String message) {
+        super(message);
+        this.errorCode = errorCode;
+    }
+
+    /**
+     * Returns the error code associated with this exception.
+     *
+     * @return The error code.
+     */
+    public int getErrorCode() {
+        return errorCode;
+    }
+
+    @Override
+    public String toString() {
+        return "VSecMHttpClientException{" +
+                "errorCode=" + errorCode +
+                ", message=" + getMessage() +
+                '}';
+    }
+
+    // Convenience methods for specific error codes
+
+    public static VSecMHttpClientException socketPathError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_SOCKET_PATH, message);
+    }
+
+    public static VSecMHttpClientException x509FetchError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_X509_FETCH, message);
+    }
+
+    public static VSecMHttpClientException sslContextError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_SSL_CONTEXT, message);
+    }
+
+    public static VSecMHttpClientException keyManagementError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_KEY_MANAGEMENT, message);
+    }
+}

sdk-java/src/main/java/org/vsecm/exception/VSecMHttpClientException.java

@@ -0,0 +1,74 @@
+package org.vsecm.exception;
+
+
+
+/**
+ * Custom exception class for handling errors in the VSecMHttpClient class.
+ * Each error code corresponds to a specific type of failure encountered during
+ * the HTTP client setup and SSL context configuration.
+ */
+
+public class VSecMHttpClientException extends RuntimeException {
+
+    // Error codes for different failure cases
+    public static final int ERROR_CODE_SOCKET_PATH = 1000;
+    public static final int ERROR_CODE_X509_FETCH = 1001;
+    public static final int ERROR_CODE_SSL_CONTEXT = 1002;
+    public static final int ERROR_CODE_KEY_MANAGEMENT = 1003;
+
+    private final int errorCode;
+
+    /**
+     * Constructor for the custom exception.
+     *
+     * @param errorCode The specific error code representing the type of failure.
+     * @param message The detailed error message.
+     */
+
+
+    public VSecMHttpClientException(int errorCode, String message) {
+        super(message);
+        this.errorCode = errorCode;
+    }
+
+
+    /**
+     * Returns the error code associated with this exception.
+     *
+     * @return The error code.
+     */
+
+    public int getErrorCode() {
+        return errorCode;
+    }
+
+
+    @Override
+    public String toString() {
+        return "VSecMHttpClientException{" +
+                "errorCode=" + errorCode +
+                ", message=" + getMessage() +
+                '}';
+    }
+
+    // Convenience methods for specific error codes
+    public static VSecMHttpClientException socketPathError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_SOCKET_PATH, message);
+    }
+
+
+    public static VSecMHttpClientException x509FetchError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_X509_FETCH, message);
+    }
+
+
+    public static VSecMHttpClientException sslContextError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_SSL_CONTEXT, message);
+    }
+
+
+    public static VSecMHttpClientException keyManagementError(String message) {
+        return new VSecMHttpClientException(ERROR_CODE_KEY_MANAGEMENT, message);
+    }
+
+}

sdk-java/src/main/java/org/vsecm/service/FetchService.java

@@ -25,11 +25,27 @@ public final class FetchService {
     private FetchService(){}
 
     /**
-     * Fetches data as a {@link String} from the specified URI using an HTTP GET request.
-     * This method utilizes a SPIFFE-enabled HTTP client for secure communication.
+     * Fetches data from the specified URI using an HTTP GET request.
+     * The request is sent over a secure channel using a SPIFFE-enabled HTTP client,
+     * which ensures mutual TLS authentication as part of the communication process.
      *
-     * @param secretUri The URI from which to fetch data. Must be a valid URI string.
-     * @return The body of the HTTP response as a {@link String}. Returns an empty string if the request fails.
+     * <p>This method constructs an HTTP GET request to the provided URI, sends the request
+     * using the {@link VSecMHttpClient} (which handles SPIFFE-based secure communication),
+     * and returns the response body as a {@link String}. If any errors occur during
+     * the request (such as invalid URI, network issues, or interrupted request), an empty string
+     * is returned, and the error is logged.</p>
+     *
+     * @param secretUri The URI from which to fetch the data. This must be a well-formed URI string
+     *                  that points to a resource to be fetched.
+     *                  Example: "https://example.com/data".
+     * @return The body of the HTTP response as a {@link String}. If the request fails or an error occurs,
+     *         an empty string is returned.
+     * @throws IllegalArgumentException if the URI is not valid or cannot be parsed.
+     * @throws URISyntaxException if the provided URI is malformed or invalid.
+     * @throws IOException if an I/O error occurs during communication with the server.
+     * @throws InterruptedException if the request is interrupted during execution.
+     *
+     * @see VSecMHttpClient
      */
     public static String fetch(String secretUri) {
         try {