Socket API Reference¶

El tipo Socket es el cliente principal que maneja la conexión con el servidor Socket.IO.

Tabla de Contenidos¶

Creación
Métodos de Conexión
Métodos de Eventos
Métodos de Emisión
Métodos de Estado
Métodos de Configuración

Creación¶

New¶

func New(rawURL string, options ...Options) *Socket

Crea una nueva instancia de Socket y establece la conexión con el servidor.

Parámetros: - rawURL (string): URL del servidor Socket.IO. Puede usar el esquema ws:// o http:// (se convertirá automáticamente a WebSocket) - options (Options, opcional): Configuración del cliente

Retorna: - *Socket: Instancia del cliente

Ejemplo:

// Conexión básica
client := socketio.New("ws://localhost:3000")

// Con opciones
client := socketio.New("ws://localhost:3000", socketio.Options{
  Auth: map[string]interface{}{
    "token": "abc123",
  },
  ReconnectAttempts: 5,
  Timeout: 30 * time.Second,
})

Métodos de Conexión¶

Close¶

func (s *Socket) Close() error

Cierra la conexión con el servidor y libera todos los recursos.

Retorna: - error: Error si la operación falla

Ejemplo:

defer client.Close()

// O manualmente
if err := client.Close(); err != nil {
  fmt.Printf("Error al cerrar: %v\n", err)
}

Métodos de Eventos¶

On¶

func (s *Socket) On(event string, handler EventHandler)

Registra un handler para escuchar un evento específico en el namespace por defecto (/).

Parámetros: - event (string): Nombre del evento - handler (EventHandler): Función que se ejecuta cuando se recibe el evento

Ejemplo:

client.On("message", func(data ...interface{}) {
  fmt.Printf("Mensaje: %v\n", data[0])
})

client.On("user-joined", func(data ...interface{}) {
  username := data[0].(string)
  fmt.Printf("%s se unió\n", username)
})

OnConnect¶

func (s *Socket) OnConnect(handler func())

Registra un handler que se ejecuta cuando la conexión se establece exitosamente.

Parámetros: - handler (func()): Función que se ejecuta al conectar

Ejemplo:

client.OnConnect(func() {
  fmt.Println("Conectado")
  client.Emit("join-room", "sala-1")
})

OnDisconnect¶

func (s *Socket) OnDisconnect(handler func(reason string))

Registra un handler que se ejecuta cuando la conexión se cierra.

Parámetros: - handler (func(reason string)): Función que recibe la razón de la desconexión

Ejemplo:

client.OnDisconnect(func(reason string) {
  fmt.Printf("Desconectado: %s\n", reason)

  if reason == "io server disconnect" {
    fmt.Println("El servidor cerró la conexión")
  }
})

OnError¶

func (s *Socket) OnError(handler func(err error))

Registra un handler que se ejecuta cuando ocurre un error.

Parámetros: - handler (func(err error)): Función que recibe el error

Ejemplo:

client.OnError(func(err error) {
  fmt.Printf("Error: %v\n", err)
})

OnReconnectAttempt¶

func (s *Socket) OnReconnectAttempt(handler func(attempt int))

Registra un handler que se ejecuta antes de cada intento de reconexión.

Parámetros: - handler (func(attempt int)): Función que recibe el número de intento

Ejemplo:

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

OnReconnect¶

func (s *Socket) OnReconnect(handler func(attempt int))

Registra un handler que se ejecuta cuando la reconexión es exitosa.

Parámetros: - handler (func(attempt int)): Función que recibe el número de intentos que tomó reconectar

Ejemplo:

client.OnReconnect(func(attempt int) {
  fmt.Printf("Reconectado después de %d intentos\n", attempt)
})

OnReconnectError¶

func (s *Socket) OnReconnectError(handler func(err error))

Registra un handler que se ejecuta cuando un intento de reconexión falla.

Parámetros: - handler (func(err error)): Función que recibe el error

Ejemplo:

client.OnReconnectError(func(err error) {
  fmt.Printf("Error en reconexión: %v\n", err)
})

OnReconnectFailed¶

func (s *Socket) OnReconnectFailed(handler func())

