MicroStream Client SDK 🚀

The client library for Microstream, a lightweight, real-time communication library for microservices. Replace REST/gRPC with WebSockets for event-driven messaging. Simplifies inter-service communication with a request-response pattern and automatic reconnection.

Author: Arijit Banerjee
License: MIT

     

       

       

         

     

---

Table of Contents 📚

• Features ✨
• How Does It Work? 🌟
• Installation 🛠️
• Usage 🚀
• Configuration Options ⚙️
• Log Levels 📊
• Error Handling 🚨
• MicroStream Hub 🏢
• Author 👨‍💻
• Contributing 🤝
• License 📜

---

Features ✨

• 🔄 Real-time inter-service communication using WebSockets.
• ⚡ Synchronous request-response pattern without HTTP overhead.
• 🔍 Auto-discovery and connection management.
• 📊 Configurable logging for better observability.
• 🏢 Central WebSocket server for real-time communication between microservices (provided by the hub).
• 🔗 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.

---

How Does It Work? 🌟

MicroStream simplifies communication between microservices using a centralized hub-and-spoke architecture, also known as a star network. In this model, the MicroStream Hub acts as the central communication point, and your microservices, equipped with the MicroStream Client, connect to the Hub and communicate through it.

Here's how it works:

🌟 The Star Network Concept

Imagine a star:

• The center of the star is the MicroStream Hub.
• The points of the star are your microservices (each equipped with the MicroStream Client).

In this setup:

• The Hub acts as the central communication point.
• Services (nodes) connect to the Hub and communicate through it, not directly with each other.

🚀 How It Works in Practice

1. Service Registration:

   • Each microservice connects to the Hub using the MicroStream Client.
   • The Hub automatically detects and registers the service.

2. Request-Response Communication in Real-Time:

   • When Service A needs to talk to Service B, it sends a request to the Hub.
   • The Hub routes the request to Service B.
   • Service B processes the request and sends a response back through the Hub.
   • All communication happens in real-time over WebSockets, ensuring fast and reliable data exchange.

3. Auto-Discovery:

   • Once connected, the 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 to confirm they’re active.
   • If a service stops sending heartbeats, the 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:

• Easy Setup: Minimal configuration required to get started.
• Real-Time Request-Response Communication: Built on WebSockets for instant, reliable data exchange.
• Auto-Service-Management: Once connected, the Hub keeps track of all services, simplifying network management.
• 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.

---

Installation 🛠️

npm install microstream-client

---

Usage 🚀

const { MicrostreamClient } = require("microstream-client");

// Create a new MicrostreamClient instance with the necessary configuration
const client = new MicrostreamClient({
  hubUrl: "http://localhost:3000", // URL of the Microstream Hub
  serviceName: "auth-service", // Name of your service - it has to be unique
  logLevel: "debug", // Enable debug logs
});

// Register a handler for incoming requests for event 'authenticate'
client.onRequest("authenticate", (data) => {
  console.log("Received authentication request:", data);
  return { success: true, token: "sample-token" }; // Respond to the request
});

// Register another handler for incoming request for another event
client.onRequest("another-event", (data) => {
  console.log("Received another-event request:", data);
  return { success: true, data: "sample-data" }; // Respond to the request
});

//  Send a request to 'jwt-service' and handle the response
try {
  const response = await client.sendRequest("jwt-service", "generate_jwt", {
    userID: 123,
  });
  console.log("Received response:", response);
} catch (error) {
  console.log("Error:", error.message);
}

//  Send a request to 'profile-service' and handle the response
try {
  const response = await client.sendRequest(
    "profile-service",
    "fetch-profile-by-userID",
    { userID: 123 }
  );
  console.log("Received response:", response);
} 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 👨🏻‍🏫

1. Configuration: The MicrostreamClient is configured with the URL of the Microstream Hub, the unique registration name of your service, and the log level.
2. Registering Handlers: The onRequest method is used to register a handler for incoming requests. In this example, handlers respond to "authenticate" and "another-event" events.
   • Parameters:
     • 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.
  • 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 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 or the Error Handling Section

---

Configuration Options ⚙️

MicrostreamClientOptions

• hubUrl: URL of the Microstream Hub.
• serviceName: A Unique Service Registation Name of the service connecting to the hub.
• timeout: Timeout for requests in milliseconds (default: 5000).
• heartbeatInterval: Interval for sending heartbeats in milliseconds (default: 5000).
• logLevel: Log level for the client (default: "info").

Important Notes 📝

• Service names must be unique across your entire system. The Hub will reject any connection attempts from services trying to register with an already registered name.
• If your service attempts to connect with a name that's already registered:
  • The connection will be rejected
  • An error will be thrown with code DUPLICATE_SERVICE_REGISTRATION
  • The process will automatically terminate to prevent conflicts

---

Log Levels 📊

• debug: Log everything (useful for development).
• info: Log info, warnings, and errors.
• warn: Log warnings and errors.
• error: Log only errors.
• silent: Disable all logs.

---

Error Handling 🚨

MicroStream Client implements standardized error handling using a CustomError class. All errors follow a consistent structure to help with error management and debugging.

Error Structure 📋

{
  code: string;        // Error identification code
  message: string;     // Human readable error message
  errorData?: any;     // Optional contextual data
}

Standard Error Codes 📝

The Client may throw the following error types:

Error Code	Description
INTERNAL_SERVER_ERROR	Occurs when an event handler fails during execution
EVENT_NOT_FOUND	Thrown when no handler is registered for the requested event
REQUEST_TIMEOUT	Occurs when a request exceeds the configured timeout period
DUPLICATE_SERVICE_REGISTRATION	Thrown when attempting to register a service name that's already in use
TARGET_SERVICE_NOT_FOUND	Thrown when attempting to send a request to a service that isn't registered with the hub

Usage Examples 💡

// Example: Handling request errors
try {
  const response = await client.sendRequest("auth-service", "validate-token", {
    token: "xyz",
  });
} catch (error) {
  switch (error.code) {
    case "REQUEST_TIMEOUT":
      console.error(`Request timed out: ${error.message}`);
      console.log("Request details:", error.errorData);
      break;
    case "EVENT_NOT_FOUND":
      console.error(`Event handler not found: ${error.message}`);
      break;
    case "INTERNAL_SERVER_ERROR":
      console.error(`Service error: ${error.message}`);
      console.log("Error context:", error.errorData);
      break;
  }
}

Error Handling Best Practices 🎯

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
6. Use allowLateResponseAfterTimeout and onLateResponse to handle late responses gracefully

Common Error Scenarios 🔄

1. Timeout Errors

   • Occurs when target service doesn't respond within timeout period
   • Default timeout: 5000ms (configurable via options)
   • Includes target service and event details in errorData

2. Event Not Found

   • Happens when requesting non-existent event handlers
   • Includes event name and service details in errorData
   • Check event name and target service configuration

3. Internal Server Errors

   • Triggered by exceptions in event handlers
   • Contains original error details in errorData
   • 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

---

MicroStream Hub 🏢

Here is the central hub for easy integration with the MicroStream Client SDK.

• MicroStream Hub on GitHub
• MicroStream Hub Documentation

---

Author 👨‍💻

Author: Arijit Banerjee

About: Full Stack Web Developer | Cyber Security Enthusiast | Actor

Social Media:   Instagram   LinkedIn   GitHub   Website

Email: arijit.codes@gmail.com

---

Contributing 🤝

We welcome contributions! Please see our CONTRIBUTING.md for guidelines on how to contribute to this project.

---

License 📜

This project is licensed under the MIT License. See the LICENSE file for details.

---