@cargolift-cdi/lib-rabbitmq

Utilitários para publicação de mensagens RabbitMQ com confirmação (publisher confirms), enriquecimento de envelope e convenções de integração.

Principais Componentes

• RabbitMQPublisherService: camada de baixo nível (confirmação, timeout, backpressure, headers contextuais).
• IntegrationEventPublisher: fachada de alto nível para eventos de integração HTTP → RabbitMQ.
• publishToDlqAndAck: envia mensagem original (enriquecida) para DLQ e faz ack.
• RabbitMQConnectionManager: reutiliza conexão evitando overhead de conexão por mensagem.
• RabbitTopologyManager: criação padronizada de exchanges (AE, DLX, retries) e filas dinâmicas por sistema.

Exemplo Rápido (NestJS)

Módulo

import { Module } from '@nestjs/common';
import { RabbitmqModule } from '@cargolift-cdi/lib-rabbitmq';
import { DemoService } from './demo.service';

@Module({
	imports: [RabbitmqModule],
	providers: [DemoService],
	exports: [DemoService]
})
export class DemoModule {}

Uso em service/controller

@Injectable()
export class DemoService {
	constructor(private readonly integration: IntegrationEventPublisher) {}

	async send(data: any) {
		const meta = await this.integration.publish({
			routingKey: 'integration.erp.demo',
			payload: data,
			raw: { returnMeta: true }
		});
		return meta; // opcional
	}
}

Publicação em Controller

@Post('demo')
async demo(@Req() req: Request) {
	await this.integration.publish({
		routingKey: 'integration.erp.demo',
		req,
		envelope: { event: 'demo', action: 'CREATE' }
	});
	return { ok: true };
}

Metadados de Publicação

RabbitMQPublisherService.publish aceita returnMeta: true em opts retornando:

{
	correlationId: string;
	exchange: string;
	routingKey: string;
	pattern: string;
	sizeBytes: number;
	durationMs: number;
	confirmedAt: string;
}

DLQ Enriquecida

publishToDlqAndAck tenta embutir JSON com:

{
	"failedAt": "2025-09-30T12:34:56.000Z",
	"error": { "name": "Error", "message": "...", "stack": "..." },
	"originalHeaders": { ... },
	"originalPayload": { ... }
}

Header x-dlq-enriched indica 1 (sucesso) ou 0 (fallback raw).

Variáveis de Ambiente

| Nome | Descrição | Default | |------|-----------|---------| | RABBITMQ_URL | URL de conexão | (obrigatório) | | RABBITMQ_EXCHANGE | Exchange default integração | integration.inbound | | RABBITMQ_ALTERNATE_EXCHANGE | Alternate exchange | integration.inbound.ae | | RABBITMQ_EXCHANGE_TYPE | Tipo do exchange | topic | | RABBITMQ_PUBLISH_TIMEOUT_MS | Timeout confirmação | 5000 |

Topologia (opcional)

| Nome | Descrição | Default | |------|-----------|---------| | RABBITMQ_EXCHANGE_INBOUND | Exchange inbound (preferencial) | integration.inbound | | RABBITMQ_EXCHANGE_OUTBOUND | Exchange outbound (preferencial) | integration.outbound | | RABBITMQ_EXCHANGE_AE | Sufixo da AE (compat) | ae | | RABBITMQ_EXCHANGE_AE | Sufixo da AE (preferencial) | ae | | RABBITMQ_EXCHANGE_DLX | Sufixo da DLX (preferencial) | dlx | | RABBITMQ_EXCHANGE_DLX | Sufixo da DLX (compat) | dlx | | RABBITMQ_UNROUTABLE_QUEUE | Nome da fila de unroutable (sem prefixo) | unroutable | | RABBITMQ_RETRY_POLICY_SHORT_MS | TTL retry curto | 120000 | | RABBITMQ_RETRY_POLICY_LONG_MS | TTL retry longo | 3600000 | | RABBITMQ_QUEUE_TYPE | Tipo das filas principais (classic ou quorum) | quorum | | RABBITMQ_RETRY_QUEUE_TYPE | Tipo das filas de retry (herda o principal se vazio) | quorum | | RABBITMQ_DELIVERY_LIMIT | Máximo de entregas antes de enviar para a DLX (quorum) | 0 (desativado) | | RABBITMQ_QUORUM_INITIAL_GROUP_SIZE | Tamanho inicial do grupo quorum | 0 (valor padrão do cluster) |

Notas:

• As variáveis com sufixo “preferencial” são a convenção nova. As chaves “compat” continuam funcionais para serviços existentes.
• RabbitTopologyManager usa estas variáveis para criar: AE (fanout), DLX (topic), retries (topic) e filas integration.<system>.* com DLQ e binds.
• Filas agora são criadas como quorum por padrão (inclusive DLQ e retries). Ajuste as variáveis acima caso precise manter filas clássicas em ambientes limitados.

Boas Práticas

• Reutilize a instância injetada (não crie manualmente o publisher baixo nível).
• Evite payloads muito grandes (considerar compressão se sizeBytes > ~256KB).
• Log de debug seletivo (considere flag futura DEBUG_RABBIT_PUBLISH).

Licença

MIT