henriqueatila/golang-gin-best-practices / skills/golang-gin-api
golang-gin-api
VerifiedBuild REST APIs with Go Gin. Use when creating Go web servers, adding Gin routes, writing handlers, or asking about middleware, binding, error handling, or project structure.
references/websocket-hub-and-client.md
View on GitHub# WebSocket — Hub Pattern & Client readPump/writePump
See also: `websocket-setup-and-echo.md`, `websocket-auth-and-keepalive.md`, `websocket-shutdown-and-messages.md`, `websocket-testing.md`, `websocket-chat-handler.md`
## Hub Pattern
For broadcasting to multiple clients (chat rooms, live feeds), a central hub serializes all register/unregister/broadcast operations through a single goroutine — avoiding mutex-protected maps.
```go
// internal/ws/hub.go
package ws
type Hub struct {
clients map[*Client]bool
broadcast chan []byte
register chan *Client
unregister chan *Client
}
func NewHub() *Hub {
return &Hub{
clients: make(map[*Client]bool),
broadcast: make(chan []byte, 256),
register: make(chan *Client),
unregister: make(chan *Client),
}
}
// Run processes hub events. Call this in a dedicated goroutine.
func (h *Hub) Run() {
for {
select {
case client := <-h.register:
h.clients[client] = true
case client := <-h.unregister:
if _, ok := h.clients[client]; ok {
delete(h.clients, client)
close(client.send)
}
case message := <-h.broadcast:
for client := range h.clients {
select {
case client.send <- message:
default:
// send buffer full — client is too slow; drop and disconnect.
close(client.send)
delete(h.clients, client)
}
}
}
}
}
```
**Why channel-based (not mutex):** The hub goroutine owns the `clients` map exclusively. No locking needed. The `default` branch in broadcast prevents a slow client from blocking the entire broadcast loop.
---
## Client Struct with readPump / writePump
Two goroutines per client: `readPump` reads from the WebSocket, `writePump` writes to it. This avoids concurrent writes to `*websocket.Conn` (gorilla/websocket does not allow them).
```go
// internal/ws/client.go
package ws
import (
"log/slog"
"time"
"github.com/gin-gonic/gin"
"github.com/gorilla/websocket"
)
const (
writeWait = 10 * time.Second
pongWait = 60 * time.Second
pingPeriod = (pongWait * 9) / 10
maxMessageSize = 512 * 1024
)
type Client struct {
hub *Hub
conn *websocket.Conn
send chan []byte
}
func (cl *Client) readPump() {
defer func() {
cl.hub.unregister <- cl
cl.conn.Close()
}()
cl.conn.SetReadLimit(maxMessageSize)
cl.conn.SetReadDeadline(time.Now().Add(pongWait))
cl.conn.SetPongHandler(func(string) error {
cl.conn.SetReadDeadline(time.Now().Add(pongWait))
return nil
})
for {
_, msg, err := cl.conn.ReadMessage()
if err != nil {
if websocket.IsUnexpectedCloseError(err,
websocket.CloseGoingAway,
websocket.CloseNormalClosure,
) {
slog.Warn("ws read error", "err", err)
}
return
}
cl.hub.broadcast <- msg
}
}
func (cl *Client) writePump() {
ticker := time.NewTicker(pingPeriod)
defer func() {
ticker.Stop()
cl.conn.Close()
}()
for {
select {
case msg, ok := <-cl.send:
cl.conn.SetWriteDeadline(time.Now().Add(writeWait))
if !ok {
cl.conn.WriteMessage(websocket.CloseMessage, []byte{})
return
}
if err := cl.conn.WriteMessage(websocket.TextMessage, msg); err != nil {
slog.Warn("ws write error", "err", err)
return
}
case <-ticker.C:
cl.conn.SetWriteDeadline(time.Now().Add(writeWait))
if err := cl.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
return
}
}
}
}
```
See also: `websocket-chat-handler.md` for `ChatHandler` wiring.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |