magarich/unisonmq repository overview

⁠UnisonMQ

UnisonMQ: High-Performance Message Broker for Modern Applications 🚀
UnisonMQ is a lightweight yet powerful message broker designed for the .NET ecosystem. It combines ease of use, high performance, and flexibility, supporting both basic messaging scenarios and complex microservice architectures. Thanks to its modular design and open protocol, UnisonMQ integrates seamlessly into any infrastructure. 🌐

⁠Core Protocol Operations 📡

1. PING → PONG 💡
   Connection health check. Clients send PING, and the server responds with PONG to confirm availability.

2. SUB <subject> [Id] 🔍
   Subscribe to a topic with wildcard support (* for single tokens, > for nested hierarchies). An optional Id allows managing multiple subscriptions within a single connection.
   Example:

   SUB orders.*.created 123
   

   Copy

3. UNSUB <Id> [MaxMessages] 🚫
   Unsubscribe using a subscription Id. If MaxMessages is specified, the broker will send up to that number of remaining messages before terminating the subscription.

4. PUB <subject> <length>\r\n<message> 📤
   Publish a message to a topic. The client specifies the data length (length) before sending the message body.
   Example:

   PUB alerts.system 11
   Hello World
   

   Copy

5. EXIT 🔌
   Gracefully terminate the connection. The server releases all client-associated resources.

⁠C# Client Libraries 📦

Integrate UnisonMQ into your projects using NuGet packages:

• Core Client:

  dotnet add package UnisonMQ.Client
  

  Copy
• Dependency Injection Support:

  dotnet add package UnisonMQ.DependencyInjection
  

  Copy

Example (Subscription and Publishing): 💻

using UnisonMQ.Client;

await using var client = new UnisonMqClientService(new UnisonMqConfiguration());

if (!client.ConnectAsync())
{
    Console.WriteLine("Failed to connect.");
    return;
}

client.Subscribe<SensorData>("sensors.*", msg =>
{
    switch (msg.Data)
    {
        case TemplateSensorData data:
            Console.WriteLine($"Received temperature from {msg.Subject}: {data.Value}");
            break;
        default:
            Console.WriteLine($"Received message from {msg.Subject}: {msg.Data}");
            break;
    }
});
client.Publish("sensors.temperature", new TemplateSensorData(Guid.NewGuid(), "24.5°C"));

abstract class SensorData(Guid id)
{
    public Guid Id { get; } = id;
}

class TemplateSensorData(Guid id, string value) : SensorData(id)
{
    public string Value { get; } = value;
}

⁠Monitoring Stack (Prometheus + Grafana) 📈

From the repository root:

docker compose up -d

• Prometheus 🎯 Collects metrics from UnisonMQ (port 5889).
• Grafana 📉 Prebuilt dashboards for analyzing load, latency, and system health.

⁠Telnet Compatibility ⌨️

UnisonMQ works with any TCP client, including Telnet:

telnet localhost 5888

Example Session: 💬

> ping
< PONG
> SUB alerts.* 1
< +OK  
> PUB alerts.system 5  
> READY  
< MSG alerts.system 1 5
< READY
< +OK
> exit
< +OK

⁠Prometheus Metrics 📊

UnisonMQ exposes detailed Prometheus metrics:

• Network Stats 🌐 Active connections, traffic volume.
• Operations ⚙️ PUB/SUB counts, processing times.
• Resource Usage 💻 CPU, memory, GC metrics.

# Example Query: Message publish rate 📤
rate(broker_messages_published_total[1m])

⁠Why Choose UnisonMQ? 🚀

• Ultra-low latency ⚡ with an optimized protocol.
• Wildcard support 🌟 for flexible topic management.
• Subscription control 🔑 via Id.
• Built-in monitoring 👁️ via Prometheus/Grafana.
• Seamless .NET integration 🔄.

Ideal for IoT 📶, microservices 🧩, and real-time systems ⏱️ where speed and reliability are critical!

⁠License 📜

UnisonMQ is released under the Apache License 2.0.
For full details, see the LICENSE⁠ file in the repository.

⁠Author 👨💻

• Magarich228⁠ - Creator and maintainer of UnisonMQ.

Happy messaging! 🎉