Servicios gRPC

GM Hades Backend registra cuatro servicios gRPC independientes sobre un único puerto. Cada servicio tiene su propio archivo .proto, su propio paquete de código generado y su propio dominio de responsabilidad. Los servicios no se importan entre sí.

QueryGatewayService v1

Paquete proto: query
Archivo: proto/query.proto
Propósito: Endpoint legado de ejecución de consulta única, mantenido por compatibilidad hacia atrás con integraciones existentes.
Métodos: ExecuteQuery, Check (health check)

Este servicio no recibe nuevas funcionalidades. Los proyectos nuevos deben usar v2.

QueryGatewayService v2

Paquete proto: queryv2
Archivo: proto/query_v2.proto (778 líneas, completamente documentado en el archivo)
Propósito: Gateway SQL completo con todas las capacidades de consulta, streaming, operaciones de esquema y monitoreo.

Métodos

Método	Tipo	Descripción
`ExecuteQuery`	Unario	Consulta SQL con paginación, búsqueda, sort y metadata de columnas
`StreamQuery`	Streaming servidor	Consulta SQL con entrega incremental en chunks
`CancelQuery`	Unario	Cancela una consulta activa por su ID
`GetActiveQueries`	Unario	Lista las consultas en ejecución para un tenant
`ExecuteBatch`	Unario	Ejecuta múltiples consultas independientes en una sola llamada
`ExecuteTransaction`	Unario	Ejecuta múltiples consultas en una transacción SQL Server con nivel de aislamiento configurable
`GetTableSchema`	Unario	Introspección de tabla: columnas, índices, foreign keys, constraints
`ListTables`	Unario	Enumera tablas y vistas con filtrado opcional
`ValidateQuery`	Unario	Valida la sintaxis SQL sin ejecutar la consulta
`GetServiceInfo`	Unario	Versión del build, commit hash y uptime

TenantContext

Todas las llamadas v2 requieren un TenantContext:

message TenantContext {
    string rfc = 1;               // RFC del cliente, 10-13 caracteres
    int32 timeout_seconds = 2;    // Default 300, máximo 600
    string connection_tag = 3;    // Etiqueta de auditoría opcional
}

ExecuteQueryRequest

{
  "tenant": {
    "rfc": "KIJ0906199R1",
    "timeout_seconds": 60,
    "connection_tag": "dashboard-main"
  },
  "sql_query": "SELECT Codigo, Descripcion FROM CatUnidades",
  "pagination": {"page": 1, "page_size": 50},
  "sort": {"column": "Codigo", "descending": false},
  "search": {"term": "TRACTO", "columns": ["Descripcion"]},
  "return_metadata": true,
  "return_statistics": true
}

StreamQuery — chunks de respuesta

StreamQuery emite tres tipos de chunks discriminados por ChunkType:

`ChunkType`	Contenido
`METADATA`	Definiciones de columnas (nombre, tipo, precisión, nullabilidad)
`DATA`	Filas del resultado en el batch actual
`END`	Estadísticas totales: filas totales, tiempo de ejecución, bytes transferidos

Comparación de métodos por caso de uso

Caso de uso	Método recomendado
Consulta con paginación para UI	`ExecuteQuery`
Exportación de dataset > 10 000 filas	`StreamQuery`
Dashboard con múltiples KPIs en paralelo	`ExecuteBatch`
Actualización de varias tablas de forma atómica	`ExecuteTransaction`
Explorar estructura de la base de datos	`GetTableSchema` + `ListTables`
Validar SQL antes de enviarlo a producción	`ValidateQuery`
Monitoreo de operaciones en curso	`GetActiveQueries`
Cancelar una operación de larga duración	`CancelQuery`

BovedaFiscalDBService

Paquete proto: bovedafiscaldb
Archivo: proto/boveda_fiscal_db.proto
Propósito: Consultas SQL de solo lectura contra la base de datos MariaDB de la Bóveda Fiscal, accesible únicamente a través de un túnel SSH.

Métodos

