Conexión WebSocket

La comunicación entre el portal Unimate y los agentes instalados en equipos Windows se realiza a través de conexiones WebSocket, permitiendo comunicación bidireccional en tiempo real para la ejecución de bots y monitoreo de estado.

Arquitectura de Comunicación

Flujo de comunicación:

Portal Unimate (Web)
│
├── WebSocket Server (wss://portal.unimate.com/ws)
│
└── Conexión Persistente
    │
    ▼
Agente Windows (Cliente)
│
├── WebSocket Client
├── Bot Executor
└── Log Streamer

Características de la conexión:

  • Segura: Usa protocolo WSS (WebSocket Secure) con TLS

  • Tiempo real: Latencia mínima para comandos e información

  • Persistente: Conexión mantenida activamente

  • Autenticada: Token JWT para identificación del agente

  • Bidireccional: Envío y recepción simultánea de mensajes

Establecimiento de Conexión

Proceso de handshake:

  1. Agente inicia conexión WebSocket al portal

  2. Envía token de autenticación en headers

  3. Portal valida token y permisos del agente

  4. Establece canal de comunicación

  5. Confirma estado «Conectado» en ambos extremos

Ejemplo de handshake:

// Headers de conexión WebSocket
{
    "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...",
    "Agent-ID": "WIN-DESKTOP-01",
    "Agent-Version": "2.1.0",
    "Python-Version": "3.9.7"
}

Respuesta del servidor:

{
    "type": "connection_established",
    "agent_id": "WIN-DESKTOP-01",
    "server_time": "2024-12-20T15:30:00Z",
    "features": ["bot_execution", "live_logs", "file_transfer"],
    "status": "connected"
}

Tipos de Mensajes

Mensajes del Portal al Agente

Ejecución de Bot

{
    "type": "execute_bot",
    "execution_id": "exec_123456",
    "bot_id": "bot_procesador_v2",
    "bot_zip_url": "https://storage.unimate.com/bots/bot_procesador_v2.zip",
    "parameters": {
        "archivo": "datos.xlsx",
        "formato": "CSV",
        "limite": 1000
    },
    "timeout": 1800,
    "notify_progress": true
}

Heartbeat (Keep-alive)

{
    "type": "ping",
    "timestamp": "2024-12-20T15:30:15Z"
}

Mensajes del Agente al Portal

Confirmación de Comando

{
    "type": "command_ack",
    "execution_id": "exec_123456",
    "status": "started",
    "pid": 12345,
    "started_at": "2024-12-20T15:30:20Z"
}

Actualización de Progreso

{
    "type": "progress_update",
    "execution_id": "exec_123456",
    "progress_percent": 45,
    "current_step": "Procesando archivo datos.xlsx",
    "processed_records": 450,
    "total_records": 1000
}

Logs en Tiempo Real

{
    "type": "log_message",
    "execution_id": "exec_123456",
    "level": "INFO",
    "message": "Iniciando procesamiento de datos",
    "timestamp": "2024-12-20T15:30:22Z",
    "source": "main.py:25"
}

Finalización de Ejecución

{
    "type": "execution_completed",
    "execution_id": "exec_123456",
    "status": "success",
    "exit_code": 0,
    "duration_seconds": 180,
    "output_files": [
        "resultado.csv",
        "reporte.pdf"
    ],
    "final_message": "Procesamiento completado exitosamente"
}

Manejo de Reconexión

El agente implementa reconexión automática.

Estrategia de Reconexión

class WebSocketReconnector:
    def __init__(self):
        self.retry_intervals = [1, 2, 5, 10, 30, 60]  # segundos
        self.max_retries = 6

    async def connect_with_retry(self):
        for attempt in range(self.max_retries):
            try:
                await self.connect()
                return True
            except Exception as e:
                wait_time = self.retry_intervals[min(attempt, len(self.retry_intervals)-1)]
                await asyncio.sleep(wait_time)
        return False

Cola de Mensajes

Durante desconexiones temporales:

  • Mensajes entrantes: Se almacenan en el servidor y se envían al reconectar

  • Mensajes salientes: Se guardan localmente en cola FIFO

  • Timeout: Mensajes antiguos se descartan después de 1 hora

Seguridad

Autenticación

  • JWT Tokens: Firmados con clave secreta del servidor

  • Rotación: Tokens renovados cada 24 horas automáticamente

  • Scopes: Permisos limitados por agente (read, execute, log)

Validación

# Validaciones del servidor para cada mensaje:
def validate_message(message, agent):
    # 1. Verificar formato JSON válido
    # 2. Verificar tipo de mensaje permitido
    # 3. Verificar permisos del agente
    # 4. Verificar parámetros obligatorios
    # 5. Verificar límites de rate-limiting

Cifrado

  • TLS 1.3: Conexión cifrada extremo a extremo

  • Certificados: Validación de certificado del servidor

  • Headers firmados: Integridad de metadatos

Monitoreo y Métricas

Métricas de Conexión

El portal monitorea:

  • Latencia: Tiempo de respuesta ping/pong

  • Throughput: Mensajes por segundo

  • Estabilidad: Tiempo sin desconexiones

  • Errores: Tasa de mensajes fallidos

Alertas Automáticas

  • Agente desconectado > 5 minutos

  • Latencia alta > 500ms consistente

  • Errores de conexión > 10% en 1 hora

  • Cola de mensajes > 100 pendientes

Debugging y Troubleshooting

Logs de Conexión

En el agente (Windows):

[2024-12-20 15:30:00] INFO: Iniciando conexión WebSocket...
[2024-12-20 15:30:01] INFO: Conectado a wss://portal.unimate.com/ws
[2024-12-20 15:30:02] INFO: Autenticación exitosa - Agent ID: WIN-DESKTOP-01
[2024-12-20 15:30:03] INFO: Heartbeat establecido - Intervalo: 30s

En el portal (Servidor):

[2024-12-20 15:30:01] INFO: Nueva conexión WebSocket desde 192.168.1.100
[2024-12-20 15:30:02] INFO: Agente WIN-DESKTOP-01 autenticado exitosamente
[2024-12-20 15:30:03] INFO: Agente registrado - Status: ONLINE

Diagnósticos Comunes

Problemas y Soluciones

Problema

Síntoma

Solución

No conecta

«Connection refused»

Verificar URL y puerto

Token inválido

«Authentication failed»

Generar nuevo token

Desconexiones frecuentes

«Connection drops»

Revisar firewall/proxy

Mensajes perdidos

«Timeouts»

Verificar estabilidad de red

Herramientas de Debug

# Test de conectividad desde agente
telnet portal.unimate.com 443

# Verificar certificados SSL
openssl s_client -connect portal.unimate.com:443

# Monitor de tráfico WebSocket (Chrome DevTools)
# Network -> WS -> Ver mensajes en tiempo real

Optimización de Performance

Mejores Prácticas

  • Batch messages: Agrupar logs múltiples en un mensaje

  • Compresión: Usar compresión gzip para mensajes grandes

  • Throttling: Limitar frecuencia de actualizaciones de progreso

  • Heartbeat óptimo: Balance entre detectar desconexiones y overhead

Configuración Recomendada

{
    "heartbeat_interval": 30,
    "message_batch_size": 10,
    "compression": true,
    "progress_update_throttle": 2,
    "log_buffer_size": 1000,
    "reconnect_max_attempts": 6
}