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-auth-and-keepalive.md
View on GitHub# WebSocket — Auth Before Upgrade & Ping/Pong Keepalive
See also: `websocket-setup-and-echo.md`, `websocket-hub-and-client.md`, `websocket-shutdown-and-messages.md`, `websocket-testing.md`
## Auth Before Upgrade
WebSocket has no standard mechanism for sending auth headers after the handshake. Authenticate during the HTTP upgrade request — before calling `upgrader.Upgrade()`. If auth fails, return a normal HTTP error response.
```go
// internal/ws/auth_handler.go
package ws
import (
"log/slog"
"net/http"
"github.com/gin-gonic/gin"
)
// AuthChatHandler validates a JWT from the query param before upgrading.
// Browsers cannot set custom headers on WebSocket connections — query params
// are the standard workaround. Keep tokens short-lived (< 60 s) when using
// them in URLs to reduce exposure in server logs.
func AuthChatHandler(hub *Hub, validateToken func(string) (string, error)) gin.HandlerFunc {
return func(c *gin.Context) {
token := c.Query("token")
if token == "" {
c.JSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
return
}
userID, err := validateToken(token)
if err != nil {
slog.Warn("ws auth failed", "err", err)
c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
return
}
conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
if err != nil {
slog.Error("ws upgrade failed", "err", err)
return
}
_ = userID // attach to Client struct as needed
client := &Client{
hub: hub,
conn: conn,
send: make(chan []byte, 256),
}
hub.register <- client
go client.writePump()
go client.readPump()
}
}
```
**Route registration — rate limiting applies to upgrade request:**
```go
wsGroup := r.Group("/ws")
wsGroup.Use(middleware.RateLimit())
{
wsGroup.GET("/chat", ws.AuthChatHandler(hub, tokenSvc.ValidateToken))
}
```
**Alternative — `Sec-WebSocket-Protocol` header:** Some clients send the token as a subprotocol name. This avoids URL exposure but requires echoing the subprotocol in the upgrade response header, which is more complex. Query param is simpler for most use cases.
---
## Ping/Pong Keepalive
Without keepalive, idle connections time out silently at the load balancer or OS level. gorilla/websocket supports WebSocket ping/pong control frames natively.
The `writePump` ticker in `websocket-hub-and-client.md` already sends pings. Here is the pattern isolated for clarity:
```go
// In readPump — reset read deadline when a pong arrives
conn.SetReadDeadline(time.Now().Add(pongWait)) // initial deadline
conn.SetPongHandler(func(appData string) error {
// Extend deadline: client is alive
conn.SetReadDeadline(time.Now().Add(pongWait))
return nil
})
// In writePump ticker case — send a ping
conn.SetWriteDeadline(time.Now().Add(writeWait))
if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil {
return // connection broken; writePump exits, triggering cleanup
}
```
**Deadline chain:** writePump sends ping every `pingPeriod` (54 s). Client must reply with pong before `pongWait` (60 s) expires. If pong never arrives, `ReadMessage` returns a deadline error and `readPump` exits, triggering `hub.unregister` and `conn.Close()`.
**Why `pingPeriod < pongWait`:** The ping must be sent before the read deadline fires. Using `(pongWait * 9) / 10` gives a 10% safety margin.
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 |