Método	Tipo	Descripción
`ExecuteQuery`	Unario	SELECT parametrizado contra MariaDB vía túnel SSH
`StreamQuery`	Streaming servidor	Resultado en chunks (default 100 filas/chunk, máximo 1 000)
`ListTables`	Unario	Lista tablas y vistas del schema
`GetTableSchema`	Unario	Metadata de columnas, nullabilidad, flags de clave primaria

Solo se aceptan SELECT, SHOW, DESCRIBE y EXPLAIN. Cualquier otro tipo de sentencia devuelve codes.InvalidArgument antes de abrir el túnel SSH.

Consulta con parámetros posicionales

Los parámetros se pasan como repeated string params y se corresponden con los marcadores ? en la consulta:

{
  "rfc": "MTC0109038R4",
  "sql_query": "SELECT * FROM Facturas WHERE RFC_Emisor = ? AND Año = ?",
  "params": ["XAXX010101000", "2025"]
}

BovedaFiscalSFTPService

Paquete proto: bovedafiscalsftp
Archivo: proto/boveda_fiscal_sftp.proto (532 líneas)
Propósito: Acceso de solo lectura al servidor SFTP que almacena CFDIs XML (comprobantes fiscales digitales).

Métodos

Método	Tipo	Descripción
`ListDirectory`	Unario	Listado de directorio con metadata
`DownloadFile`	Unario	Descarga completa de archivo hasta 10 MB
`StreamDownload`	Streaming servidor	Descarga en chunks configurables (default 64 KB)
`StatFile`	Unario	Metadata de archivo o directorio
`ReadTextFile`	Unario	Contenido de texto hasta 50 MB como string
`SearchXMLFiles`	Streaming servidor	Descubrimiento recursivo de archivos XML
`FindByUUID`	Unario	Localiza un CFDI por su UUID sin descargarlo
`StreamDownloadByUUID`	Streaming servidor	Localiza y descarga un CFDI por UUID
`DownloadBatchAsZip`	Streaming servidor	Resuelve múltiples CFDIs por UUID, los comprime en ZIP y transmite el archivo con progreso en tiempo real

Límites de tamaño por operación

Operación	Límite	Motivo
`DownloadFile`	10 MB	Respuesta unaria única
`ReadTextFile`	50 MB	Contenido de texto en la respuesta
`StreamDownload`	Sin límite	Entrega en chunks de 64 KB
`DownloadBatchAsZip`	Sin límite	ZIP transmitido vía `io.Pipe` sin carga en memoria

DownloadBatchAsZip — protocolo de dos fases

DownloadBatchAsZip emite dos tipos de chunk sobre el mismo stream, discriminados por ZipChunkType:

Fase 1 — PROGRESS: Por cada UUID que se resuelve en el árbol de directorios SFTP, se emite un chunk con progress_percent y progress_status. Proporciona retroalimentación en tiempo real al cliente durante la resolución.

Fase 2 — DATA: Una vez resueltos todos los UUIDs, se transmiten los bytes del archivo ZIP en chunks. El primer chunk DATA incluye zip_file_name, files_found, files_not_found y not_found_uuids. El último chunk DATA incluye total_size_bytes.

Documentación interactiva en el puerto

La documentación completa de todos los métodos, mensajes y campos está disponible en HTML en http://host:50051/docs. El servidor HTTP en ese mismo puerto —multiplexado con cmux— sirve la documentación generada a partir del contenido de los archivos proto.

Resumen

GM Hades expone cuatro servicios gRPC: v1 (legado), v2 (gateway completo), BovedaFiscalDB (MariaDB vía SSH) y BovedaFiscalSFTP (CFDIs XML).
El v2 tiene 10 métodos organizados en cinco categorías: consultas, streaming, batch/transacciones, esquema y monitoreo.
TenantContext con el RFC del cliente es obligatorio en todas las llamadas v2.
Bóveda Fiscal DB acepta solo sentencias de lectura (SELECT, SHOW, DESCRIBE, EXPLAIN). El resto devuelve error antes de abrir el túnel SSH.
DownloadBatchAsZip opera en dos fases sobre un stream único: PROGRESS por resolución de UUIDs, DATA por bytes del ZIP. Nunca carga el archivo completo en memoria.