https://github.com/arijitcodes/microstream-client
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. [ NPM 📦 ]
https://github.com/arijitcodes/microstream-client
communication ipc message-broker microservices microstream microstream-client nodejs real-time service-communication service-discovery service-mesh socket-io typescript
Last synced: 12 days ago
JSON representation
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. [ NPM 📦 ]
- Host: GitHub
- URL: https://github.com/arijitcodes/microstream-client
- Owner: arijitcodes
- License: mit
- Created: 2025-02-27T18:30:57.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-03-27T12:20:36.000Z (about 2 months ago)
- Last Synced: 2025-04-28T07:50:27.336Z (27 days ago)
- Topics: communication, ipc, message-broker, microservices, microstream, microstream-client, nodejs, real-time, service-communication, service-discovery, service-mesh, socket-io, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/microstream-client
- Size: 838 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](#author)
License: [MIT](./LICENSE)
[](https://www.npmjs.com/package/microstream-client)
[](https://github.com/arijitcodes/microstream-client)
[](https://github.com/arijitcodes/microstream-client/blob/main/LICENSE.md)
[](https://www.npmjs.com/package/microstream-client)
[](https://www.npmjs.com/package/microstream-client)
[](https://www.npmjs.com/package/microstream-client)
[](https://github.com/arijitcodes/microstream-client/blob/main/LICENSE)
[](https://github.com/arijitcodes/microstream-client)
[](https://github.com/arijitcodes/microstream-client)
[](https://github.com/arijitcodes/microstream-client/commits/main)
[](https://github.com/arijitcodes/microstream-client/graphs/contributors)
[](https://github.com/arijitcodes/microstream-client/pulls)
[](https://github.com/arijitcodes/microstream-client/issues)
[](https://github.com/arijitcodes/microstream-client)
[](https://github.com/arijitcodes/microstream-client)
[](https://github.com/semantic-release/semantic-release)
[](https://commitizen.github.io/cz-cli/)
[](https://www.conventionalcommits.org)
## Table of Contents 📚
- [Features ✨](#features-)
- [How Does It Work? 🌟](#how-does-it-work-)
- [Installation 🛠️](#installation-)
- [Usage 🚀](#usage-)
- [Configuration Options ⚙️](#configuration-options-)
- [Log Levels 📊](#log-levels-)
- [Error Handling 🚨](#error-handling-)
- [MicroStream Hub 🏢](#microstream-hub-)
- [Author 👨💻](#author-)
- [Contributing 🤝](#contributing-)
- [License 📜](#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](https://github.com/arijitcodes/microstream-hub)** acts as the central communication point, and your microservices, equipped with the **[MicroStream Client](https://github.com/arijitcodes/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](https://github.com/arijitcodes/microstream-hub)**.
- The **points of the star** are your **microservices** (each equipped with the **[MicroStream Client](https://github.com/arijitcodes/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](https://github.com/arijitcodes/microstream-client)**.
- The **[Hub](https://github.com/arijitcodes/microstream-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](https://github.com/arijitcodes/microstream-hub)**.
- The **[Hub](https://github.com/arijitcodes/microstream-hub)** routes the request to **Service B**.
- **Service B** processes the request and sends a response back through the **[Hub](https://github.com/arijitcodes/microstream-hub)**.
- All communication happens in **real-time** over WebSockets, ensuring fast and reliable data exchange.
3. **Auto-Discovery**:
- 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:
- **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](https://github.com/arijitcodes/microstream-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 🛠️
```bash
npm install microstream-client
```
## Usage 🚀
```javascript
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`](#microstreamclientoptions) is configured with the URL of the [Microstream Hub](#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**](#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-)
## 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-levels-): 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](https://github.com/arijitcodes/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 📋
```typescript
{
code: string; // Error identification code
message: string; // Human readable error message
errorData?: any; // Optional contextual data
}
```
### Standard Error Codes 📝
The **[Client](https://github.com/arijitcodes/microstream-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 💡
```javascript
// 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](https://github.com/arijitcodes/microstream-hub)
- [MicroStream Hub Documentation](https://github.com/arijitcodes/microstream-hub#readme)
## Author 👨💻
Author: [Arijit Banerjee](https://www.github.com/arijitcodes)
About: Full Stack Web Developer | Cyber Security Enthusiast | Actor
Social Media:
[ Instagram](https://www.instagram.com/arijit.codes)
[ LinkedIn](https://www.linkedin.com/in/arijitban)
[ GitHub](https://github.com/arijitcodes)
[ Website](https://iamarijit.dev)
Email: [email protected]
## Contributing 🤝
We welcome contributions! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute to this project.
## License 📜
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.