Socket.IO Client for Go

This is the Socket.IO client implementation for Go, providing compatibility with Socket.IO v4 servers.

Table of Contents

• Installation
• Quick Start
• Documentation
• Usage
  • Basic Example
  • With Options
  • Namespaces
  • Acknowledgments
  • Binary Events
  • Error Handling
• Features
• Compatibility
• Examples
• Testing
• License

Installation

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

Requires Go 1.18 or later.

Quick Start

package main

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

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

    client.OnConnect(func() {
        fmt.Println("Connected")
        client.Emit("hello", "world")
    })

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

    select {} // Keep alive
}

Documentation

📚 Complete Documentation - Comprehensive guides, API reference, and advanced usage

🌐 Available in Multiple Languages

Documentation is available in:

• 🇬🇧 English (Default)
• 🇪🇸 Español
• 🇩🇪 Deutsch

Your language preference will be remembered across sessions.

Quick Links

• Getting Started Guide - Your first connection in 5 minutes
• Event System - Events, acknowledgments, and handlers
• API Reference - Complete API documentation
  • Socket API
  • Namespace API
  • Options API
• Advanced Usage - Advanced patterns and techniques
  • Namespaces
  • Acknowledgments
  • Binary Events
  • Reconnection

Usage

Basic Example

package main

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

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

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

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

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

    client.Emit("hello", "world")

    select {} // Keep alive
}

With Options

client := socketio.New("ws://localhost:3000", socketio.Options{
    Auth: map[string]interface{}{
        "token": "your-auth-token",
    },
    ReconnectAttempts: 5,
    ReconnectDelay:    time.Second,
    ReconnectDelayMax: 5 * time.Second,
    Timeout:           30 * time.Second,
})

Namespaces

// Connect to default namespace
client.On("news", func(data ...interface{}) {
    fmt.Printf("News: %v\n", data)
})

// Connect to custom namespace
chat := client.Of("/chat")
chat.OnConnect(func() {
    fmt.Println("Connected to chat namespace")
})

chat.On("message", func(data ...interface{}) {
    fmt.Printf("Chat message: %v\n", data)
})

chat.Emit("join", "room-123")

Acknowledgments

// Emit with acknowledgment
client.EmitWithAck("update", func(response ...interface{}) {
    fmt.Printf("Server acknowledged: %v\n", response)
}, "some", "data")

// Handle events that expect acknowledgment
client.On("question", func(data ...interface{}) {
    // Last argument is the ack callback
    if len(data) > 0 {
        if ack, ok := data[len(data)-1].(func(...interface{})); ok {
            ack("answer")
        }
    }
})

Binary Events

// Emit binary data
binaryData := []byte{1, 2, 3, 4, 5}
client.Of("/").EmitBinary("binary-event", binaryData, "additional", "data")

Error Handling

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

client.OnReconnectAttempt(func(attempt int) {
    fmt.Printf("Reconnection attempt %d\n", attempt)
})

client.OnReconnectError(func(err error) {
    fmt.Printf("Reconnection failed: %v\n", err)
})

client.OnReconnectFailed(func() {
    fmt.Println("All reconnection attempts failed")
})

Features

• Supports Socket.IO v4 protocol
• Engine.IO v4 with HTTP long-polling and WebSocket transport
• Namespaces for connection multiplexing
• Event acknowledgments with timeout support
• Binary event transmission
• Authentication during handshake
• Automatic reconnection with exponential backoff
• Production-ready thread-safety with Go's native concurrency primitives (sync.Map, atomic.Value, RWMutex)
• Room awareness
• Zero data races - Validated with Go Race Detector
• High performance - 10,000+ concurrent events/second

Compatibility

Socket.IO Server	Engine.IO	Status
v4.x	v4	Yes
v3.x	v4	Yes
v2.x	v3	Partial
v1.x	v2	No

Examples

The examples/ directory contains complete working examples for different use cases:

• basic/ - Simple connection and events
• acknowledgments/ - Request-response pattern with acks
• authentication/ - JWT token authentication
• binary/ - Binary data transmission
• chat/ - Real-time chat application
• namespaces/ - Multiple namespaces
• reconnection/ - Automatic reconnection handling
• rooms/ - Room-based messaging

Each example includes its own README with one-command execution.

cd examples/basic
go run .

Testing

Run all tests with a single command:

go run cmd/testrunner/main.go

Test types available:

• go run cmd/testrunner/main.go -type=unit - Unit tests only (no server required)
• go run cmd/testrunner/main.go -type=integration - Integration tests with real server
• go run cmd/testrunner/main.go -type=compliance - Socket.IO v4 protocol validation
• go run cmd/testrunner/main.go -type=stress - Performance and concurrency tests
• go run cmd/testrunner/main.go -type=all - Run all tests (default)

Add -race flag to enable race detector:

go run cmd/testrunner/main.go -race

Or run tests directly with go test:

go test -v -race -count=1 .

License

MIT