ReliableCommandOutbox.Abstractions 1.3.0

ReliableCommandOutbox.Abstractions

ReliableCommandOutbox.Abstractions define los contratos públicos del patrón Transactional Command Outbox y su complemento Inbox (Idempotent Consumer).

Este paquete no contiene lógica, no contiene infraestructura y no ejecuta comandos.
Su objetivo es establecer un lenguaje común y estable entre productores, consumidores y el motor de procesamiento, respetando Clean Architecture.

Propósito

Este paquete existe para:

• Definir cómo se representa la intención de ejecutar un comando externo
• Definir cómo se despacha un comando fuera del microservicio
• Definir cómo se decide retry o terminación
• Definir cómo un consumidor implementa idempotencia (Inbox)
• Evitar dependencias entre dominio, infraestructura y transporte

Qué incluye

Command Outbox (lado productor)

Contratos para garantizar la ejecución confiable de comandos externos:

• Persistencia de la intención de ejecutar un comando
• Ejecución asíncrona
• Reintentos controlados
• Auditoría explícita del ciclo de vida

Inbox (lado consumidor)

Contratos para consumo idempotente de comandos:

• Deduplicación por commandId
• Protección contra reintentos
• Consumo transaccional seguro

Qué NO incluye

Este paquete NO:

• ❌ Ejecuta comandos
• ❌ Implementa persistencia
• ❌ Usa Entity Framework, Dapper o SQL
• ❌ Incluye schedulers (Quartz, cron, timers)
• ❌ Conoce transporte (HTTP, gRPC, colas)
• ❌ Implementa retry
• ❌ Contiene lógica de negocio

Este paquete define contratos, no comportamiento.

Principios de diseño

• Clean Architecture
• Ports & Adapters
• Separación productor / consumidor
• Semánticas explícitas
• Idempotencia consciente
• Sin dependencias de infraestructura
• Reutilizable vía NuGet
• Orientado a sistemas críticos

Contratos incluidos

Command Outbox

Inbox (Idempotent Consumer)

El Inbox no ejecuta lógica de negocio, solo protege su ejecución.

Modelo estructural (solo contratos)

classDiagram
    direction TB

    %% =========================
    %% COMMAND OUTBOX
    %% =========================
    class CommandOutboxRecord {
        <<abstract>>
        +Guid Id
        +string CommandName
        +string Target
        +string Payload
        +string BusinessKey
        +OutboxStatus Status
        +int RetryCount
        +int MaxRetries
        +DateTime NextAttemptAt
        +DateTime CreatedAt
        +DateTime? ProcessedAt
        +string? LastError
    }

    class OutboxStatus {
        <<enum>>
        Pending
        Processing
        Sent
        Failed
        Dead
    }

    class ICommandOutboxRepository~TRecord~ {
        <<interface>>
        +AddAsync(TRecord)
        +FetchNextAsync()
        +MarkProcessingAsync(Guid)
        +MarkAsSentAsync(Guid)
        +MarkAsFailedAsync(Guid, string)
        +MarkAsDeadAsync(Guid, string)
        +ScheduleRetryAsync(Guid, DateTime, string)
    }

    class ICommandDispatcher~TRecord~ {
        <<interface>>
        +DispatchAsync(TRecord)
    }

    class IRetryPolicy {
        <<interface>>
        +ShouldRetry(int, Exception?, OutboxExecutionResult?)
        +CalculateNextAttempt(int, DateTime)
    }

    class IClock {
        <<interface>>
        +UtcNow
    }

    class OutboxExecutionResult {
        +bool Success
        +bool Retryable
        +string? Error
    }

    %% =========================
    %% INBOX
    %% =========================
    class InboxRecord {
        <<abstract>>
        +Guid CommandId
        +string CommandName
        +string Source
        +DateTime ProcessedAt
    }

    class IInboxRepository~TRecord~ {
        <<interface>>
        +ExistsAsync(Guid)
        +AddAsync(TRecord)
    }

    %% =========================
    %% RELATIONSHIPS
    %% =========================
    CommandOutboxRecord --> OutboxStatus
    ICommandOutboxRepository~TRecord~ ..> CommandOutboxRecord
    ICommandDispatcher~TRecord~ ..> CommandOutboxRecord
    ICommandDispatcher~TRecord~ ..> OutboxExecutionResult
    IRetryPolicy ..> OutboxExecutionResult
    IInboxRepository~TRecord~ ..> InboxRecord