Recuperación de la Exception Queue de Oracle AQ

Reconstrucción didáctica de un problema que resolví en Totalplay: miles de solicitudes de clientes atoradas sin que nadie lo supiera, porque los mensajes que agotaban sus reintentos en Oracle Advanced Queuing terminaban en la exception queue y ningún proceso la leía. Fui el primero en resolverlo internamente.

Este repositorio no contiene código ni datos de Totalplay. Es una implementación nueva con nombres de ejemplo que reproduce el problema y la solución.

El problema

Oracle AQ reintenta automáticamente un mensaje cuando el consumidor hace rollback. Al llegar a max_retries, lo mueve a la exception queue de su tabla de colas (AQ$_<tabla>_E). Hasta ahí, todo es comportamiento esperado.

Lo que casi nadie sabe es que esa cola se crea deshabilitada para desencolar. Si no hay un proceso diseñado para vaciarla, los mensajes se acumulan indefinidamente:

  • La operación del cliente (en este ejemplo, cancelar una promoción) nunca se completa.
  • No hay error visible: la cola principal funciona y los monitoreos normales no ven nada.
  • El problema crece en silencio hasta que aparece como queja de clientes.

La solución

 cola principal ──(5 rollbacks)──▶ exception queue ──▶ RecoveryWorker ──┬──▶ reencola con backoff ──▶ cola principal
                                                       │                 └──▶ revisión manual (nunca se descarta)
                                                       └──▶ bitácora de cada decisión
  1. Diagnóstico (sql/04_diagnostico.sql): cuántos mensajes están atorados y desde cuándo.
  2. Habilitar el desencolado (sql/02_habilitar_exception_queue.sql), solo de salida.
  3. Un worker que decide mensaje por mensaje con una política explícita:
Situación Acción
Mensaje vacío o ilegible Revisión manual: jamás se procesará bien solo
Mensaje con más de 7 días Revisión manual: el negocio puede haber cambiado
Ya se intentó recuperar 3 veces Revisión manual: es un mensaje veneno
Cualquier otro caso Reencolar con backoff exponencial (5, 10, 20 min… máximo 2 h)

Decisiones de diseño

  • Una transacción por mensaje. Desencolar, reencolar o apartar, y registrar en bitácora ocurren en la misma transacción de Oracle (OracleAQVisibilityMode.OnCommit). Si algo falla, el mensaje regresa intacto a la exception queue.
  • Sin giros en falso. Un mensaje revertido vuelve al frente de la cola; si reaparece en la misma corrida, el worker se detiene y lo deja para la siguiente.
  • Nada se descarta en silencio. Lo que no se puede recuperar va a una tabla de revisión con su motivo.
  • Política como función pura. RecoveryPolicy no depende de Oracle: la lógica delicada se prueba completa sin base de datos.
  • Seguridad. Todas las consultas son parametrizadas (BindByName), la cadena de conexión viene de una variable de entorno y la bitácora guarda identificadores, nunca el contenido de los mensajes, que puede tener datos personales.

Estructura

sql/                      Scripts de Oracle: cola, exception queue, bitácora y diagnóstico
src/AqRecovery/           Núcleo sin dependencias: contratos, política y worker
src/AqRecovery.Oracle/    Adaptador ODP.NET y proceso ejecutable
tests/AqRecovery.Tests/   Pruebas con un gateway en memoria con semántica transaccional

Cómo ejecutarlo

# Pruebas del núcleo (no requieren Oracle ni paquetes de NuGet)
dotnet run -c Release --project tests/AqRecovery.Tests

# Proceso real contra Oracle (requiere el paquete Oracle.ManagedDataAccess.Core)
export ORACLE_CONNECTION="User Id=...;Password=...;Data Source=..."
dotnet run -c Release --project src/AqRecovery.Oracle

Las pruebas cubren la política completa, la reversión ante fallas a mitad de la transacción, el caso de la cola vacía y un mensaje veneno que regresa a la exception queue tres veces hasta terminar en revisión manual.