Orquestación Asíncrona Persistente para Python, Edge & Desktop
La alternativa industrial Zero-Config y con cero dependencias externas a Celery y Redis. Diseñada sobre transacciones atómicas SQLite WAL para operar con máxima tolerancia ante cortes eléctricos y sin brokers pesados.
Iconografía Tecnológica y Arquitectura de GNQ
GNQ articula estándares abiertos y tecnologías nativas para garantizar máxima resiliencia, rendimiento de microsegundos e integración universal con aplicaciones móviles y contenedores.
Construido únicamente con módulos de la Standard Library (sqlite3, concurrent.futures, threading, multiprocessing). Cero dependencias de terceros.
- Compatible con CPython y PyPy en Linux/macOS/Win
- Interoperabilidad nativa con
asyncioyFuture - Falla rápido ante argumentos no serializables
Modo Write-Ahead Logging de alta concurrencia. Los lectores nunca bloquean a los escritores. Si el servidor se apaga abruptamente, se recupera al instante sin perder tareas.
busy_timeout = 30000mscontra contención- Índices únicos parciales para deduplicación
- Pool thread-local persistente 73x más veloz
Permite a tus aplicaciones móviles Android e iOS enviar tareas, monitorear trabajos en caliente y conectarse al motor GNQ mediante widgets reactivos de baja latencia.
- Arquitectura de streams reactivos para UI
- Notificaciones y tareas en segundo plano
- Compatible con emuladores y dispositivos físicos
SDK oficial con serialización JSON estructurada, reintentos automáticos con retroceso exponencial y cola de espera para envío diferido sin conexión.
- Cola local offline ante pérdida de señal
- Token Bearer y HTTP Basic Auth integrado
- Métodos tipados
enqueue,pollycancel
Despliega GNQ Server y Workers aislados con un solo comando docker compose up -d. Monta volúmenes persistentes y expone sondeos en /health.
- Imagen multi-stage ultra ligera (Python slim)
- Reinicio automático con
restart: always - Volumen persistente
gnq_data:/app/data
Mecanismo de transporte periférico para transmitir última posición GPS, mensajes de rescate o collares de mascotas perdidas cuando la red móvil colapsa por una catástrofe.
- Red distribuida entre teléfonos cercanos
- Filtro antirrebote de hardware (debounce)
- Prioridad P10 crítica para emergencias
Aprovecha directamente las señales del sistema operativo (SIGINT, SIGTERM) para un apagado limpio. Permite elegir entre hilos ligeros o procesos independientes.
ProcessPoolExecutorpara bypass del GIL- Recuperación de tareas huérfanas al reiniciar
- Heartbeats y registro de PIDs en tiempo real
Servidor HTTP multi-hilo integrado en Python sin dependencias externas. Soporta encolado directo con POST /api/tasks, eliminación, reintentos y autenticación segura.
- Basic Auth y API Bearer Token de tiempo constante
- CORS completo para frontends web y apps móviles
- Límite estricto de payload (413 Payload Too Large)
El Fin de la Sobreingeniería en Colas de Tareas
Herramientas como Celery dominan grandes nubes corporativas, pero fallan rotundamente cuando se requiere simplicidad, autonomía de hardware o despliegues locales sin brokers externos.
Persistencia WAL Atómica
Respaldada por SQLite en modo Write-Ahead Logging con busy_timeout = 30000ms. Si se corta la energía en plena ejecución, ninguna tarea se corrompe.
Multi-Worker Real (Hilos y Procesos)
Ejecución en threads para operaciones I/O intensivas o processes (ProcessPoolExecutor) para cómputo CPU multi-core puro sin colisiones de IPC.
Resiliencia Zombie Tasks
Si un worker muere inesperadamente por caída del kernel o SIGKILL, el supervisor recupera automáticamente las tareas huérfanas en RUNNING devolviéndolas a PENDING.
Idempotencia a Nivel de Base de Datos
Índice parcial único idx_gnq_unique_active. Garantiza a nivel de motor SQL que nunca existan dos tareas activas idénticas con el mismo _unique_key.
Monitor Web 2.0 & Seguridad Integrada
Dashboard embebido bilingüe (ES/EN) con login HMAC-SHA256, consola SQL interactiva, logs deduplicados, branding corporativo, telemetría de CPU/RAM/WAL y API REST segura.
Módulo de Hardware IoT (BLE / NFC)
Adaptadores listos para Bluetooth Low Energy y credenciales NFC con filtro antirrebote (debounce), incluyendo simuladores de prueba sin hardware físico.
Directivas Operativas en Vivo
Tabla gnq_directives versionada en SQLite WAL. Permite cambiar umbrales, flags y reglas JSON desde el Monitor o Python vía get_directive() con 0 reinicios y cero eval().
Hot-Swap Canary & Plugins HMAC
GNQWorkerSupervisor valida plugins firmados (SHA-256 / HMAC) en un subproceso Canary aislado antes de relevar workers sin detener el Monitor, aplicando Auto-Rollback si falla.
GNQ frente a los Motores Tradicionales
Comparación objetiva de dependencias, consumo de memoria y capacidades operacionales.
| Característica | GNQ (Nativo) | Celery + Redis | RQ (Redis Queue) | queue.Queue (Stdlib) |
|---|---|---|---|---|
| Dependencias de Broker Externo | Ninguna (0) | Redis / RabbitMQ | Redis Obligatorio | Ninguna |
| Persistencia ante Apagones | Sí (SQLite WAL Atómico) | Depende de configuración Redis | Depende de configuración Redis | No (Volátil en RAM) |
| Uso de Memoria en Reposo | < 15 MB | > 250 MB (Broker + Workers) | > 80 MB (Redis + Worker) | < 5 MB |
| Compatibilidad PEP 3148 Future | Sí (AsyncResult es Future) | API propia (AsyncResult) | API propia (Job) | No |
| Soporte Nativo await job | Sí (__await__ nativo) | Requiere librerías extra | No | No |
| Despliegue en Escritorio (Tauri / Electron) | Ideal (Embebido local) | Inviable sin servidor | Inviable sin servidor | Posible pero sin persistencia |
| Recuperación de Tareas Zombie | Automática en latido | Compleja (Visibility timeout) | Requiere worker supervisor | No |
| Dashboard Web Integrado | Sí (Cero config en puerto 8080) | Requiere Flower separado | Requiere RQ-Dashboard | No |
Qué Incluye Hoy el Monitor Web de GNQ
Servido nativamente por GNQMonitorHandler sin frameworks externos: seguridad de acceso, branding personalizable, 4 paneles operativos responsivos y control Zero-Downtime.
Login Blindado & Privacidad
Vista dedicada /login con cookies firmadas HMAC-SHA256 (HttpOnly, SameSite=Lax), HTTP Basic, API Bearer Token, validación CSRF, límite anti-DoS de 1 MB y ocultamiento estricto del origen/archivo de credenciales en /api/auth/session.
Branding Corporativo & Acerca de
Personalización en vivo vía /api/branding (#corp-banner con logo propio, fondo, color de acento, badge y footer guardados en gnq_config.json) preservando el emblema GNQ superior, junto al modal Información (v1.0.0, enlace oficial y crédito a Sochindep).
Telemetría Unificada & Responsividad
Tarjeta única en tiempo real con CPU %, RAM RSS, almacenamiento SQLite + WAL, hilos y uptime, modos Claro/Oscuro, idioma ES/EN completo, Pantalla Completa automática y grilla adaptable desde 320px (móvil 2×2) hasta TV.
Panel 1: Tareas, Workers & Detección
Filtros por estado/prioridad/búsqueda, vista Tabla o Tarjetas, inspección con cURL/JSON y modal Nueva Tarea inteligente (/api/tasks/schema) que autodetecta tareas del Worker o SQLite y el formato (args, [{...}], kwargs o híbrido).
Panel 2 & 3: Consola SQL + Logs Sin Duplicados
Consola SQLite redimensionable verticalmente (SELECT, PRAGMA y comandos stats/workers/health/purge/help) y terminal de Logs en Vivo deduplicada por transición de estado, mensajes completos hasta 1200 chars y salto de línea automático.
Panel 4: Directivas & Hot-Reload Canary
Editor en vivo de directivas operativas (/api/directives), inventario de extensiones y conectores (/api/extensions), prueba aislada Canary y botón Recargar Workers Zero-Downtime con Auto-Rollback automático.
Tan Simple como Pythonico
Elige tu caso de uso y comprueba cómo GNQ se adapta a tu arquitectura sin fricción.
from gnq import Queue, GNQWorker
# 1. Inicializa la cola persistente (crea gnq_tasks.sqlite automáticamente)
q = Queue("mis_tareas.sqlite")
# 2. Define la tarea con reintentos automáticos
@q.task(max_retries=3)
def procesar_transaccion(usuario_id, monto):
print(f"Procesando pago de ${monto} para usuario {usuario_id}...")
return {"status": "aprobado", "auth_code": 98412}
# 3. Encolar asíncronamente con prioridad y deduplicación atómica
job = procesar_transaccion.delay(450, 120.50, _priority=10, _unique_key="tx_450_984")
print(f"Tarea encolada con ID: {job.id}")
# 4. Iniciar el Worker (o ejecutarlo mediante 'gnq worker' en la terminal)
with GNQWorker(q, max_workers=4) as worker:
# Espera el resultado como un Future estándar
resultado = job.result(timeout=5.0)
print("Resultado:", resultado)
import asyncio
from gnq import Queue
q = Queue("app.sqlite")
@q.task()
def generar_reporte(datos):
# Tarea pesada ejecutada en hilo o proceso secundario
return {"filas": len(datos), "ok": True}
async def main():
job = generar_reporte.delay([1, 2, 3, 4, 5])
# Cumplimiento PEP 3156: 'await job' nativo sin bloquear el loop de asyncio
resultado = await job
print(f"Reporte listo vía await: {resultado}")
# Cumplimiento PEP 3148: callbacks estilo concurrent.futures.Future
job2 = generar_reporte.delay([10, 20])
job2.add_done_callback(lambda j: print(f"Callback completado para: {j.id}"))
asyncio.run(main())
# Patrón Desktop (Tauri / Electron / PyQt)
# El frontend encola y consulta por sondeo sin bloquear la ventana principal
from gnq import Queue, GNQWorker
q = Queue("app_desktop.sqlite")
# Iniciar worker en hilo secundario de la aplicación
worker = GNQWorker(q, max_workers=2)
worker.start(non_blocking=True)
# Cuando el usuario hace click en exportar:
def on_click_exportar():
job = exportar_pdf.delay("Balance_2026.pdf")
return {"job_id": job.id} # Retornado inmediatamente al frontend
# Polling desde JS/Tauri cada 300ms:
def consultar_progreso(job_id):
job = q[job_id] # Container protocol: q[id]
return {
"status": job.status,
"is_ready": job.is_ready,
"result": job.return_value if job.is_ready else None
}
# docker-compose.yml oficial de GNQ
services:
gnq:
image: sochindep/gnq:latest
restart: unless-stopped
command: ["server", "--db", "/data/gnq_tasks.sqlite", "--port", "8080", "--host", "0.0.0.0"]
volumes:
- gnq_storage:/data
ports:
- "8080:8080"
environment:
- GNQ_MONITOR_USER=admin
- GNQ_MONITOR_PASSWORD=super_secreto
healthcheck:
test: ["CMD", "gnq", "health", "--db", "/data/gnq_tasks.sqlite"]
interval: 15s
# Herramienta de línea de comandos incluida
# Iniciar worker con directorio confiable de plugins/conectores
$ gnq worker --db produccion.sqlite --workers 8 --concurrency threads --plugins-dir ./plugins
# Iniciar servidor Zero-Downtime (Supervisor Canary + Hot-Swap + Monitor HTTP)
$ gnq server --db produccion.sqlite --port 8080 --host 0.0.0.0 --hot-swap --plugins-dir ./plugins
# Iniciar únicamente el Monitor Web 2.0 con autenticación por archivo de configuración
$ gnq monitor --db produccion.sqlite --config gnq_config.json --port 8080
# Monitorear estado de tareas y workers conectados
$ gnq status --db produccion.sqlite
# Validar salud de la base de datos WAL (código de salida 0 o 1 para CI/CD)
$ gnq health --db produccion.sqlite
# Purgar tareas exitosas para optimizar almacenamiento
$ gnq purge --db produccion.sqlite --status SUCCESS
from gnq import Queue, BaseConnector, GNQWorkerSupervisor
q = Queue("campo_24_7.sqlite")
# 1. Actualizar reglas operativas en vivo sin reiniciar procesos
q.set_directive("alerta_rssi_umbral", -72, description="Sensibilidad BLE en cordillera")
@q.task()
def evaluar_sensor(rssi_dbm):
umbral = q.get_directive("alerta_rssi_umbral", -70)
return {"alerta": rssi_dbm >= umbral, "umbral_vivo": umbral}
# 2. Conector extensible para hardware o integraciones externas
class ConectorCampo(BaseConnector):
name = "telemetria_mina"
def poll(self, queue):
return 0
# 3. Recarga Zero-Downtime con validación Canary y Auto-Rollback
sup = GNQWorkerSupervisor(db_path="campo_24_7.sqlite", plugins_dir="./plugins")
sup.start()
resultado = sup.reload(reason="nuevo_conector_v2") # Si Canary falla, preserva el worker anterior
Integración con Flutter (Dart) & Redes Mesh
GNQ expone una API REST asíncrona y reactiva diseñada para comunicarse con aplicaciones móviles Flutter en Android, iOS y dispositivos periféricos sin dependencias pesadas.
// 1. Instanciación del Cliente GNQ en Flutter / Dart
final gnq = GNQClient(
baseUrl: 'http://10.0.2.2:8080', // Emulador Android (o localhost en iOS)
bearerToken: 'gnq_sec_token_tactico_2026', // Opcional según configuración
);
// 2. Encolado Atómico con Prioridad Máxima P10 y Deduplicación
final response = await gnq.enqueueTask(
taskName: 'procesar_avistamiento_mascota',
args: [
{
'collar_id': 'BLE-PET-DOG-77',
'lat': -33.4350,
'lon': -70.6250,
'rssi_dbm': -58,
'timestamp': DateTime.now().toIso8601String(),
}
],
priority: 10, // Salto inmediato al primer lugar de ejecución
uniqueKey: 'sighting_BLE-PET-DOG-77_window_42', // Deduplicación automática
);
print('Tarea encolada: ${response.id} | Deduplicada: ${response.deduplicated}');
// 3. Espera asíncrona de resultado (Future)
final result = await gnq.waitForCompletion(response.id);
print('Dueño notificado: ${result.result}');
// Red Comunitaria de Mascotas Perdidas: Detección Pasiva en Segundo Plano
void onBluetoothDeviceDiscovered(ScanResult result) async {
final deviceName = result.device.platformName;
if (deviceName.startsWith('BLE-PET-')) {
// 1. Obtener última posición GPS del teléfono transeúnte
final position = await Geolocator.getCurrentPosition();
// 2. Generar clave única para ventana de 30 segundos (evita spam de ráfaga)
final window = DateTime.now().millisecondsSinceEpoch ~/ 30000;
final deduplicationKey = 'mesh_${deviceName}_$window';
// 3. Despachar a GNQ con Prioridad P10
await gnq.enqueueTask(
taskName: 'procesar_avistamiento_mascota',
args: [{
'collar_id': deviceName,
'lat': position.latitude,
'lon': position.longitude,
'rssi_dbm': result.rssi,
}],
priority: 10,
uniqueKey: deduplicationKey,
);
}
}
// Resiliencia Offline: Guardar localmente y transmitir al recuperar conexión
class OfflineMeshDispatcher {
final LocalDatabase _sqlite = LocalDatabase();
Future<void> despacharConResiliencia(Map<String, dynamic> avistamiento) async {
final isOnline = await Connectivity().checkConnectivity() != ConnectivityResult.none;
if (isOnline) {
try {
await gnq.enqueueTask(taskName: 'procesar_avistamiento_mascota', args: [avistamiento]);
return;
} catch (_) {}
}
// En zona sin señal (catástrofe/sótano/parque): persistir en almacenamiento local
await _sqlite.insertPendingSighting(avistamiento);
}
}
// Guía de Direcciones IP para Conexión desde Flutter a Docker GNQ:
// -------------------------------------------------------------------------
// • Emulador Android Studio: http://10.0.2.2:8080
// • Simulador iOS / macOS: http://localhost:8080 o http://127.0.0.1:8080
// • Dispositivo Móvil Físico: http://<IP_DE_TU_MAC_EN_WIFI>:8080 (ej. 192.168.1.45:8080)
//
// Probar conectividad desde la terminal del móvil o Mac:
// $ curl -X GET http://localhost:8080/health
// -> {"status": "healthy", "sqlite": "ok", "active_workers": 4}
Docker, Microservicios y Contenedores
Despliega el motor concurrente de GNQ y el panel Monitor 2.0 con persistencia SQLite WAL y reinicio automático en segundos.
Despliegue en 1 Comando con Docker Compose
Monta el Worker de procesamiento y el Monitor Dashboard con autenticación segura y volumen persistente.
docker compose up -d
- Dashboard Web: http://localhost:8080
- API REST para Flutter:
POST /api/tasks - Healthcheck Nativo:
gnq health --db /data/gnq_tasks.sqlite - Almacenamiento WAL Persistente: Volumen Docker
gnq_storage:/data
Seguridad Operacional & Tokens
Configura credenciales y tokens mediante variables de entorno en tu archivo .env:
GNQ_MONITOR_USER=admin
GNQ_MONITOR_PASSWORD=super_clave_segura
GNQ_MONITOR_TOKEN=gnq_sec_token_tactico_2026
GNQ_MAX_WORKERS=4
GNQ_RETENTION_DAYS=7
Contratos de la API Python
Diseñada para ser instantáneamente familiar para desarrolladores habituados a concurrent.futures y Celery.
¿Buscas la Documentación Técnica Exhaustiva y de Estándar Python?
Accede al nuevo portal web con 41 secciones técnicas completas: arquitectura interna SQLite WAL, diagramas de ciclo de vida, hot-swap con Canary testing, motor de auto-limpieza, 10 ejemplos de código y matriz de troubleshooting.
-
@task(max_retries=0, name=None)Decorador para registrar funciones como tareas persistentes. Soporta nombres explícitos y cuotas de reintentos con backoff exponencial.
-
stats() -> dictDevuelve recuentos en tiempo real:
pending,running,success,failed,cancelledytotal. -
purge(status="SUCCESS") / clear(status="ALL")Limpia tareas terminadas para mantener la base de datos en tamaño óptimo de almacenamiento.
-
set_directive(key, value) / get_directive(key, default)Motor de reglas operativas en vivo (
gnq_directives) con versionado atómico en SQLite WAL para cambiar umbrales sin reiniciar procesos.
-
result(timeout=None)Bloquea de forma segura hasta obtener el retorno de la tarea o agotar el tiempo límite (lanza
GNQTimeoutError). -
await jobSoporte nativo para
asynciomediante el protocolo dunder__await__. No bloquea el loop de eventos. -
cancel() -> boolCancela una tarea si aún se encuentra en estado
PENDING. Cumple con la especificación PEP 3148.
-
GNQWorker(queue, max_workers, extension_registry)Worker multihilo o multiproceso con drenaje por
SIGTERM, recuperación de huérfanas y sondeo seguro de conectores. -
GNQWorkerSupervisor.reload()Orquesta validación Canary aislada, arranque Blue-Green del nuevo worker y Auto-Rollback si detecta fallos.
-
BLEReceiver(queue, task_name, debounce_seconds)Receptor de tramas Bluetooth con filtro antirrebote de hardware para evitar sobrecargas de CPU.
-
NFCTrigger(queue, task_name)Inyector de lecturas instantáneas de credenciales NFC por puerto USB o I2C.
-
BaseConnector / ExtensionRegistryContrato estándar (
connect,poll,health,close) y rutas seguras bajo/api/ext/*detrás de auth y CSRF. -
PluginLoader / validate_plugins_canaryCarga local verificada con SHA-256 / firma HMAC-SHA256, bloqueo de symlinks externos y verificación en subproceso scratch.
-
/api/tasks · /api/tasks/schema · /api/console · /api/logsGestión REST, detección automática de esquemas
args/kwargs, consola SQL y streaming deduplicado. -
/api/branding · /api/directives · /api/workers/reloadPersonalización corporativa persistente, reglas operativas en vivo y recarga Canary Zero-Downtime protegida por sesión.
Evolución del Proyecto y Futuras Etapas
El camino desde el desarrollo inicial hasta la meta de convertirse en candidata a módulo oficial de la Biblioteca Estándar de Python.
Núcleo Atómico y Resiliencia Inicial
Diseño del motor sobre SQLite en modo WAL, control de concurrencia con busy timeout de 30s, reintentos exponenciales, de-duplicación por clave única y sistema de auto-recuperación de tareas zombie tras cortes eléctricos.
Alineación PEP y Observabilidad Moderna
Transformación de GNQJob al protocolo concurrent.futures.Future (PEP 3148), soporte directo de await job (asyncio), pool de conexiones thread-local (73.4x más veloz), creación del Monitor Web Reactivo 2.0 y CLI de terminal unificado.
Continuidad 24/7, Monitor 2.0 & Hot-Swap Zero-Downtime
Endurecimiento industrial completo: auto-limpieza periódica y poda por cardinalidad (`Queue.maintenance()`), truncado WAL + incremental vacuum, Login HMAC-SHA256, branding corporativo, detección de esquemas en Nueva Tarea, Consola SQL redimensionable, Logs deduplicados, Directivas en vivo, Plugins firmados HMAC y Supervisor Canary con Auto-Rollback (65 pruebas unitarias).
Ecosistema Híbrido Desktop & Web Frameworks
Desarrollo de conectores empaquetados y hooks nativos para Tauri (Rust IPC) y Electron (IPC), junto con adaptadores zero-config para FastAPI, Flask y Django que permitan usar GNQ como backend de tareas sin instalar Redis.
Clústeres Edge Descentralizados P2P
Protocolo de sincronización de colas descentralizado punto a punto (P2P) entre dispositivos Edge (Raspberry Pi, micro-servidores en faenas subterráneas o flotas de rescate USAR) sin requerir un servidor central.
Postulación a Módulo Nativo de Python (Standard Library)
Presentación de la propuesta formal ante la Python Software Foundation (PSF) para incorporar GNQ bajo la biblioteca estándar (ej. concurrent.queue), llenando la brecha histórica entre colas en memoria y sistemas distribuidos pesados.
Checklist de Publicación Oficial (PyPI & GitHub)
Revisión exhaustiva de estándares requeridos para la distribución comunitaria e industrial.
py.typed).
Future).
await job en asyncio.
pyproject.toml y setup.py.
/login HMAC, Consola SQL, Logs deduplicados, Branding corporativo y autodetección de esquemas.
$ pip install --upgrade build twine
$ python3 -m build
$ twine check dist/*
$ twine upload dist/*