Skip to main content

​
Por qué esto es importante

Un cliente envía una transacción. Midaz debe hacer dos cosas: validarla y persistir el resultado. En el modo sincrónico, ambos pasos se ejecutan en la misma solicitud. El cliente espera a que cada escritura llegue a la base de datos antes de obtener una respuesta. Este modelo es simple y predecible, pero tiene un techo. A alto volumen, las escrituras en la base de datos se convierten en el cuello de botella. Cada transacción retiene una conexión, espera por bloqueos y compite por I/O. El modo asíncrono rompe esa dependencia. Midaz valida la transacción, devuelve la respuesta de inmediato y persiste los datos en segundo plano a través de RabbitMQ. El cliente obtiene respuestas más rápidas. Con el procesamiento asíncrono habilitado, el Bulk Recorder agrupa inserciones de forma predeterminada; configura BULK_RECORDER_ENABLED=false para persistir los mensajes en cola individualmente. Para orientación más amplia sobre escalamiento, consulta Estrategias de escalabilidad.

​
Cómo funciona

​
Modo sincrónico (predeterminado)

Midaz valida la transacción y la escribe directamente en PostgreSQL dentro del mismo ciclo de solicitud. La API envía su respuesta solo después de que cada operación de base de datos se completa.
Diagrama de secuencia que muestra al cliente enviando un POST /transaction a la API de Midaz, que lo valida, escribe la transacción y las operaciones en PostgreSQL, espera la confirmación y solo entonces devuelve 201 Created al cliente. La respuesta 201 Created lleva el estado transitorio CREATED, no la aprobación final.

Figura 1. Flujo de transacción sincrónico — el cliente espera hasta que la escritura en la base de datos sea confirmada.

Aquí está el flujo completo, paso a paso:
  1. El cliente envía un POST /transaction a la API de Midaz.
  2. La API valida la solicitud — ejecuta la validación de la estructura de la solicitud, las verificaciones de saldo y la aplicación de límites aquí.
  3. La API escribe en PostgreSQL — persiste la transacción y sus operaciones dentro del mismo ciclo de solicitud.
  4. PostgreSQL confirma la escritura — hace commit de todos los registros.
  5. La API devuelve 201 Created al cliente con la transacción creada. La respuesta sale del servidor solo después de que la base de datos confirma todo. La respuesta lleva el estado transitorio CREATED; Midaz promueve la transacción a APPROVED de forma asíncrona después del procesamiento de saldos. No trates el 201 como aprobación final; espera a que el estado llegue a APPROVED antes de considerar la transacción liquidada.
Características:
  • El tiempo de respuesta incluye la latencia de escritura en la base de datos.
  • Cada transacción es una operación independiente de base de datos.
  • Más simple de razonar. La respuesta muestra exactamente lo que Midaz persiste.
Incluso en modo sincrónico, Midaz actualiza los saldos atómicamente en Redis durante la solicitud. Redis es la fuente autoritativa para los saldos. La escritura anterior persiste la transacción y sus operaciones, no las filas de saldo en Postgres. El worker de sincronización de saldos, siempre activo, reconcilia esas filas (consulta Sincronización de saldos).

​
Modo asíncrono

Midaz valida la transacción de la misma manera. En lugar de una escritura directa en la base de datos, Midaz publica un mensaje en RabbitMQ. Un consumidor en segundo plano recoge el mensaje y maneja la persistencia por separado.
Diagrama de secuencia que muestra al cliente enviando un POST /transaction a la API de Midaz, que lo valida, publica el payload en RabbitMQ y devuelve inmediatamente 201 Created al cliente. La respuesta 201 Created lleva el estado transitorio CREATED, no la aprobación final. En paralelo, RabbitMQ entrega el mensaje a un consumidor en segundo plano, que escribe la transacción y las operaciones en PostgreSQL; los saldos los maneja el worker dedicado de sincronización de saldos.

