Socket.IO Client for Go Documentation¶

Welcome to the complete documentation for the Socket.IO client for Go. This library provides a full implementation of the Socket.IO v4 protocol.

🚀 Quick Start¶

First time using this library? Start here:

📘 Getting Started Guide - Install and create your first connection in 5 minutes

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

📚 Guides¶

Core Concepts¶

• Event System - Learn how to emit and listen to events, handle acknowledgments, and work with binary events

First Steps¶

1. Installation - How to install the library
2. Your First Connection - Connect and emit your first event
3. Core Concepts - Socket, events, namespaces, and lifecycle
4. Basic Configuration - Common configuration options

🔧 API Reference¶

Complete documentation for all public APIs:

Core¶

• Socket - Main Socket.IO client
• Creation and configuration
• Connection methods
• Event emission and reception

• State management

• Namespace - Multiplexed communication channels

• Namespace retrieval and usage
• Events per namespace

• Context isolation

• Options - Client configuration

• Authentication
• Timeouts and reconnection
• Custom headers

🎯 Advanced Usage¶

Advanced patterns and techniques for complex use cases:

• Advanced Namespaces
• Namespace architecture
• Implementation patterns
• Namespace manager

• Dynamic namespaces

• Acknowledgments

• Request-response pattern
• Timeout handling
• Multiple parallel requests

• Promise-like API

• Binary Events

• Efficient data transmission
• File upload/download
• Audio/video streaming

• Compression and checksums

• Automatic Reconnection

• Reconnection configuration
• Exponential backoff
• State re-synchronization
• Offline queue

📖 Examples by Use Case¶

By Functionality¶

By Level¶

Basic Level: - Simple connection - Emit and receive events - Disconnection handling

Intermediate Level: - Authentication - Acknowledgments - Multiple namespaces

Advanced Level: - Binary streaming - Custom reconnection - Offline queue

🎓 Recipes¶

Quick solutions for common problems:

Connection and Authentication¶

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

Error Handling¶

// Handle all possible errors
client.OnError(func(err error) {
  log.Println("Error:", err)
})

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

Connection State¶

// Check state before emitting
if client.IsConnected() {
  client.Emit("event", data)
} else {
  log.Println("Not connected, queuing...")
}

Request-Response¶

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

Multiple Namespaces¶

// Organize by functionality
chat := client.Of("/chat")
chat.On("message", handleChatMessage)

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

🔍 Quick Reference¶

By Method¶

By Event¶

By Option¶

🛠️ Troubleshooting¶

Common Issues¶

Not connecting: 1. Verify URL (should be ws:// or wss://) 2. Verify server is running 3. Check error logs with OnError()

Events not received: 1. Verify handler is registered before connection 2. Verify event name (case-sensitive) 3. Verify you're on the correct namespace

Acknowledgment timeout: 1. Increase AckTimeout in Options 2. Verify server responds correctly 3. Implement retry logic

Reconnection fails: 1. Verify reconnection configuration 2. Check OnReconnectError for reason 3. Implement state re-synchronization

Debugging¶

// Enable all event handlers
client.OnConnect(func() {
  log.Println("[DEBUG] Connected")
})

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

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

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

// Log all events
client.On("*", func(data ...interface{}) {
  log.Printf("[DEBUG] Event received: %v\n", data)
})

🤝 Compatibility¶

📊 Features¶

• ✅ Socket.IO v4 Protocol
• ✅ Engine.IO v4 with HTTP long-polling and WebSocket
• ✅ Namespaces for multiplexing
• ✅ Event acknowledgments with timeout
• ✅ Binary event transmission
• ✅ Authentication in handshake
• ✅ Automatic reconnection with exponential backoff
• ✅ Thread-safe with Go concurrency primitives
• ✅ Zero data races (validated with Go Race Detector)
• ✅ High performance (10,000+ events/second)

📝 Release Notes¶

v1.0.0 (Current) - Complete Socket.IO v4 implementation - Namespace and acknowledgment support - Automatic reconnection - Thread-safe and production-ready

🔗 Useful Links¶

• GitHub Repository
• GoDoc
• Examples
• Socket.IO Protocol

📄 License¶

MIT License - See LICENSE

Have questions? Open an issue on GitHub

Found a bug? Report the issue

Want to contribute? Read the Contribution Guide