EAC.Infrastructure.Messaging 0.1.0-rc.4

EAC.Infrastructure.Messaging

Desde 2026-10-09, Native AOT queda fuera del alcance por decisión del usuario. No se declara compatibilidad ni se exige su gate. Las referencias históricas no constituyen soporte vigente; build y tests ordinarios siguen siendo obligatorios.

La capacidad Inbox es opcional y permanece deshabilitada sin Inbox:Enabled=true o UseInbox. Para consumo directo al menos una vez, UseDirectConsumer registra validación de catálogo, deserialización JSON explícita y despacho sin IInboxStore; el handler debe ser idempotente y devolver Committed solo tras persistir su efecto.

NuGet neutral al broker para contratos lógicos, publicación Outbox y consumo Inbox durable. Las trece reglas propias del núcleo y MSG-010 están cerrados con CI local, Tekton y publicación RC. Kafka conserva implementación, reglas, pruebas reales y ciclo de release independientes.

Instalación y composición

<PackageReference Include="EAC.Infrastructure.Messaging" Version="0.1.0-rc.2" />

Referenciar el paquete solo incorpora el núcleo. No registra stores, transportes, dispatchers ni workers. Cada aplicación declara sus contratos con metadata JSON generada y activa únicamente las capacidades que necesita:

services.AddEacMessaging(configuration, messaging => messaging
    .Event<OrderIssued>(
        "sample.order.issued",
        1,
        "sample.order.events",
        ApplicationJsonContext.Default.OrderIssued)
    .UseOutbox());

Combinaciones admitidas:

• núcleo: AddEacMessaging(configuration, messaging => messaging.Event(...));
• Outbox: añadir UseOutbox() o configurar Outbox:Enabled=true;
• Inbox: añadir UseInbox() o configurar Inbox:Enabled=true;
• publisher hospedado: añadir UseOutboxPublisher() o configurar Outbox:Publisher:Enabled=true;
• salud operacional Outbox: añadir UseOutboxOperationalHealth() o configurar Outbox:Health:Enabled=true;
• ambas: activar las dos capacidades.

Outbox exige que el adaptador registre IOutboxStore e IMessageTransport. Inbox exige IInboxStore e IIncomingMessageDispatcher. Messaging nunca aporta sustitutos silenciosos.

Cada servicio declara obligatoriamente su identidad lógica bajo Eac:Messaging:Service:Name. AddEacServiceMessageChannels(configuration) deriva exactamente <servicio>.events para sus eventos de integración y <servicio>.commands para comandos remotos que recibe. No existe una identidad predeterminada: ausencia, un sufijo de canal o una identidad con segmentos vacíos hacen fallar el arranque. El catálogo impide cruzar tipos de mensaje entre ambos canales. Retry y dead-letter son mecanismos operativos, no canales funcionales adicionales.

Los eventos salientes siempre usan la instancia Events propia. Los comandos entrantes se consumen exclusivamente desde Commands propio y se despachan por su identidad contractual. Un comando saliente debe declarar un RemoteCommandDestination con la identidad lógica del servicio destino; el paquete deriva <destino>.commands y el adaptador resuelve su topic físico. No se deduce un destino desde el nombre CLR ni desde el tipo de comando.

Configuración

{
  "Eac": {
    "Messaging": {
      "Service": {
        "Name": "sample.orders"
      },
      "Outbox": {
        "Enabled": true,
        "BatchSize": 100,
        "LeaseDuration": "00:01:00",
        "MaxAttempts": 5,
        "BaseRetryDelay": "00:00:01",
        "MaxRetryDelay": "00:01:00"
      },
      "Inbox": {
        "Enabled": false,
        "Consumer": "orders",
        "LeaseDuration": "00:01:00",
        "MaxPayloadBytes": 1048576
      },
      "Telemetry": {
        "AllowedBaggageKeys": [ "tenant.id" ]
      }
    }
  }
}

Las variables de entorno siguen el binding nativo, por ejemplo Eac__Messaging__Outbox__Enabled=true, Eac__Messaging__Inbox__Consumer=orders y Eac__Messaging__Telemetry__AllowedBaggageKeys__0=tenant.id.

La configuración programática se aplica después de IConfiguration y por ello tiene precedencia:

services.AddEacMessaging(configuration, messaging => messaging
    .UseOutbox(options => options.BatchSize = 50)
    .DisableInbox()
    .ConfigureTelemetry(options => options.AllowedBaggageKeys = ["tenant.id"]));

Una capacidad deshabilitada no valida ni exige sus dependencias. Una capacidad habilitada con valores inválidos falla mediante Options validation al iniciar o resolver sus opciones. Endpoints, credenciales y connection strings pertenecen al adaptador físico y deben proceder de variables, workload identity o un proveedor de secretos; no se colocan en esta sección ni se registran en telemetría.

Uso durable

En el código fuente de desarrollo, IntegrationEventOutbox.Create convierte un IntegrationEventEnvelope<T> en OutboxMessage con metadata JSON explícita. Evita repetir identidad, versión, tiempos, correlación y clave de orden entre ambos objetos. El servicio conserva el payload y su proyección desde Domain; la factory no guarda ni publica y no cambia el límite transaccional. IntegrationEventJsonMetadata.Create permite declarar nombres de wire existentes sin modificar el contexto generado compartido. Véase la guía de consumo. Esta API aditiva se consume por ProjectReference; no se ha publicado.

El adaptador Persistence incorpora el mensaje a la transacción local mediante IOutboxStore.AddAsync. OutboxPublisher reclama lotes acotados y publica mediante el IMessageTransport registrado. En entrada, IncomingMessageProcessor valida el contrato y despacha; UseInbox añade deduplicación con IInboxStore, mientras UseDirectConsumer exige un handler idempotente sin ese almacén. Solo devuelve Acknowledge tras obtener un resultado durable.

La recuperación de un fallo permanente es una operación explícita de operador mediante IOutboxRecoveryStore.RequeueFailedAsync. Selecciona identificadores concretos y se aplica de forma atómica: si falta un mensaje o alguno no está en Failed, no cambia ninguno. Una recuperación válida conserva el contador de intentos y la metadata de orden, limpia el estado terminal y cualquier lease, y programa un intento inmediato. No existe limpieza automática, purga de fallos ni reintento infinito.

El publisher hospedado es opcional y crea un scope por ciclo. La comprobación operacional del Outbox también es opcional, requiere el monitor del adaptador de persistencia y solo expone backlog agregado y antigüedad; la conectividad del broker pertenece a su adaptador físico.

Los mensajes pueden capturar MessagingTraceContext.CaptureCurrent(allowedKeys). El paquete continúa únicamente Trace Context W3C válido y baggage explícitamente permitido. La fuente de actividades y métricas es EAC.Infrastructure.Messaging; nunca agrega payloads, tokens, credenciales ni headers completos.

El host selecciona Eac:Observability:Tracing:DetailLevel=Boundary o Detailed. El nivel detallado añade el ciclo independiente messaging.outbox.batch y el despacho Inbox, sin convertir el lote en padre artificial de una publicación que continúa su traceparent persistido.

Ese meter publica eac.messaging.operations, eac.messaging.operation.duration en segundos y eac.outbox.transitions. La transición Outbox se registra después de confirmar el estado durable como confirmed, retry o failed; las dimensiones se limitan a operation, result y message.kind.

Los contratos canónicos portables se encuentran en contracts; JSON Schema y AsyncAPI son la fuente contractual, no los nombres CLR.

Candidato local

./scripts/ci.sh valida y prueba el componente sin empaquetarlo. Tras esa compilación, ./scripts/release-candidate.sh genera un candidato local sin credenciales ni publicación: .nupkg, .snupkg, SBOM SPDX 2.2, hashes, inspección estructural, smoke consumidor aislado y evidencia ligada al HEAD. Los resultados quedan bajo artifacts/, excluidos del repositorio.

La CI remota usa exclusivamente el binding mínimo .tekton/continuous-integration.yaml, fijado al perfil eac-nuget-ci de Pipeline Catalog v0.4.4. Las Pipelines y Tasks reutilizables no se copian en este repositorio y la CI de ramas no recibe credenciales de publicación.

• Índice documental
• Guía de consumo y configuración
• Plan de implementación
• Diseño
• Arquitectura transversal