Guía de Inicio Rápido¶

Esta guía te ayudará a comenzar a usar el cliente Socket.IO para Go en menos de 5 minutos.

Instalación¶

Requiere Go 1.18 o superior.

go get github.com/arcaela/socket.io-client-go

Tu Primera Conexión¶

Crea un archivo main.go con el siguiente código:

package main

import (
  "fmt"
  socketio "github.com/arcaela/socket.io-client-go"
)

func main() {
  // Crear cliente
  client := socketio.New("ws://localhost:3000")
  defer client.Close()

  // Manejar conexión exitosa
  client.OnConnect(func() {
    fmt.Println("✅ Conectado al servidor")
  })

  // Manejar desconexión
  client.OnDisconnect(func(reason string) {
    fmt.Printf("❌ Desconectado: %s\n", reason)
  })

  // Escuchar evento del servidor
  client.On("welcome", func(data ...interface{}) {
    fmt.Printf("📩 Mensaje del servidor: %v\n", data[0])
  })

  // Emitir evento al servidor
  client.Emit("hello", "¡Hola desde Go!")

  // Mantener la aplicación ejecutándose
  select {}
}

Ejecuta tu aplicación:

go run main.go

Conceptos Fundamentales¶

Socket¶

El Socket es el cliente principal que maneja la conexión con el servidor Socket.IO. Se crea con socketio.New() y proporciona métodos para emitir y escuchar eventos.

client := socketio.New("ws://localhost:3000")

Eventos¶

Los eventos son mensajes que se envían entre cliente y servidor. Puedes escuchar eventos con On() y emitir eventos con Emit().

// Escuchar
client.On("message", func(data ...interface{}) {
  fmt.Println(data[0])
})

// Emitir
client.Emit("message", "Hola mundo")

Namespaces¶

Los namespaces permiten multiplexar conexiones sobre una única conexión WebSocket. El namespace por defecto es /.

// Namespace por defecto
client.On("news", handler)

// Namespace personalizado
chat := client.Of("/chat")
chat.On("message", handler)

Ciclo de Vida¶

La conexión tiene varios estados que puedes monitorear:

client.OnConnect(func() {
  fmt.Println("Conectado")
})

client.OnDisconnect(func(reason string) {
  fmt.Println("Desconectado:", reason)
})

client.OnError(func(err error) {
  fmt.Println("Error:", err)
})

Configuración Básica¶

Puedes personalizar el comportamiento del cliente con opciones:

client := socketio.New("ws://localhost:3000", socketio.Options{
  // Autenticación
  Auth: map[string]interface{}{
    "token": "tu-token-secreto",
  },

  // Reconexión automática
  ReconnectAttempts: 5,
  ReconnectDelay:    time.Second,
  ReconnectDelayMax: 5 * time.Second,

  // Timeouts
  Timeout:    30 * time.Second,
  AckTimeout: 5 * time.Second,
})

Patrones Comunes¶

Emit con Respuesta (Acknowledgment)¶

client.EmitWithAck("request", func(response ...interface{}) {
  fmt.Println("Respuesta del servidor:", response[0])
}, "datos de la petición")

Manejo de Reconexión¶

client.OnReconnectAttempt(func(attempt int) {
  fmt.Printf("Intento de reconexión #%d\n", attempt)
})

client.OnReconnectError(func(err error) {
  fmt.Println("Error en reconexión:", err)
})

client.OnReconnectFailed(func() {
  fmt.Println("Reconexión falló después de todos los intentos")
})

Verificar Estado de Conexión¶

if client.IsConnected() {
  fmt.Println("El cliente está conectado")
}

state := client.GetState()
// state puede ser: StateDisconnected, StateConnecting, StateConnected, etc.

Próximos Pasos¶

Ahora que tienes una conexión básica funcionando, explora:

Sistema de Eventos - Aprende sobre todos los eventos disponibles
Referencia de la API - Documentación completa de métodos
Uso Avanzado - Namespaces, acknowledgments y datos binarios
Configuración - Todas las opciones disponibles

Ejemplos Completos¶

El repositorio incluye ejemplos completos en la carpeta examples/:

examples/basic/ - Conexión y eventos básicos
examples/authentication/ - Autenticación con JWT
examples/chat/ - Aplicación de chat en tiempo real
examples/namespaces/ - Múltiples namespaces
examples/reconnection/ - Manejo de reconexión

Cada ejemplo se puede ejecutar con un solo comando:

cd examples/basic
go run .