Figura 2. Flujo de transacción asíncrono — el cliente recibe una respuesta tan pronto como el mensaje se publica, y la persistencia ocurre en segundo plano.

Aquí está el flujo completo, paso a paso:
  1. El cliente envía un POST /transaction a la API de Midaz.
  2. La API valida la solicitud — ejecuta la validación de la estructura de la solicitud, las verificaciones de saldo y la aplicación de límites exactamente como en el modo sincrónico.
  3. La API publica el payload de la transacción en RabbitMQ en lugar de una escritura directa en la base de datos.
  4. La API devuelve 201 Created al cliente en cuanto la cola acepta el mensaje — el cliente no espera por la persistencia en la base de datos. La respuesta lleva el estado transitorio CREATED; Midaz promueve la transacción a APPROVED de forma asíncrona después del procesamiento de saldos. No trates el 201 como aprobación final; espera a que el estado llegue a APPROVED antes de considerar la transacción liquidada.
  5. RabbitMQ entrega el mensaje a un consumidor en segundo plano, desacoplado de la solicitud de la API.
  6. El consumidor escribe en PostgreSQL — persiste la transacción y sus operaciones a partir del mensaje encolado. El worker de sincronización de saldos coordina las actualizaciones de saldo y mantiene los saldos consistentes en ambos modos (consulta la sección Sincronización de saldos).
Características:
  • El tiempo de respuesta excluye la latencia de escritura en la base de datos — el cliente solo espera por la validación y la publicación en la cola.
  • Midaz serializa los mensajes con MessagePack para un transporte compacto y eficiente.
  • Los consumidores en segundo plano escriben en la base de datos a su propio ritmo, con reintentos; las inserciones en lote requieren un Bulk Recorder habilitado.
El paso de validación es idéntico en ambos modos. Verificaciones de saldo, validación de la estructura de la solicitud, aplicación de límites — todo eso ocurre antes de que la API responda, independientemente del modo de procesamiento. La diferencia está solo en cuándo los datos llegan a la base de datos.

​
Resiliencia incorporada

Si RabbitMQ no está disponible cuando el modo asíncrono intenta publicar un mensaje, Midaz intenta realizar una escritura directa en la base de datos. Si esa escritura falla, Midaz devuelve el error de la base de datos. Esto significa:
  • Durante una interrupción de la cola, Midaz intenta escribir directamente en la base de datos.
  • El cliente puede recibir un error si falla la escritura de fallback en la base de datos.
  • Midaz registra la falla de la cola y, si también falla la escritura directa, la falla del fallback para que tu equipo de operaciones pueda investigarlas.
Durante una interrupción de la cola, la latencia puede aumentar porque las escrituras van directo a la base de datos. Monitorea la salud de RabbitMQ para mantener activo el modo asíncrono.

​
Habilitar el modo asíncrono

Configura una variable de entorno en la aplicación del ledger:
Con false (el valor predeterminado), todas las transacciones usan procesamiento sincrónico y se persisten directamente en PostgreSQL. El bootstrap actual del Ledger todavía inicializa RabbitMQ y conecta su consumidor. Con true, el ledger publica los payloads de transacción en el exchange configurado de RabbitMQ. Luego un consumidor en segundo plano maneja la persistencia.

​
Configuración de RabbitMQ

El modo asíncrono utiliza las siguientes configuraciones de RabbitMQ (todas en el .env del ledger):
El consumidor utiliza credenciales separadas (RABBITMQ_CONSUMER_USER / RABBITMQ_CONSUMER_PASS) del productor. Esto sigue el principio de menor privilegio — el consumidor solo necesita acceso de lectura a la cola.

​
Sincronización de saldos

Un worker dedicado de sincronización de saldos coordina las actualizaciones de saldo. Utiliza Redis como capa de coordinación. Este worker se ejecuta tanto en modo sincrónico como asíncrono. Mantiene los saldos consistentes incluso cuando múltiples consumidores procesan mensajes al mismo tiempo. El worker de sincronización de saldos se ejecuta automáticamente en ambos modos. No necesitas configuración adicional más allá de una instancia de Redis disponible.