Registra un handler que se ejecuta cuando todos los intentos de reconexión fallan.

Parámetros: - handler (func()): Función que se ejecuta cuando la reconexión falla definitivamente

Ejemplo:

client.OnReconnectFailed(func() {
  fmt.Println("No se pudo reconectar")
  notifyUser("Conexión perdida")
})

Métodos de Emisión¶

Emit¶

func (s *Socket) Emit(event string, data ...interface{}) error

Emite un evento al servidor en el namespace por defecto (/).

Parámetros: - event (string): Nombre del evento - data (...interface{}): Argumentos a enviar (pueden ser múltiples)

Retorna: - error: Error si la operación falla

Ejemplo:

// Un argumento
client.Emit("message", "Hola mundo")

// Múltiples argumentos
client.Emit("user-action", "login", map[string]interface{}{
  "username": "juan",
  "timestamp": time.Now().Unix(),
})

// Manejar error
if err := client.Emit("important", data); err != nil {
  fmt.Printf("Error al emitir: %v\n", err)
}

EmitWithAck¶

func (s *Socket) EmitWithAck(event string, ack AckCallback, data ...interface{}) error

Emite un evento y espera una respuesta (acknowledgment) del servidor.

Parámetros: - event (string): Nombre del evento - ack (AckCallback): Función callback que recibe la respuesta - data (...interface{}): Argumentos a enviar

Retorna: - error: Error si la operación falla

Ejemplo:

client.EmitWithAck("get-user", func(response ...interface{}) {
  if len(response) == 0 {
    fmt.Println("No se recibió respuesta (timeout)")
    return
  }

  user := response[0].(map[string]interface{})
  fmt.Printf("Usuario: %v\n", user)
}, "user-123")

// Con timeout configurado
client := socketio.New("ws://localhost:3000", socketio.Options{
  AckTimeout: 5 * time.Second,
})

client.EmitWithAck("slow-operation", func(response ...interface{}) {
  if response == nil {
    fmt.Println("Timeout: el servidor no respondió a tiempo")
    return
  }
  fmt.Println("Respuesta:", response[0])
}, "datos")

Métodos de Estado¶

IsConnected¶

func (s *Socket) IsConnected() bool

Retorna si el cliente está actualmente conectado al servidor.

Retorna: - bool: true si está conectado, false en caso contrario

Ejemplo:

if client.IsConnected() {
  client.Emit("ping")
} else {
  fmt.Println("No hay conexión")
}

GetState¶

func (s *Socket) GetState() ConnectionState

Retorna el estado actual de la conexión.

Retorna: - ConnectionState: Estado actual de la conexión

Estados posibles: - StateDisconnected (0): Sin conexión - StateConnecting (1): Estableciendo conexión - StateConnected (2): Conectado - StateReconnecting (3): Intentando reconectar - StateDisconnecting (4): Cerrando conexión

Ejemplo:

state := client.GetState()

switch state {
case socketio.StateDisconnected:
  fmt.Println("Desconectado")
case socketio.StateConnecting:
  fmt.Println("Conectando...")
case socketio.StateConnected:
  fmt.Println("Conectado")
case socketio.StateReconnecting:
  fmt.Println("Reconectando...")
case socketio.StateDisconnecting:
  fmt.Println("Desconectando...")
}

GetReconnectCount¶

func (s *Socket) GetReconnectCount() int

Retorna el número de veces que el cliente ha intentado reconectar.

Retorna: - int: Contador de intentos de reconexión

Ejemplo:

count := client.GetReconnectCount()
fmt.Printf("Intentos de reconexión: %d\n", count)

// Usar en lógica de negocio
if count > 3 {
  fmt.Println("Múltiples intentos de reconexión, verifica tu conexión")
}

Métodos de Configuración¶

Of¶

func (s *Socket) Of(path string) *Namespace

Retorna una instancia de Namespace para el path especificado. Si el namespace no existe, lo crea.

Parámetros: - path (string): Path del namespace (debe comenzar con /)

Retorna: - *Namespace: Instancia del namespace

Ejemplo:

// Namespace por defecto
client.On("global-event", handler)

