Outbox Messages

Este documento descreve todas as operações disponíveis para o gerenciamento de Outbox Messages e suas configurações, seguindo os padrões de Domain-Driven Design (DDD) e Command Query Responsibility Segregation (CQRS).

Índice

• OutboxMessages (Mensagens do Outbox)
• OutboxMessageConfigurations (Configurações)

---

OutboxMessages (Mensagens do Outbox)

Queries (Consultas)

1. Listar Tipos de Eventos (GetEventTypes)

Contrato: GetEventTypesQuery

Campos Necessários: Nenhum

Retorno: GetEventTypesResponse

Campo	Tipo	Descrição
EventTypes	IReadOnlyList\<string>	Lista de tipos de eventos distintos

Endpoint: GET /v1/outbox-messages/event-types

Autenticação: Requer [AdminAuthorize]

---

2. Buscar Mensagem por ID (GetOutboxMessageById)

Contrato: GetOutboxMessageByIdQuery

Campos Necessários:

• Id (Guid, obrigatório) - Identificador da mensagem

Retorno: GetOutboxMessageByIdResponse

Campo	Tipo	Descrição
Id	Guid	Identificador único da mensagem
EventType	string	Tipo do evento
Topic	string	Tópico de destino
Payload	string	Conteúdo da mensagem (JSON)
Headers	string	Headers da mensagem (JSON)
Status	int	Status da mensagem (enum)
StatusDescription	string	Descrição do status
CreatedAt	DateTime	Data de criação
ProcessedAt	DateTime?	Data de processamento
RetryCount	int	Número de tentativas
ErrorMessage	string?	Mensagem de erro (se houver)
LastRetryAt	DateTime?	Data da última tentativa
LockedBy	string?	Identificador do processo que bloqueou
LockedUntil	DateTime?	Data até quando está bloqueada
PartitionKey	int	Chave de partição
ManualReprocessCount	int	Número de reprocessamentos manuais

Endpoint: GET /v1/outbox-messages/{id}

Autenticação: Requer [AdminAuthorize]

---

3. Buscar Mensagens com Filtros (GetOutboxMessages)

Contrato: GetOutboxMessagesQuery

Campos Necessários:

• Status (int, opcional) - Filtrar por status
• EventType (string, opcional) - Filtrar por tipo de evento
• PageNumber (int, opcional) - Número da página (padrão: 1)
• PageSize (int, opcional) - Tamanho da página (padrão: 50)

Retorno: GetOutboxMessagesResponse (PagingResult\<GetOutboxMessagesResponseItem>)

Campo	Tipo	Descrição
Items	List\<GetOutboxMessagesResponseItem>	Lista de mensagens
TotalCount	int	Total de registros
PageNumber	int	Página atual
PageSize	int	Tamanho da página

Endpoint: GET /v1/outbox-messages/search

Autenticação: Requer [AdminAuthorize]

---

Commands (Comandos)

4. Reprocessar Mensagem (ReprocessOutboxMessage)

Contrato: ReprocessOutboxMessageCommand

Campos Necessários:

• MessageId (Guid, obrigatório) - Identificador da mensagem a reprocessar

Validações:

• MessageId: Mensagem deve existir

Retorno: ReprocessOutboxMessageResponse

Campo	Tipo	Descrição
Success	bool	Indica se a operação foi bem-sucedida
Message	string	Mensagem descritiva do resultado

Endpoint: POST /v1/outbox-messages/{messageId}/reprocess

Autenticação: Requer [AdminAuthorize]

Regras de Negócio:

• Altera o status da mensagem para Pending
• Incrementa o contador de reprocessamentos manuais
• Limpa o erro anterior

---

5. Reprocessar Mensagens com Falha (ReprocessFailedMessages)

Contrato: ReprocessFailedMessagesCommand

Campos Necessários:

• EventType (string, opcional) - Filtrar por tipo de evento
• MaxRetries (int, opcional) - Reprocessar apenas mensagens com retry count menor que este valor

Retorno: ReprocessFailedMessagesResponse

Campo	Tipo	Descrição
Success	bool	Indica se a operação foi bem-sucedida
ReprocessedCount	int	Número de mensagens reprocessadas
Message	string	Mensagem descritiva do resultado

Endpoint: POST /v1/outbox-messages/reprocess-failed

Autenticação: Requer [AdminAuthorize]

Regras de Negócio:

• Reprocessa todas as mensagens com status Failed
• Se EventType for fornecido, filtra apenas por esse tipo
• Se MaxRetries for fornecido, ignora mensagens com muitas tentativas

---

OutboxMessageConfigurations (Configurações)

Commands (Comandos)

1. Pausar Evento (PauseOutboxEvent)

Contrato: PauseOutboxEventCommand

Campos Necessários:

• EventType (string, obrigatório) - Tipo do evento a ser pausado (ex: "OrderCreatedEvent")
• Reason (string, obrigatório) - Motivo da pausa
• PauseUntil (DateTime, opcional) - Data/hora até quando pausar (se null, pausa indefinidamente)

Validações:

• EventType: Não pode ser vazio
• Reason: Não pode ser vazio

Retorno: PauseOutboxEventResponse

Campo	Tipo	Descrição
Success	bool	Indica se a operação foi bem-sucedida
Message	string	Mensagem descritiva do resultado
ConfigurationId	Guid?	ID da configuração criada/atualizada
EventType	string	Tipo do evento pausado
PausedUntil	DateTime?	Data até quando está pausado

Endpoint: POST /v1/outbox-messages/configurations/pause

Autenticação: Requer [AdminAuthorize]

Regras de Negócio:

• Cria ou atualiza a configuração do evento
• Novos eventos criados durante a pausa serão salvos com status Paused
• Eventos já pendentes não são afetados

---

2. Resumir Evento (ResumeOutboxEvent)

Contrato: ResumeOutboxEventCommand

Campos Necessários:

• EventType (string, obrigatório) - Tipo do evento a ser resumido

Validações:

• EventType: Não pode ser vazio
• Configuração deve existir

Retorno: ResumeOutboxEventResponse

Campo	Tipo	Descrição
Success	bool	Indica se a operação foi bem-sucedida
Message	string	Mensagem descritiva do resultado
EventType	string	Tipo do evento resumido
ResumedMessagesCount	int	Número de mensagens que foram despausadas

Endpoint: POST /v1/outbox-messages/configurations/{eventType}/resume

Autenticação: Requer [AdminAuthorize]

Regras de Negócio:

• Remove a pausa da configuração do evento
• Altera o status de todas as mensagens pausadas deste tipo para Pending
• Retorna o número de mensagens que foram reativadas

---

Status das Mensagens

Valor	Nome	Descrição
0	Pending	Aguardando processamento
1	Processing	Em processamento
2	Processed	Processada com sucesso
3	Failed	Falha no processamento
4	Paused	Pausada manualmente

---

Uso via SDK

Interface IOutboxMessageService

public interface IOutboxMessageService
{
    Task<GetOutboxMessageByIdResponse> GetOutboxMessageByIdAsync(Guid id, CancellationToken cancellationToken = default);
    Task<GetOutboxMessagesResponse> GetOutboxMessagesAsync(GetOutboxMessagesRequest request, CancellationToken cancellationToken = default);
    Task<GetEventTypesResponse> GetEventTypesAsync(CancellationToken cancellationToken = default);
    Task<ReprocessOutboxMessageResponse> ReprocessMessageAsync(Guid messageId, CancellationToken cancellationToken = default);
    Task<ReprocessFailedMessagesResponse> ReprocessFailedMessagesAsync(string? eventType, int? maxRetries, CancellationToken cancellationToken = default);
    Task<PauseOutboxEventResponse> PauseEventAsync(PauseOutboxEventRequest request, CancellationToken cancellationToken = default);
    Task<ResumeOutboxEventResponse> ResumeEventAsync(string eventType, CancellationToken cancellationToken = default);
}

Exemplos de Uso

Listar Tipos de Eventos

var eventTypes = await _outboxService.GetEventTypesAsync();
foreach (var eventType in eventTypes.EventTypes)
{
    Console.WriteLine($"Tipo de evento: {eventType}");
}

Buscar Mensagens com Filtros

var request = new GetOutboxMessagesRequest
{
    Status = 3, // Failed
    EventType = "OrderCreatedEvent",
    PageNumber = 1,
    PageSize = 50
};

var messages = await _outboxService.GetOutboxMessagesAsync(request);
Console.WriteLine($"Total de mensagens: {messages.TotalCount}");

Reprocessar Mensagem Específica

var result = await _outboxService.ReprocessMessageAsync(messageId);
if (result.Success)
{
    Console.WriteLine("Mensagem reprocessada com sucesso!");
}

Reprocessar Todas as Mensagens com Falha

var result = await _outboxService.ReprocessFailedMessagesAsync(
    eventType: "OrderCreatedEvent",
    maxRetries: 5
);

Console.WriteLine($"{result.ReprocessedCount} mensagens reprocessadas");

Pausar um Tipo de Evento

var request = new PauseOutboxEventRequest
{
    EventType = "OrderCreatedEvent",
    Reason = "Manutenção programada",
    PauseUntil = DateTime.UtcNow.AddHours(2)
};

var result = await _outboxService.PauseEventAsync(request);
if (result.Success)
{
    Console.WriteLine($"Evento pausado até: {result.PausedUntil}");
}

Resumir um Tipo de Evento

var result = await _outboxService.ResumeEventAsync("OrderCreatedEvent");
Console.WriteLine($"{result.ResumedMessagesCount} mensagens foram reativadas");

---

Referências

• Outbox Pattern