Documentación Socket.IO Client para Go¶

Bienvenido a la documentación completa del cliente Socket.IO para Go. Esta librería proporciona una implementación completa del protocolo Socket.IO v4.

🚀 Inicio Rápido¶

¿Primera vez usando esta librería? Comienza aquí:

📘 Guía de Inicio Rápido - Instala y crea tu primera conexión en 5 minutos

client := socketio.New("ws://localhost:3000")
client.OnConnect(func() {
  client.Emit("hello", "world")
})

📚 Guías¶

Conceptos Fundamentales¶

• Sistema de Eventos - Aprende a emitir y escuchar eventos, manejar acknowledgments y trabajar con eventos binarios

Primeros Pasos¶

1. Instalación - Cómo instalar la librería
2. Tu Primera Conexión - Conectar y emitir tu primer evento
3. Conceptos Fundamentales - Socket, eventos, namespaces y ciclo de vida
4. Configuración Básica - Opciones comunes de configuración

🔧 API Reference¶

Documentación completa de todas las APIs públicas:

Core¶

• Socket - Cliente principal de Socket.IO
• Creación y configuración
• Métodos de conexión
• Emisión y recepción de eventos

• Manejo de estado

• Namespace - Canales de comunicación multiplexados

• Obtención y uso de namespaces
• Eventos por namespace

• Aislamiento de contexto

• Options - Configuración del cliente

• Autenticación
• Timeouts y reconexión
• Headers personalizados

🎯 Uso Avanzado¶

Patrones y técnicas avanzadas para casos de uso complejos:

• Namespaces Avanzados
• Arquitectura de namespaces
• Patrones de implementación
• Manager de namespaces

• Namespaces dinámicos

• Acknowledgments

• Patrón request-response
• Manejo de timeouts
• Múltiples requests paralelos

• Promise-like API

• Eventos Binarios

• Transmisión eficiente de datos
• Subida/descarga de archivos
• Streaming de audio/video

• Compresión y checksums

• Reconexión Automática

• Configuración de reconexión
• Backoff exponencial
• Re-sincronización de estado
• Offline queue

📖 Ejemplos por Caso de Uso¶

Por Funcionalidad¶

Por Nivel¶

Nivel Básico: - Conexión simple - Emitir y recibir eventos - Manejo de desconexión

Nivel Intermedio: - Autenticación - Acknowledgments - Namespaces múltiples

Nivel Avanzado: - Streaming binario - Reconexión personalizada - Offline queue

🎓 Recipes¶

Soluciones rápidas para problemas comunes:

Conexión y Autenticación¶

// Conectar con token JWT
client := socketio.New("ws://api.example.com", socketio.Options{
  Auth: map[string]interface{}{
    "token": "eyJhbGciOiJIUzI1NiIs...",
  },
})

Manejo de Errores¶

// Manejar todos los errores posibles
client.OnError(func(err error) {
  log.Println("Error:", err)
})

client.OnReconnectError(func(err error) {
  log.Println("Error reconectando:", err)
})

Estado de Conexión¶

// Verificar estado antes de emitir
if client.IsConnected() {
  client.Emit("event", data)
} else {
  log.Println("No conectado, encolando...")
}

Request-Response¶

// Solicitar datos con timeout
client.EmitWithAck("get-data", func(response ...interface{}) {
  if response == nil {
    log.Println("Timeout")
    return
  }
  data := response[0]
  processData(data)
}, "param")

Múltiples Namespaces¶

// Organizar por funcionalidad
chat := client.Of("/chat")
chat.On("message", handleChatMessage)

notifications := client.Of("/notifications")
notifications.On("alert", handleAlert)

🔍 Búsqueda Rápida¶

Por Método¶

Por Evento¶

Por Opción¶

🛠️ Troubleshooting¶

Problemas Comunes¶

No se conecta: 1. Verifica la URL (debe ser ws:// o wss://) 2. Verifica que el servidor esté corriendo 3. Revisa logs de errores con OnError()

Eventos no se reciben: 1. Verifica que el handler está registrado antes de la conexión 2. Verifica el nombre del evento (case-sensitive) 3. Verifica que estás en el namespace correcto

Timeout en acknowledgments: 1. Aumenta AckTimeout en Options 2. Verifica que el servidor responde correctamente 3. Implementa retry logic

Reconexión falla: 1. Verifica configuración de reconexión 2. Revisa OnReconnectError para ver razón 3. Implementa re-sincronización de estado

Debugging¶

// Habilitar todos los handlers de eventos
client.OnConnect(func() {
  log.Println("[DEBUG] Conectado")
})

client.OnDisconnect(func(reason string) {
  log.Printf("[DEBUG] Desconectado: %s\n", reason)
})

client.OnError(func(err error) {
  log.Printf("[DEBUG] Error: %v\n", err)
})

client.OnReconnectAttempt(func(attempt int) {
  log.Printf("[DEBUG] Reconectando... (#%d)\n", attempt)
})

// Logging de todos los eventos
client.On("*", func(data ...interface{}) {
  log.Printf("[DEBUG] Evento recibido: %v\n", data)
})

🤝 Compatibilidad¶

📊 Características¶

• ✅ Socket.IO v4 Protocol
• ✅ Engine.IO v4 con HTTP long-polling y WebSocket
• ✅ Namespaces para multiplexación
• ✅ Event acknowledgments con timeout
• ✅ Transmisión de eventos binarios
• ✅ Autenticación en handshake
• ✅ Reconexión automática con backoff exponencial
• ✅ Thread-safe con primitivas de concurrencia de Go
• ✅ Zero data races (validado con Go Race Detector)
• ✅ Alto rendimiento (10,000+ eventos/segundo)

📝 Notas de Versión¶

v1.0.0 (Actual) - Implementación completa de Socket.IO v4 - Soporte de namespaces y acknowledgments - Reconexión automática - Thread-safe y production-ready

🔗 Enlaces Útiles¶

• Repositorio GitHub
• GoDoc
• Ejemplos
• Socket.IO Protocol

📄 Licencia¶

MIT License - Ver LICENSE

¿Tienes preguntas? Abre un issue en GitHub

¿Encontraste un bug? Reporta el issue

¿Quieres contribuir? Lee la Guía de Contribución