GoSocket

The simplest way to add WebSockets to your Go application

Stop writing WebSocket boilerplate. Start building features.

// That's it. You have a working WebSocket server.
ws, _ := gosocket.NewServer(
    gosocket.WithPort(8080),
    gosocket.OnMessage(func(client *gosocket.Client, message *gosocket.Message, ctx *gosocket.Context) error {
        client.Send(message.RawData) // Echo back
        return nil
    }),
)
log.Fatal(ws.Start())

---

Why GoSocket?

GoSocket focuses on developer experience and getting started quickly:

• Minimal boilerplate - Get a WebSocket server running in a few lines
• Built-in features - Rooms, broadcasting, and client management included
• Middleware support: Add auth, logging, CORS, whatever you need
• Simple API - Intuitive methods that do what you expect
• Flexible - Use standalone or integrate with existing HTTP servers
• Multiple servers: Run chat, notifications, and admin panels on different ports simultaneously

Quick Start

Installation

go get -u github.com/FilipeJohansson/gosocket@latest

Standalone Server

Perfect for dedicated WebSocket services:

package main

import (
    "fmt"
    "log"
    "github.com/FilipeJohansson/gosocket"
)

func main() {
    ws, err := gosocket.NewServer(
        gosocket.WithPort(8080),
        gosocket.WithPath("/ws"),
        gosocket.OnConnect(func(client *gosocket.Client, ctx *gosocket.Context) error {
            fmt.Printf("Client %s connected\n", client.ID)
            return nil
        }),
        gosocket.OnMessage(func(client *gosocket.Client, message *gosocket.Message, ctx *gosocket.Context) error {
            // Broadcast to all clients
            ctx.Hub().BroadcastMessage(gosocket.NewRawMessage(gosocket.TextMessage, message.RawData))
            return nil
        }),
        gosocket.OnDisconnect(func(client *gosocket.Client, ctx *gosocket.Context) error {
            fmt.Printf("Client %s disconnected\n", client.ID)
            return nil
        }),
    )

    if err != nil {
        // Something wrong with the server configuration
    }
    
    log.Fatal(ws.Start())
}

Integrate with Existing HTTP Server

Perfect for adding real-time features to REST APIs:

package main

import (
    "net/http"
    "github.com/FilipeJohansson/gosocket"
)

func main() {
    // Your existing routes
    http.HandleFunc("/api/users", getUsersHandler)
    
    // Add WebSocket endpoint
    ws, err := gosocket.NewHandler(
        gosocket.OnMessage(func(client *gosocket.Client, message *gosocket.Message, ctx *gosocket.Context) error {
            client.Send(message.RawData)
            return nil
        }),
    )

    if err != nil {
        // Something wrong with the handler configuration
    }
    
    http.Handle("/ws", ws)
    http.ListenAndServe(":8080", nil)
}

Middleware Support

Add authentication, logging, CORS, and more:

ws, _ := gosocket.NewServer(
    gosocket.WithPort(8080),
    gosocket.WithAuth(AuthMiddleware),
    gosocket.WithMiddleware(LoggingMiddleware),
    gosocket.OnConnect(func(client *gosocket.Client, ctx *gosocket.Context) error {
        fmt.Printf("Authenticated client connected: %s\n", client.ID)
        return nil
    }),
)

Rooms & Broadcasting

gosocket.OnConnect(func(client *gosocket.Client, ctx *gosocket.Context) error {
    client.JoinRoom("general")
    return nil
})

gosocket.OnMessage(func(client *gosocket.Client, message *gosocket.Message, ctx *gosocket.Context) error {
    // Send to specific room
    ctx.Hub().BroadcastToRoom("general", gosocket.NewRawMessage(gosocket.TextMessage, message.RawData))
    
    // Send to specific client
    client.Send([]byte("ACK"))
    
    // Send to everyone
    ctx.Hub().BroadcastMessage(gosocket.NewRawMessage(gosocket.TextMessage, []byte("Global announcement")))
    
    return nil
})

Real-World Examples

• Chat Application - Multi-room chat with rooms
• Live Notifications - Push notifications to web clients
• Game Lobby - Real-time multiplayer coordination
• Stock Ticker - Live data streaming
• Middleware Example - Authentication and logging middleware
• Gin Integration - Add WebSockets to Gin apps

Features

• Quick Setup - Minimal code to get started
• Built-in Rooms - Join/leave rooms without manual management
• Broadcasting - Send to all clients, rooms, or individuals
• Flexible Integration - Standalone server or HTTP handler
• Multiple Encodings - JSON ready, Protobuf & MessagePack coming

Roadmap to v1.0.0

Status	Feature
✅ Completed	WebSocket server + middleware
✅ Completed	Rooms and broadcasting
🔄 In Progress	Rate limiting, logging and other improvements
⚪ Planned	Protobuf & MessagePack support
⚪ Planned	Clustering & high availability
⚪ Planned	Monitoring & metrics
⚪ Planned	Performance benchmarks

Note: These are the key steps we need to complete before GoSocket reaches v1.0.0. Once all planned features are implemented and thoroughly tested, we aim to release the first stable version.

Contributing

We're actively looking for contributors! Areas where you can help:

• Documentation: Improve examples and guides
• Testing: Write tests and benchmarks
• Features: Help implement features listed in the roadmap section
• Bug fixes: Report and fix issues

Check out CONTRIBUTING.md to get started.

License

MIT License - see LICENSE for details.

---

Love GoSocket? Give us a ⭐ and help spread the word!

🐦 Tweet • 📺 Demo • 💬 Discussions