Chirp 3.0.7

Chirp - Flexible Messaging Library

Chirp is a flexible, provider-agnostic messaging library that simplifies publishing and consuming messages across various message brokers, including RabbitMQ, with planned support for Kafka, Redis, Azure Service Bus, Amazon SQS, NATS, and Google Pub/Sub.

Features

• Provider-agnostic API for messaging operations
• Unified interface for multiple message brokers
• Simple integration with dependency injection
• Automatic handler registration and subscription
• Strongly-typed configuration options for each message broker
• Message retries with configurable retry counts
• Dead letter exchange/queue support for failed messages
• Clean subscription management with in-memory event tracking
• Support for multiple message brokers:
  • RabbitMQ (✅ fully implemented)
  • Kafka (🚧 scaffolding in place)
  • Redis (🚧 scaffolding in place)
  • Azure Service Bus (🚧 scaffolding in place)
  • Amazon SQS (🚧 scaffolding in place)
  • NATS (🚧 scaffolding in place)
  • Google Pub/Sub (🚧 scaffolding in place)

Installation

dotnet add package Chirp

Getting Started

Configuration

Add the necessary configuration to your appsettings.json:

{
  "RMQ": {
    "Host": "localhost",
    "Port": 5672,
    "Username": "guest",
    "Password": "guest",
    "ExchangeName": "chirp_exchange",
    "ExchangeNameDLX": "chirp_dlx_exchange"
  }
}

Setting Up Dependencies

Register the required dependencies in your Program.cs or Startup.cs:

using Chirp.Infrastructure;
using Chirp.Infrastructure.EventBus;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

// Add Chirp services with RabbitMQ
services.AddChirp(options =>
{
    options.EventBusType = EventBusType.RabbitMQ;
    options.QueueName = "my_service_queue";
    options.RetryCount = 3;
    
    // Register event handlers - they'll be automatically subscribed
    options.AddConsumer<OrderCreatedEventHandler>();
    options.AddConsumer<PaymentReceivedEventHandler>();
});

Using Strongly Typed Options

Chirp supports strongly typed configuration options for each message broker implementation. This provides better IntelliSense and type safety:

RabbitMQ Configuration

using Chirp.Application.Common.EventBusOptions;
using Chirp.Infrastructure;

// Add Chirp services with RabbitMQ-specific options
services.AddChirp(options => 
{
    options.Host = "my-rabbitmq-server";
    options.Username = "my-username";
    options.Password = "my-password";
    options.QueueName = "my_service_queue";
    options.RetryCount = 3;
    options.ExchangeName = "my_custom_exchange";
    options.DeadLetterExchangeName = "my_custom_dlx";
    options.QueueDurable = true;
    options.PersistentMessages = true;
    
    // Register event handlers
    options.AddConsumer<OrderCreatedEventHandler>();
    options.AddConsumer<PaymentReceivedEventHandler>();
});

Future Provider Configuration Examples

The following configuration examples show how other providers will be configured once implemented:

Kafka Configuration (Scaffolding in place)

using Chirp.Application.Common.EventBusOptions;
using Chirp.Infrastructure;

// Note: Kafka implementation is not yet complete
services.AddChirp(options => 
{
    options.TopicName = "my-topic";
    options.ConsumerGroupId = "my-service-group";
    options.AutoCreateTopics = true;
    options.NumPartitions = 3;
    options.ReplicationFactor = 2;
    
    // Register event handlers
    options.AddConsumer<OrderCreatedEventHandler>();
});

Azure Service Bus Configuration (Scaffolding in place)

using Chirp.Application.Common.EventBusOptions;
using Chirp.Infrastructure;

// Note: Azure Service Bus implementation is not yet complete
services.AddChirp(options => 
{
    options.UseTopics = true;
    options.TopicName = "my-topic";
    options.SubscriptionName = "my-subscription";
    options.AutoCreateResources = true;
    
    // Register event handlers
    options.AddConsumer<OrderCreatedEventHandler>();
});

Creating Events

Create event classes that inherit from IntegrationEvent:

using Chirp.Domain.Common;

public record OrderCreatedEvent(int OrderId, string CustomerName, decimal Total) : IntegrationEvent;

Creating Event Handlers

Create handlers that implement IChirpIntegrationEventHandler<T>:

using Chirp.Application.Interfaces;

public class OrderCreatedEventHandler : IChirpIntegrationEventHandler<OrderCreatedEvent>
{
    public async Task Handle(OrderCreatedEvent @event)
    {
        // Process the event
        Console.WriteLine($"Order {@event.OrderId} created for {@event.CustomerName} with total {@event.Total}");
        await Task.CompletedTask;
    }
}

Publishing Events

public class OrderService
{
    private readonly IChirpEventBus _eventBus;

    public OrderService(IChirpEventBus eventBus)
    {
        _eventBus = eventBus;
    }

    public async Task CreateOrderAsync(int orderId, string customerName, decimal total)
    {
        // Create and publish the event
        var orderCreatedEvent = new OrderCreatedEvent(orderId, customerName, total);
        await _eventBus.PublishAsync(orderCreatedEvent);
    }
}

Advanced Usage

Using the Event Bus Factory

You can also use the EventBusFactory to create an instance of the event bus:

IChirpEventBus eventBus = EventBusFactory.Create(
    EventBusType.RabbitMQ,
    serviceProvider,
    configuration,
    "my_service_queue",
    retryCount: 5);

Working with Multiple Message Brokers

Chirp is designed to support multiple message broker implementations. Once additional providers are fully implemented, this will be useful in scenarios like:

• Migrating from one messaging system to another
• Creating hybrid systems with different messaging needs
• Publishing to multiple brokers for redundancy
• Consuming messages from different sources

Currently, the library has a fully implemented RabbitMQ provider. Other providers have scaffolding in place but require implementation of the core publish/subscribe functionality.

Planned Features for Multi-Broker Support

• Message routing based on event type
• Automatic failover between brokers
• Unified configuration for multiple brokers
• Message synchronization between different broker types

Supported Message Brokers

Note: Providers marked with 🚧 have interfaces, option classes, and event bus classes in place, but the PublishAsync and SubscribeAsync methods are not yet implemented and will throw NotImplementedException.

Contributing

Contributions are welcome! Feel free to submit a Pull Request. If you'd like to help implement one of the message broker providers, please check the existing scaffolding in the Infrastructure/EventBus directory.

License

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