GM Hades Backend
GM Hades Backend es el gateway gRPC centralizado de GM Transport para la ejecución de consultas SQL en bases de datos de clientes multitenant y para el acceso de solo lectura a la Bóveda Fiscal. Está escrito en Go, desplegado como un binario estático en Azure Container Apps, y expone los cuatro servicios gRPC sobre un único puerto TCP usando multiplexación con cmux.
El servicio nació de la necesidad del equipo de Proyectos Nuevos de eliminar la proliferación de Azure Functions —uno por consulta, uno por plataforma— y reemplazarlos por un gateway unificado donde cualquier backend envía un RFC de cliente más una consulta SQL y recibe los resultados, sin necesidad de conocer las credenciales ni la ubicación de la base de datos destino.
Motivación
Antes de GM Hades, cada integración requería crear un endpoint dedicado para cada consulta y cada plataforma. Agregar una nueva consulta significaba un nuevo endpoint, un nuevo despliegue y una nueva fuente de deuda técnica. El crecimiento era exponencial en complejidad.
GM Hades invierte ese modelo: un desarrollador envía una consulta SQL y un RFC; el gateway resuelve las credenciales, ejecuta la consulta en la base de datos correcta y devuelve los resultados. No hay endpoints por consulta. No hay conocimiento de credenciales en el cliente.
Servicios expuestos
El binario registra cuatro servicios gRPC independientes sobre el mismo puerto:
| Servicio | Proto | Función principal |
|---|---|---|
QueryGatewayService v1 | query.proto | Gateway SQL legado compatible hacia atrás |
QueryGatewayService v2 | query_v2.proto | Gateway completo con streaming, batch, transacciones y esquemas |
BovedaFiscalDBService | boveda_fiscal_db.proto | Consultas MariaDB vía túnel SSH |
BovedaFiscalSFTPService | boveda_fiscal_sftp.proto | Acceso a CFDIs XML vía SFTP |
El mismo puerto 50051 sirve tráfico gRPC (HTTP/2) y la documentación HTML interactiva (HTTP/1.1). Un navegador que accede a http://host:50051 recibe la documentación del API; un cliente gRPC recibe el servicio completo.
Características de rendimiento
Sin conexión por petición en SQL Server. Las credenciales de cada RFC se obtienen del ADMON una vez y se almacenan en caché en proceso durante 15 minutos. Las peticiones subsecuentes del mismo tenant no incurren en una consulta de red para obtener la configuración.
Streaming sin carga en memoria. StreamQuery itera fila por fila y emite chunks al cliente de forma incremental. El conjunto de datos nunca se carga completo en memoria, lo que permite procesar datasets de tamaño arbitrario con uso de memoria constante.
Propagación de contexto completa. Toda operación ejecuta bajo un context.Context con timeout explícito que se propaga desde el handler hasta el driver SQL. Si el cliente se desconecta o el timeout expira, la consulta de base de datos se cancela de forma inmediata.
Cancelación activa. QueryHandlerV2 mantiene un mapa en proceso de queries activos por ID. Los clientes pueden cancelar una consulta en ejecución por su ID; la cancelación se propaga a través del context.CancelFunc almacenado.
Despliegue
El binario se construye en dos etapas con CGO_ENABLED=0 para producir un binario estático. La imagen final es alpine:latest con el binario, los certificados CA del sistema y el archivo connections.json de Bóveda Fiscal embebido en /config/boveda_fiscal/.
Existen dos imágenes Docker:
| Imagen | Puerto | Descripción |
|---|---|---|
gm-hades-backend | 50051 | Gateway SQL Server completo (requiere ADMON DB) |
gm-hades-boveda | 50052 | Solo Bóveda Fiscal (SKIP_ADMON_DB=true) |
Resumen
- GM Hades Backend es el gateway gRPC centralizado que elimina la necesidad de endpoints por consulta en integraciones multitenant.
- Expone cuatro servicios gRPC sobre un único puerto TCP: gateway SQL Server v1/v2 y Bóveda Fiscal DB/SFTP.
- Las credenciales por tenant se cachean 15 minutos en proceso; el streaming opera con memoria constante.
- El mismo puerto sirve gRPC y documentación HTML interactiva mediante multiplexación con
cmux. - Se despliega como binario estático en Azure Container Apps con dos variantes de imagen: completa y solo Bóveda Fiscal.