[Feature] Add library hooks (#277)

Author: jchen293

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## Next release
+
+- Adds new `RequestHook` and `ResponseHook` classes. (un)subscribe to them with the new `subscribeToRequestHook`, `subscribeToResponseHook`, `unsubscribeFromRequestHook`, or `unsubscribeFromResponseHook` methods of an `EasyPostClient`
+
 ## v6.7.0 (2023-06-06)
 
 - Retrieving carrier metadata is now generally available via `client.carrierMetadata.retrieve`

Makefile

@@ -62,6 +62,6 @@ test:
 ## update-examples-submodule - Update the examples submodule
 update-examples-submodule:
 	git submodule init
-	git submodule update
+	git submodule update --remote
 
 .PHONY: help build clean coverage docs install-styleguide install lint publish publish-dry release scan scan-strict test update-examples-submodule

README.md

@@ -89,6 +89,32 @@ public class CreateShipment {
 }
 ```
 
+## HTTP Hooks
+
+Users can subscribe to HTTP requests and responses via the `RequestHook` and `ResponseHook` objects. To do so, pass a function to the `subscribeToRequestHook` or `subscribeToResponseHook` methods of an `EasyPostClient` object:
+
+```java
+    EasyPostClient client = new EasyPostClient(System.getenv("EASYPOST_API_KEY"));
+
+    // For request hook custom function, make sure you have RequestHookResponses in the parameter
+    public static Object requestHookFunction(RequestHookResponses datas) {
+        // Pass your code here, the information about the request/response is available within the datas parameter.
+        return true;
+    }
+
+    client.subscribeToRequestHook(requestHookFunction); // subscribe to request hook by passing your custom function
+    client.unsubscribeToRequestHook(requestHookFunction); // unsubscribe from request hook
+
+    // For response hook custom function, make sure you have ResponseHookResponses in the parameter
+    public static Object responseHookFunction(ResponseHookResponses datas) {
+        // Pass your code here, the information about the request/response is available within the datas parameter.
+        return true;
+    }
+
+    client.subscribeToRequestHook(responseHookFunction); // subscribe to response hook by passing your custom function
+    client.unsubscribeToRequestHook(responseHookFunction); // unsubscribe from response hook
+```
+
 ## Documentation
 
 API documentation can be found at: <https://easypost.com/docs/api>.

dependency-check-suppressions.xml

@@ -8,5 +8,6 @@
         <vulnerabilityName>CVE-2022-3171</vulnerabilityName>
         <vulnerabilityName>CVE-2022-3509</vulnerabilityName>
         <vulnerabilityName>CVE-2022-3510</vulnerabilityName>
+        <vulnerabilityName>CVE-2023-2976</vulnerabilityName>
     </suppress>
 </suppressions>

examples

@@ -0,0 +1,35 @@
+package com.easypost.hooks;
+
+import java.util.function.Function;
+import java.util.ArrayList;
+import java.util.List;
+
+public class RequestHook {
+    private List<Function<RequestHookResponses, Object>> eventHandlers = new ArrayList<>();
+
+    /**
+     * Add a function to the list of event handlers.
+     * @param handler The event handler function to be added.
+     */
+    public void addEventHandler(Function<RequestHookResponses, Object> handler) {
+        eventHandlers.add(handler);
+    }
+
+    /**
+     * Remove a function to the list of event handlers.
+     * @param handler The event handler function to be removed.
+     */
+    public void removeEventHandler(Function<RequestHookResponses, Object> handler) {
+        eventHandlers.remove(handler);
+    }
+    
+    /**
+     * Execute all the functions from the event handlers.
+     * @param datas The datas from the hooks.
+     */
+    public void executeEventHandler(RequestHookResponses datas) {
+        for (Function<RequestHookResponses, Object> eventHandler : eventHandlers) {
+            Object result = eventHandler.apply(datas);
+        }
+    }
+}

src/main/java/com/easypost/hooks/RequestHook.java

@@ -0,0 +1,38 @@
+package com.easypost.hooks;
+
+import java.util.Map;
+
+import com.google.gson.JsonObject;
+
+import lombok.Getter;
+import lombok.Setter;
+
+@Setter @Getter
+public class RequestHookResponses {
+    private Map<String, String> headers;
+    private String method;
+    private String path;
+    private JsonObject requestBody;
+    private String requestTimestamp;
+    private String requestUuid;
+
+    /**
+     * RequestHookResponses constructor.
+     *
+     * @param headers The headers of the request.
+     * @param method The HTTP method of the request.
+     * @param path The path of the request.
+     * @param requestBody The JSON object representing the request body.
+     * @param requestTimestamp The timestamp of the request.
+     * @param requestUuid The UUID of the request.
+     */
+    public RequestHookResponses(Map<String, String> headers, String method, String path, JsonObject requestBody,
+                                String requestTimestamp, String requestUuid) {
+        this.headers = headers;
+        this.method = method;
+        this.path = path;
+        this.requestBody = requestBody;
+        this.requestTimestamp = requestTimestamp;
+        this.requestUuid = requestUuid;
+    }
+}

src/main/java/com/easypost/hooks/RequestHookResponses.java

@@ -0,0 +1,35 @@
+package com.easypost.hooks;
+
+import java.util.function.Function;
+import java.util.ArrayList;
+import java.util.List;
+
+public class ResponseHook {
+    private List<Function<ResponseHookResponses, Object>> eventHandlers = new ArrayList<>();
+
+    /**
+     * Add a function to the list of event handlers.
+     * @param handler The event handler function to be added.
+     */
+    public void addEventHandler(Function<ResponseHookResponses, Object> handler) {
+        eventHandlers.add(handler);
+    }
+
+    /**
+     * Remove a function to the list of event handlers.
+     * @param handler The event handler function to be removed.
+     */
+    public void removeEventHandler(Function<ResponseHookResponses, Object> handler) {
+        eventHandlers.remove(handler);
+    }
+    
+    /**
+     * Execute all the functions from the event handlers.
+     * @param datas The datas from the hooks.
+     */
+    public void executeEventHandler(ResponseHookResponses datas) {
+        for (Function<ResponseHookResponses, Object> eventHandler : eventHandlers) {
+            Object result = eventHandler.apply(datas);
+        }
+    }
+}

src/main/java/com/easypost/hooks/ResponseHook.java

@@ -0,0 +1,42 @@
+package com.easypost.hooks;
+
+import java.util.Map;
+
+import lombok.Getter;
+import lombok.Setter;
+
+@Setter @Getter
+public class ResponseHookResponses {
+    private int httpStatus;
+    private Map<String, String> headers;
+    private String method;
+    private String path;
+    private String responseBody;
+    private String responseTimestamp;
+    private String requestTimestamp;
+    private String requestUuid;
+
+    /**
+     * ResponseHookResponses constructor.
+     *
+     * @param httpStatus The HTTP status code of the response.
+     * @param headers The headers of the response.
+     * @param method The HTTP method of the request.
+     * @param path The path of the request.
+     * @param responseBody The response body as a string.
+     * @param responseTimestamp The timestamp of the response.
+     * @param requestTimestamp The timestamp of the corresponding request.
+     * @param requestUuid The UUID of the corresponding request.
+     */
+    public ResponseHookResponses(int httpStatus, Map<String, String> headers, String method, String path,
+        String responseBody, String responseTimestamp, String requestTimestamp, String requestUuid) {
+        this.httpStatus = httpStatus;
+        this.headers = headers;
+        this.method = method;
+        this.path = path;
+        this.responseBody = responseBody;
+        this.responseTimestamp = responseTimestamp;
+        this.requestTimestamp = requestTimestamp;
+        this.requestUuid = requestUuid;
+    }
+}

src/main/java/com/easypost/hooks/ResponseHookResponses.java

@@ -0,0 +1,9 @@
+/**
+ * Custom hook classes for the EasyPost API.
+ *
+ * @author EasyPost developers
+ * @version 1.0
+ * @see <a href="https://www.easypost.com/docs">EasyPost API documentation</a>
+ * @since 1.0
+ */
+package com.easypost.hooks;