Cosmos.EventDriven.Abstractions 2.1.0

Cosmos.EventDriven.Abstractions

Abstracciones fundamentales para implementar Event Driven Architecture (EDA) en .NET 10.

Descripción

Este paquete proporciona las interfaces base necesarias para construir aplicaciones basadas en arquitecturas orientadas a eventos. Define contratos claros para la publicación de eventos públicos (inter-servicio) y eventos privados (intra-servicio).

Características

• IPublicEvent: Marcador para eventos publicados a servicios externos vía broker (RabbitMQ, Azure Service Bus, etc.)
• IPrivateEvent: Marcador para eventos publicados dentro del mismo bounded context
• IPublicEventSender: Interfaz para publicar IPublicEvent de forma asíncrona
• IPrivateEventSender: Interfaz para publicar IPrivateEvent de forma asíncrona
• IPrivateEventHandlerAsync<TEvent>: Contrato del patrón event handler para eventos privados — garantiza la firma que Wolverine descubre por convención y hace el handler testeable in-memory
• IPrivateEventRouter: Invoca inline los handlers de un evento privado dentro del mismo servicio (la llamada espera a que terminen y las excepciones se propagan al caller)
• PublishOptions: Opciones del sobre (GroupId para orden FIFO y Headers arbitrarios) para publicar sin explotar la matriz de sobrecargas
• Sin dependencias de implementación concreta

Instalación

dotnet add package Cosmos.EventDriven.Abstractions

Uso

Definir un Evento Público (inter-servicio)

using Cosmos.EventDriven.Abstractions;

public record UserRegistered(
    string UserId,
    string Email,
    DateTime RegisteredAt
) : IPublicEvent;

Definir un Evento Privado (intra-servicio)

using Cosmos.EventDriven.Abstractions;

public record UserProfileUpdated(
    string UserId,
    string NewEmail
) : IPrivateEvent;

Publicar un Evento Público

public class UserService
{
    private readonly IPublicEventSender _publicEventSender;

    public UserService(IPublicEventSender publicEventSender)
    {
        _publicEventSender = publicEventSender;
    }

    public async Task RegisterUser(string userId, string email)
    {
        // Lógica de negocio...

        var @event = new UserRegistered(userId, email, DateTime.UtcNow);
        await _publicEventSender.PublishAsync(@event);
    }
}

Publicar Eventos Privados

public class UserService
{
    private readonly IPrivateEventSender _privateEventSender;

    public UserService(IPrivateEventSender privateEventSender)
    {
        _privateEventSender = privateEventSender;
    }

    public async Task UpdateProfile(string userId, string newEmail)
    {
        // Lógica de negocio...

        var @event = new UserProfileUpdated(userId, newEmail);
        await _privateEventSender.PublishAsync(@event);
    }
}

Manejar un evento privado (patrón event handler)

Los eventos privados son intra-servicio: sus handlers viven en el mismo bounded context y no pasan por un anticorruption layer. IPrivateEventHandlerAsync<TEvent> fija el contrato del handler (y lo hace testeable con PrivateEventHandlerAsyncTest de Cosmos.EventSourcing.Testing.Utilities); IPrivateEventRouter lo invoca inline cuando el caller necesita que el manejo ocurra dentro de la misma operación:

using Cosmos.EventDriven.Abstractions;

// El nombre de la clase debe terminar en "Handler" para que Wolverine la descubra por convención.
public class UserProfileUpdatedHandler : IPrivateEventHandlerAsync<UserProfileUpdated>
{
    public Task HandleAsync(UserProfileUpdated @event, CancellationToken cancellationToken)
    {
        // Lógica intra-servicio...
        return Task.CompletedTask;
    }
}

public class UserService(IPrivateEventRouter router)
{
    public async Task UpdateProfile(string userId, string newEmail, CancellationToken ct)
    {
        // Invoca inline los handlers del evento y espera a que terminen.
        await router.InvokeAsync(new UserProfileUpdated(userId, newEmail), ct);
    }
}

IPrivateEventSender vs IPrivateEventRouter: el sender publica (fire-and-forget durable, vía la ruta configurada al broker); el router invoca inline (la operación espera el resultado y las excepciones del handler se propagan al caller).

Publicar con opciones del sobre (headers / clave de enrutamiento)

Cuando el destinatario debe enrutarse por una clave de enrutamiento (por ejemplo, un correlation filter de Azure Service Bus que solo evalúa las application properties del mensaje, no su body), estampa esa clave como un header arbitrario del sobre vía PublishOptions.Headers:

using Cosmos.EventDriven.Abstractions;

var options = new PublishOptions
{
    Headers = new Dictionary<string, string> { ["applicationBundleId"] = applicationBundleId },
};

await _publicEventSender.PublishAsync(options, @event);

GroupId (orden FIFO / SessionId) y Headers (clave de enrutamiento) son ortogonales: pueden usarse por separado o juntos en el mismo PublishOptions, sin conflacionarse.

var options = new PublishOptions { GroupId = "cuenta-123", Headers = headers };

En Azure Service Bus, los Headers se materializan como application properties del mensaje (matcheables por un CorrelationFilter de igualdad); en RabbitMQ, como headers.

Distinción IPublicEvent vs IPrivateEvent

Implementaciones Concretas

Para implementaciones listas para usar con Wolverine, consulta:

• Cosmos.EventDriven.CritterStack — implementaciones base con Wolverine
• Cosmos.EventDriven.CritterStack.RabbitMQ — extensiones para RabbitMQ
• Cosmos.EventDriven.CritterStack.AzureServiceBus — extensiones para Azure Service Bus

Requisitos

• .NET 10.0 o superior

Licencia

Copyright © Cosmos. Todos los derechos reservados.