El módulo TM (Transaction Module) de Kamailio es el componente encargado de implementar la capa transaccional del protocolo SIP según la RFC 3261. Su función principal es convertir a Kamailio de un proxy stateless a un proxy stateful, lo que significa que mantiene estado de las peticiones y respuestas mientras se procesan. Este módulo es prácticamente obligatorio en cualquier implementación de Kamailio que vaya más allá del simple reenvío de paquetes.

El módulo TM gestiona transacciones SIP, que son pares de petición-respuesta. Cuando una petición SIP entra al servidor, el módulo puede crear una transacción que agrupa esa petición con todas sus respuestas asociadas. Esto incluye las respuestas provisionales (1xx), exitosas (2xx), de redirección (3xx) y de error (4xx, 5xx, 6xx).
La gestión transaccional implica varias responsabilidades críticas. Primero, el módulo implementa el mecanismo de retransmisión automática de peticiones cuando no se reciben respuestas en los tiempos establecidos por el protocolo. Esto es especialmente relevante para peticiones sobre UDP, donde los paquetes pueden perderse. Segundo, absorbe retransmisiones duplicadas, evitando que el mismo mensaje se procese múltiples veces. Tercero, genera respuestas de timeout cuando un servidor downstream no responde dentro de los límites temporales configurados.

El módulo mantiene en memoria una estructura de datos para cada transacción activa, que incluye la petición original, información de enrutamiento, timers activos y el estado actual de la transacción. Esta información se mantiene hasta que la transacción se completa, momento en el cual se libera la memoria asociada.

Funciones principales del módulo TM

- t_relay() es la función más utilizada. Envía la petición actual al destino configurado en el Request-URI, activando toda la maquinaria transaccional. Esto incluye el inicio de timers de retransmisión, la preparación de estructuras para recibir respuestas, y el establecimiento del contexto transaccional. Si la petición ya forma parte de una transacción existente (por ejemplo, es una retransmisión), t_relay() la detecta y no crea una transacción duplicada.

- t_newtran() crea explícitamente una nueva transacción sin reenviar el mensaje. Esto es útil cuando necesitas procesar el mensaje localmente o aplicar lógica compleja antes de decidir qué hacer con él. Una vez creada la transacción con t_newtran(), puedes usar otras funciones como t_reply() o t_relay() posteriormente.

- t_reply(code, reason) genera una respuesta SIP directamente desde el script. Por ejemplo, t_reply("486", "Busy Here") envía un código 486 al origen de la petición. Esta función maneja automáticamente todos los detalles del protocolo: construye las cabeceras obligatorias, copia las cabeceras necesarias de la petición original, y envía la respuesta por la ruta correcta.

- t_check_trans() verifica si el mensaje actual ya está siendo manejado por una transacción existente. Retorna verdadero si encuentra una transacción coincidente, lo que permite al script abortar el procesamiento para evitar trabajo duplicado. Esta función es especialmente importante al inicio del script de enrutamiento.

- t_on_failure("route_name") define qué bloque de failure_route se ejecutará si la transacción falla. Una transacción se considera fallida cuando todas las respuestas recibidas son negativas (códigos >= 300) o cuando expiran los timers sin recibir respuesta. Las failure_routes permiten implementar lógicas de failover, donde puedes intentar destinos alternativos o aplicar transformaciones a la petición antes de reintentarla.

- t_on_reply("route_name") especifica un bloque de onreply_route que se ejecutará cada vez que se reciba una respuesta para esa transacción. Esto permite inspeccionar y modificar respuestas en tránsito, útil para manipular SDP, agregar cabeceras personalizadas o aplicar políticas de negocio basadas en las respuestas recibidas.