// Namespace personalizado
chat := client.Of("/chat")
chat.On("message", func(data ...interface{}) {
  fmt.Println("Mensaje de chat:", data[0])
})

chat.Emit("join", "sala-general")

// Múltiples namespaces
admin := client.Of("/admin")
admin.On("alert", adminHandler)

notifications := client.Of("/notifications")
notifications.On("new", notificationHandler)

Tipos Relacionados¶

EventHandler¶

type EventHandler func(data ...interface{})

Tipo de función para manejar eventos.

AckCallback¶

type AckCallback func(data ...interface{})

Tipo de función para manejar respuestas de acknowledgments.

ConnectionState¶

type ConnectionState int

const (
  StateDisconnected ConnectionState = iota
  StateConnecting
  StateConnected
  StateReconnecting
  StateDisconnecting
)

Estados posibles de la conexión.

Uso Thread-Safe¶

Todos los métodos de Socket son thread-safe y pueden ser llamados desde múltiples goroutines simultáneamente.

// Emitir desde múltiples goroutines
for i := 0; i < 10; i++ {
  go func(id int) {
    client.Emit("worker", map[string]interface{}{
      "id": id,
      "data": processData(id),
    })
  }(i)
}

// Escuchar eventos es thread-safe
client.On("result", func(data ...interface{}) {
  // Este handler puede ser llamado concurrentemente
  go processResult(data)
})

Ejemplo Completo¶

package main

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

func main() {
  // Crear cliente con opciones
  client := socketio.New("ws://localhost:3000", socketio.Options{
    Auth: map[string]interface{}{
      "token": "secret-token",
    },
    ReconnectAttempts: 5,
    ReconnectDelay:    time.Second,
    ReconnectDelayMax: 5 * time.Second,
    Timeout:           30 * time.Second,
    AckTimeout:        5 * time.Second,
  })
  defer client.Close()

  // Eventos del ciclo de vida
  client.OnConnect(func() {
    fmt.Println("✅ Conectado")

    // Emitir evento inicial
    client.Emit("join", "sala-principal")
  })

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

  client.OnError(func(err error) {
    fmt.Printf("⚠️  Error: %v\n", err)
  })

  // Eventos de reconexión
  client.OnReconnectAttempt(func(attempt int) {
    fmt.Printf("🔄 Intentando reconectar... (#%d)\n", attempt)
  })

  client.OnReconnect(func(attempt int) {
    fmt.Printf("✅ Reconectado después de %d intentos\n", attempt)
  })

  // Eventos personalizados
  client.On("message", func(data ...interface{}) {
    fmt.Printf("📩 Mensaje: %v\n", data[0])
  })

  client.On("user-joined", func(data ...interface{}) {
    username := data[0].(string)
    fmt.Printf("👤 %s se unió\n", username)
  })

  // Emitir con acknowledgment
  client.EmitWithAck("get-data", func(response ...interface{}) {
    if response == nil {
      fmt.Println("⏱️  Timeout esperando respuesta")
      return
    }
    fmt.Printf("📦 Datos recibidos: %v\n", response[0])
  }, "request-id-123")

  // Namespaces
  chat := client.Of("/chat")
  chat.On("message", func(data ...interface{}) {
    fmt.Printf("💬 Chat: %v\n", data[0])
  })

  // Verificar estado
  if client.IsConnected() {
    fmt.Println("Estado: Conectado")
  }

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

Socket API Reference¶

Tabla de Contenidos¶

Creación¶

New¶

Métodos de Conexión¶

Close¶

Métodos de Eventos¶

On¶

OnConnect¶

OnDisconnect¶

OnError¶

OnReconnectAttempt¶

OnReconnect¶

OnReconnectError¶

OnReconnectFailed¶

Métodos de Emisión¶

Emit¶

EmitWithAck¶

Métodos de Estado¶

IsConnected¶

GetState¶

GetReconnectCount¶

Métodos de Configuración¶

Of¶

Tipos Relacionados¶

EventHandler¶

AckCallback¶

ConnectionState¶

Uso Thread-Safe¶

Ejemplo Completo¶

Ver También¶