feat(index.ts): added late response handling with onLateResponse callback

- Introduced `allowLateResponseAfterTimeout` flag in `sendRequest` method to enable late response handling.
- Added `onLateResponse` callback in `sendRequest` method to handle late responses after request timeout.
- Modified `sendRequest` to store timed-out requests conditionally in `timedOutRequests` object.
- Updated response handler to invoke `onLateResponse` for late responses.
- Improved error handling by passing `CustomError` or response to the callback.
- Added detailed logging for late response handling.
- Updated README with documentation for late response handling and new error codes.
- Updated `auth-service` example to demonstrate late response handling in the README.

This feature allows users to handle late responses gracefully, providing better flexibility for real-time communication in microservices.

Author: arijitcodes

README.md

@@ -66,6 +66,7 @@ License: [MIT](./LICENSE)
 - 🔗 Service discovery and registration (provided by the hub).
 - 📡 Request routing and response handling (provided by the hub).
 - ❤️ Heartbeat mechanism to detect and remove inactive services (provided by the hub).
+- ⏳ Late response handling even after a request timeout.
 
 <hr>
 
@@ -108,9 +109,14 @@ In this setup:
    - Once connected, the **[Hub](https://github.com/arijitcodes/microstream-hub)** keeps track of all connected services, so you don’t need to manually configure connections between services. However, you still need to specify the target service and method when sending a request.
 
 4. **Heartbeat Mechanism**:
+
    - Services send regular "heartbeats" to the **[Hub](https://github.com/arijitcodes/microstream-hub)** to confirm they’re active.
    - If a service stops sending heartbeats, the **[Hub](https://github.com/arijitcodes/microstream-hub)** removes it from the network.
 
+5. **Late Response Handling**:
+   - If a request times out, you can optionally allow late responses to be handled via a callback.
+   - This is useful for scenarios where the target service may respond after the timeout period - and the request is for something that can be done in the background or processed later.
+
 ### ✨ Why Choose MicroStream?
 
 **MicroStream** is designed to make microservice communication **simple**, **efficient**, and **scalable**. Here’s why you’ll love it:
@@ -121,6 +127,7 @@ In this setup:
 - **Scalable**: Easily add more services without reconfiguring the network.
 - **Lightweight**: Minimal overhead compared to traditional REST or gRPC.
 - **Flexible**: Works seamlessly with any microservice architecture.
+- **Late Response Handling**: Gracefully handle responses that arrive after a timeout.
 
 <hr>
 
@@ -177,6 +184,26 @@ try {
 } catch (error) {
   console.log("Error:", error.message);
 }
+
+// Example of late response handling
+try {
+  const response = await client.sendRequest(
+    "jwt-service",
+    "generate_jwt",
+    { userId: 123 },
+    true, // Allow late responses
+    (error, res) => {
+      if (error) {
+        console.log("Late response error:", error.message);
+      } else {
+        console.log("Late response received:", res);
+      }
+    }
+  );
+  console.log("Received response:", response);
+} catch (error) {
+  console.log("Error:", error.message);
+}
 ```
 
 ### Explanation 👨🏻‍🏫
@@ -187,12 +214,20 @@ try {
      - `event`: The event name to listen for.
      - `handler`: The function to handle the request. It receives the request data and returns the response.
 3. **Sending Requests**: The `sendRequest` method is used to send a request to another service. In this example, requests are sent to the "jwt-service" to generate a JWT and to the "profile-service" to fetch a profile by user ID.
-   - **Parameters**:
-     - `targetService`: The name of the target service.
-     - `event`: The event name to trigger on the target service.
-     - `data`: Optional data to send with the request.
-   - **Returns**: A promise that resolves with the response from the target service.
-   - **Error Handling**: The `sendRequest` method is wrapped in a try-catch block to handle any errors that may occur during the request. For example, if a request is sent to an invalid service, the [Hub](#microstream-hub-) will respond with an error, which will be received by the client and thrown accordingly. The catch block will catch the error, and the user can display it using the `error.message` property.
+
+- **Parameters**:
+
+  - `targetService`: The name of the target service.
+  - `event`: The event name to trigger on the target service.
+  - `data`: Optional data to send with the request.
+  - `allowLateResponseAfterTimeout`: Whether to allow handling late responses after the request times out (default: `false`).
+  - `onLateResponse`: Optional callback to handle late responses. This callback is invoked if:
+    - `allowLateResponseAfterTimeout` is true, and
+    - A late response is received after the request has timed out.
+
+- **Returns**: A promise that resolves with the response from the target service.
+
+- **Error Handling**: The `sendRequest` method is wrapped in a try-catch block to handle any errors that may occur during the request. For example, if a request is sent to an invalid service, the [**Hub**](#microstream-hub-) will respond with an error, which will be received by the client and thrown accordingly. The catch block will catch the error, and the user can display it using the `error.message` property. For more error related info, please have a look at the [Error Structure](#error-structure-) or the [Error Handling Section](#error-handling-)
 
 <hr>
 
@@ -279,11 +314,12 @@ try {
 
 ### Error Handling Best Practices 🎯
 
-1. Always wrap requests in try-catch blocks
+1. Always wrap requests in `try-catch` blocks
 2. Check error codes for specific error handling
-3. Use error.errorData for additional context in debugging
-4. Handle REQUEST_TIMEOUT errors with appropriate retry logic
-5. Implement proper logging for INTERNAL_SERVER_ERROR cases
+3. Use `error.errorData` for additional context in debugging
+4. Handle `REQUEST_TIMEOUT` errors with appropriate retry logic
+5. Implement proper logging for `INTERNAL_SERVER_ERROR` cases
+6. Use `allowLateResponseAfterTimeout` and `onLateResponse` to handle late responses gracefully
 
 ### Common Error Scenarios 🔄
 
@@ -306,10 +342,17 @@ try {
    - Useful for debugging service-side issues
 
 4. **Service Registration Errors**
+
    - Occurs during initial connection
    - Critical errors that may require process termination
    - Check for duplicate service names in your network
 
+5. **Late Response Errors**
+
+   - Occurs when a response is received after the request has timed out
+   - Includes the original request payload and response data
+   - Use `onLateResponse` to handle these scenarios gracefully
+
 <hr>
 
 ## MicroStream Hub 🏢

src/index.ts

@@ -44,6 +44,19 @@ export class MicrostreamClient {
   private handlers: { [event: string]: (data: any) => any } = {};
   private pendingRequests: { [requestId: string]: (response: any) => void } =
     {};
+  private timedOutRequests: {
+    [requestId: string]: {
+      allowLateResponseAfterTimeout: boolean;
+      onLateResponse?: (
+        error: CustomError | null,
+        response: {
+          response: any;
+          originalPayload: RequestPayload;
+        } | null
+      ) => void;
+      originalPayload: RequestPayload; // In case we use it in future
+    };
+  } = {};
   private logger: Logger; // Add logger instance
 
   /**
@@ -149,6 +162,8 @@ export class MicrostreamClient {
         `[${this.serviceName}] Received response for request ${id}`,
         response
       );
+
+      /*
       if (this.pendingRequests[id]) {
         this.pendingRequests[id](response);
         delete this.pendingRequests[id];
@@ -158,6 +173,60 @@ export class MicrostreamClient {
           response
         );
       }
+      */
+
+      // First check if the request is a Normal Pending Request
+      if (this.pendingRequests[id]) {
+        this.pendingRequests[id](response);
+        delete this.pendingRequests[id];
+        return;
+      }
+
+      // Else - Check if the request is in timedOutRequests
+      const timedOutRequest = this.timedOutRequests[id];
+
+      if (timedOutRequest) {
+        this.logger.warn(
+          `Received response for timed-out request ${id}`,
+          response
+        );
+
+        // Check if late responses are allowed
+        if (timedOutRequest.allowLateResponseAfterTimeout) {
+          // Invoke the onLateResponse callback if it exists
+          this.logger.info(
+            `Invoking onLateResponse callback for timed-out request ${id}`
+          );
+
+          if (timedOutRequest.onLateResponse) {
+            // If the response contains an error, pass it as the first argument
+            if (response.error) {
+              timedOutRequest.onLateResponse(
+                response.error, // Error object
+                null // No response
+              );
+            } else {
+              // If the response is successful, pass null as the first argument and the response as the second argument
+              timedOutRequest.onLateResponse(
+                null, // No error
+                {
+                  response,
+                  originalPayload: timedOutRequest.originalPayload,
+                }
+              );
+            }
+          }
+        }
+
+        // Clean up the timed-out request
+        delete this.timedOutRequests[id];
+      } else {
+        // Completely unexpected response
+        this.logger.warn(
+          `[${this.serviceName}] Received unexpected response for request ${id}`,
+          response
+        );
+      }
     });
 
     // Handle socket connection rejection error by the hub
@@ -205,15 +274,35 @@ export class MicrostreamClient {
 
   /**
    * Sends a request to another service through the Microstream Hub.
+   *
    * @param targetService - The name of the target service.
    * @param event - The event name to trigger on the target service.
    * @param data - Optional data to send with the request.
+   * @param allowLateResponseAfterTimeout - Whether to allow handling late responses after the request times out.
+   *                                         If `true`, the `onLateResponse` callback will be invoked if a late response is received.
+   *                                         Defaults to `false`.
+   * @param onLateResponse - Optional callback to handle late responses. This callback is invoked if:
+   *                         1. `allowLateResponseAfterTimeout` is `true`, and
+   *                         2. A late response is received after the request has timed out.
+   *                         The callback receives two arguments:
+   *                         - `error`: A `CustomError` object if the late response contains an error, or `null` if the response is successful.
+   *                         - `response`: An object containing the `response` and `originalPayload` if the response is successful, or `null` if there’s an error.
    * @returns A promise that resolves with the response from the target service.
+   *          If the request times out, the promise is rejected with a `CustomError`. For specific error codes, refer to the documentation.
+   *          If a late response is received and `allowLateResponseAfterTimeout` is `true`, the `onLateResponse` callback is invoked.
    */
   public sendRequest(
     targetService: string,
     event: string,
-    data?: any
+    data?: any,
+    allowLateResponseAfterTimeout: boolean = false,
+    onLateResponse?: (
+      error: CustomError | null,
+      response: {
+        response: any;
+        originalPayload: RequestPayload;
+      } | null
+    ) => void
   ): Promise<any> {
     return new Promise((resolve, reject) => {
       const requestId = nanoid();
@@ -224,6 +313,15 @@ export class MicrostreamClient {
 
       // Set a timeout for the request
       const timeoutHandler = setTimeout(() => {
+        // Only add the timed out request to timedOutRequests object/map if late responses are allowed
+        if (allowLateResponseAfterTimeout) {
+          this.timedOutRequests[requestId] = {
+            allowLateResponseAfterTimeout,
+            onLateResponse,
+            originalPayload: payload,
+          };
+        }
+
         // reject(new Error("Request timeout"));
         reject(
           /* new Error(
@@ -235,6 +333,8 @@ export class MicrostreamClient {
             { targetService, event, data }
           )
         );
+
+        // Delete from PendingRequests
         delete this.pendingRequests[requestId]; // Clean up
       }, this.timeout);