​
Circuit breaker de RabbitMQ

Cuando habilitas el modo asíncrono, Midaz depende de RabbitMQ para la persistencia de las transacciones. Un circuit breaker integrado protege contra interrupciones del broker. Monitorea la salud de la conexión con RabbitMQ y falla rápido cuando el broker se cae. Esto previene la acumulación de solicitudes y las fallas en cascada. El circuit breaker está activo en la ruta de RabbitMQ de tenant único. RabbitMQ multi-tenant usa la gestión de conexiones por tenant. El circuit breaker sigue el modelo estándar de tres estados:
  • Cerrado (normal): las solicitudes fluyen hacia RabbitMQ. El breaker contabiliza las fallas.
  • Abierto (disparado): el breaker rechaza las solicitudes de inmediato y no contacta a RabbitMQ. Un verificador de salud en segundo plano monitorea el broker e intenta la recuperación.
  • Semi-abierto (sondeo): el breaker deja pasar un número limitado de solicitudes para probar la recuperación de RabbitMQ. Si tienen éxito, el circuito se cierra. Si fallan, se vuelve a abrir.
El circuito se abre cuando cualquiera de estas condiciones es verdadera:
  • El número de fallas consecutivas alcanza el umbral, O
  • La proporción de fallas excede el porcentaje configurado dentro de la ventana de conteo

​
Configuración del circuit breaker

Cuando el circuito está abierto, Midaz intenta realizar escrituras directas en la base de datos para las transacciones asíncronas. Si una escritura directa falla, Midaz devuelve el error de la base de datos; el fallback no garantiza la entrega de la transacción durante interrupciones del broker.
Para la mayoría de los deployments en producción, los valores predeterminados funcionan bien. Ajusta CONSECUTIVE_FAILURES y TIMEOUT si tu clúster de RabbitMQ tiene patrones de recuperación conocidos. Por ejemplo, reduce el timeout si tu broker se recupera en segundos. Aumenta las fallas consecutivas si ves fluctuaciones transitorias de red.

​
Cómo se conecta el modo asíncrono con el Bulk Recorder

El modo asíncrono y el Bulk Recorder son funcionalidades complementarias que funcionan juntas:
  1. El modo asíncrono desacopla la respuesta de la API de la persistencia — las transacciones van a RabbitMQ en lugar de directamente a PostgreSQL.
  2. El Bulk Recorder optimiza cómo el consumidor escribe esos mensajes en la base de datos — agrupa múltiples mensajes en inserciones en lote únicas.
El Bulk Recorder está activo con el modo asíncrono salvo que establezcas explícitamente BULK_RECORDER_ENABLED=false. Sin modo asíncrono, la persistencia de transacciones usa escrituras directas en la base de datos y no hay cola de transacciones que agrupar.

​
Cuándo usar el modo asíncrono

Usa el modo asíncrono cuando:
  • Necesitas tiempos de respuesta de API más bajos para la creación de transacciones.
  • Tu carga de trabajo involucra altos volúmenes de transacciones (cientos+ por segundo).
  • Ejecutas operaciones por lotes como pagos masivos o liquidaciones.
  • Deseas desacoplar tu capa de API del rendimiento de la base de datos.
Mantén el modo sincrónico cuando:
  • Necesitas persistencia de transacciones directa y ligada a la solicitud.
  • El volumen de transacciones es bajo a moderado.
  • Quieres que una respuesta exitosa de la API signifique que Midaz ya persistió los datos.
  • Trabajas en un entorno de desarrollo o pruebas donde la simplicidad importa más que el rendimiento.
Puedes cambiar entre modos en cualquier momento. Cambia RABBITMQ_TRANSACTION_ASYNC y reinicia la aplicación del ledger. No necesitas migración de datos, porque el formato de la transacción es el mismo en ambas rutas.