<< All versions
Skill v1.0.0
currentLLM-judged scan90/100abrahamvilchesdelacruz/ididntcatchthat/api-events-infra
──Details
PublishedOctober 24, 2026 at 12:34 AM
Content Hashsha256:66cb517ddc96ae67...
Git SHA6a16263a45ba
──Files
Files (1 file, 3.5 KB)
SKILL.md3.5 KBactive
SKILL.md · 95 lines · 3.5 KB
version: "1.0.0" name: api-events-infra description: "AmqpMessageBus, SubscribersBootstrapper, retry, DLQ, idempotencia en apps/api/. Trigger: Al implementar AmqpMessageBus, configurar SubscribersBootstrapper, o entender retry y DLQ." license: Apache-2.0 metadata: author: AbrahamVilchesDeLaCruz version: "2.0"
When to Use
- Al implementar o modificar
AmqpMessageBus - Al registrar subscribers en módulos NestJS
- Al diseñar la política de retry o idempotencia
Leereferences/docs.mdpara skills relacionadas, ADRs y documentación externa.
Leereferences/amqp-message-bus.mdpara la implementación completa deAmqpMessageBus,SubscribersBootstrappery el registro en módulos.
Concepto
AmqpMessageBus implementa tres interfaces a la vez:
DomainEventPublisher (domain) → publish(events)DomainEventConsumer (app) → consume(queue, eventName, exchange, DomainEventClass, handler)OnModuleDestroy (NestJS) → onModuleDestroy() — cierra channel + connection al apagar
SubscribersBootstrapper llama a subscriber.init() en onModuleInit() — registra todos los consumers al arrancar.
Retry Policy
| Intento | Delay | Mecanismo | |
|---|---|---|---|
| 1 | 1 s | expiration: "1000" en .retry → vuelve vía DLX | |
| 2 | 5 s | expiration: "5000" en .retry → vuelve vía DLX | |
| 3 | 10 s | expiration: "10000" en .retry → vuelve vía DLX | |
| 4 | — | → .dead_letter — intervención manual |
El `expiration` es por mensaje, no por cola — permite backoff exponencial con una sola .retry queue.
Colas creadas automáticamente en setupQueues():
{queueName}— cola principal{queueName}.retry— mensajes esperando reintento{queueName}.dead_letter— mensajes agotados
Idempotencia
Opción A — Natural (por defecto)
typescript
async handle(event: DomainEvent): Promise<void> {const existing = await this.repo.search(id);if (existing) return; // ya procesadoawait this.useCase.execute({ ... });}
Opción B — Inbox table (operaciones irreversibles críticas)
typescript
async handle(event: DomainEvent): Promise<void> {if (await this.inboxRepo.exists(event.eventId)) return;await this.useCase.execute({ ... });await this.inboxRepo.save(event.eventId, event.eventName());}
Tabla: processed_events(event_id UUID PK, event_name, processed_at) — purgar > 30 días.
Reglas
AmqpMessageBusvive enshared/infrastructure/— es transversal a todos los BCAmqpMessageBusse registra una sola vez enSharedModulecomo singleton víauseExisting; los módulos BC no lo re-registranSubscribersBootstrappery el tokenSUBSCRIBERSse importan desde sharedOnModuleInitsolo enSubscribersBootstrapper— nunca en subscribers ni use casesSUBSCRIBERSse registra conuseFactoryque devuelve un array de subscribers — nuncauseExisting + multi: true- El DLQ no se re-encola automáticamente — requiere fix manual + re-encolado explícito
prefetch(1)siempre — procesamiento secuencial por consumerDomainEventClassesnew (...args: unknown[]) => DomainEvent— nonever, noany- El payload publicado usa el campo
datapara los atributos del evento, noattributesnitoPrimitives() AmqpMessageBustiene reconexión automática: al cerrar la conexión, esperaRECONNECT_DELAY_MSy re-registra todos los consumers
ADR de decisión: docs/adr/019-event-bus-strategy.md