El flujo de procesamiento en Kamailio con el módulo TM sigue una secuencia específica. Cuando llega una petición SIP, primero se ejecuta el bloque request_route principal sin crear ninguna transacción. En este punto el procesamiento es stateless y puedes realizar validaciones iniciales, consultas a base de datos, autenticación, autorización y cualquier lógica de negocio necesaria. La creación de la transacción ocurre cuando llamas a t_relay(), t_newtran() o implícitamente cuando usas t_reply(). A partir de ese momento, el mensaje pasa a control del módulo TM. Si el mensaje es reenviado con t_relay(), el módulo espera respuestas del downstream y las retransmite hacia el origen.

Las respuestas recibidas disparan los bloques onreply_route si fueron configurados con t_on_reply(). Estos bloques se ejecutan en el contexto de la transacción y tienen acceso tanto a la petición original como a la respuesta recibida. Puedes modificar la respuesta antes de que se reenvíe al cliente. Si todas las respuestas son negativas o hay timeout, se ejecuta el bloque failure_route configurado con t_on_failure(). Aquí puedes implementar lógica de reintentos. Por ejemplo, modificar el Request-URI para apuntar a un servidor alternativo y llamar nuevamente a t_relay(). El módulo TM maneja la complejidad de reutilizar la misma transacción para múltiples intentos de entrega.

El módulo TM tiene varios parámetros que afectan su comportamiento. 

fr_timer define el timeout para respuestas finales (por defecto 30 segundos). Si no se recibe ninguna respuesta final en este tiempo, la transacción se considera fallida. 

fr_inv_timer es similar pero específico para peticiones INVITE, típicamente configurado con valores mayores (120-180 segundos) porque el establecimiento de llamadas puede tomar más tiempo.

noisy_ctimer controla si el módulo registra en logs cuando expiran los timers. En producción suele desactivarse para reducir el volumen de logs. restart_fr_on_each_reply hace que el timer de respuesta final se reinicie cada vez que llega una respuesta provisional, evitando timeouts prematuros en llamadas que tardan en establecerse.

aggregate_challenges habilita la agregación de desafíos de autenticación cuando se hace fork a múltiples destinos. Sin esto, solo se retransmite la primera respuesta 401/407 recibida, lo que puede causar problemas en escenarios de autenticación complejos.

El módulo TM soporta dos modos principales de operación. En modo stateful, que es el predeterminado al usar t_relay(), se mantiene estado completo de la transacción. Esto consume memoria pero proporciona todas las funcionalidades avanzadas: retransmisiones, timeouts, failure routes, etc.
También existe la posibilidad de hacer reenvío stateless usando la función forward() del módulo core de Kamailio, sin involucrar al módulo TM. Esto consume menos recursos pero no ofrece ninguna de las garantías transaccionales. Es útil solo en escenarios muy específicos donde el volumen de tráfico es extremadamente alto y las funcionalidades avanzadas no son necesarias.

El módulo TM es la base sobre la que funcionan muchos otros módulos de Kamailio. El módulo de accounting (acc) depende del TM para registrar llamadas correctamente, ya que necesita saber cuándo una transacción se completa exitosamente. Los módulos de autenticación se integran con el TM para manejar desafíos 401/407 de forma correcta.
El módulo dialog también depende del TM, ya que los diálogos se crean cuando una transacción INVITE recibe una respuesta 2xx. El módulo registrar utiliza el TM para enviar respuestas 200 OK a los registros y para implementar timeouts en el procesamiento de registros.

Cada transacción activa consume memoria proporcional al tamaño de la petición SIP original más las estructuras de control del módulo. En sistemas con alto volumen de llamadas simultáneas, esto puede sumar varios gigabytes de RAM. El módulo TM limpia automáticamente las transacciones completadas, pero mantiene las estructuras durante un tiempo adicional para absorber retransmisiones tardías.

El procesamiento transaccional añade latencia mínima (microsegundos) pero es necesario para cumplir con el protocolo SIP correctamente. El costo computacional es bajo comparado con los beneficios de tener un proxy robusto que maneja correctamente pérdida de paquetes, timeouts y escenarios de error.