Skip to content

henriqueatila/golang-gin-best-practices / skills/golang-gin-api

golang-gin-api

Verified

Build 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.

FileKindSize
SKILL.mdskill md10.0 KB
metadata.jsonconfig482 B
references/background-jobs-goroutine-and-pool.mdmarkdown3.5 KB
references/background-jobs-queue-and-shutdown.mdmarkdown3.5 KB
references/defensive-handler-patterns.mdmarkdown3.7 KB
references/error-handling-apperror.mdmarkdown4.1 KB
references/error-handling-recovery.mdmarkdown1.8 KB
references/error-handling-validation.mdmarkdown3.0 KB
references/file-uploads-cloud.mdmarkdown2.4 KB
references/file-uploads-local.mdmarkdown4.0 KB
references/middleware-core.mdmarkdown4.2 KB
references/middleware-logging-and-recovery.mdmarkdown3.3 KB
references/middleware-timeout-and-custom.mdmarkdown3.2 KB
references/rate-limiting-algorithms.mdmarkdown3.5 KB
references/rate-limiting-fallback.mdmarkdown2.3 KB
references/rate-limiting-headers.mdmarkdown1.8 KB
references/rate-limiting-peruser.mdmarkdown2.4 KB
references/rate-limiting-redis-sliding.mdmarkdown2.2 KB
references/rate-limiting-redis.mdmarkdown2.9 KB
references/rate-limiting-sliding-window.mdmarkdown2.2 KB
references/rate-limiting-tiered.mdmarkdown3.0 KB
references/routing-groups-and-versioning.mdmarkdown3.8 KB
references/routing-params-and-wildcards.mdmarkdown3.4 KB
references/routing-validators-and-limits.mdmarkdown2.4 KB
references/safe-context-extraction.mdmarkdown4.3 KB
references/server-handlers-and-errors.mdmarkdown3.6 KB
references/server-setup-and-routes.mdmarkdown3.9 KB
references/websocket-auth-and-keepalive.mdmarkdown3.5 KB
references/websocket-chat-handler.mdmarkdown1.5 KB
references/websocket-hub-and-client.mdmarkdown3.9 KB
references/websocket-setup-and-echo.mdmarkdown3.4 KB
references/websocket-shutdown-and-messages.mdmarkdown3.8 KB
references/websocket-testing.mdmarkdown3.8 KB

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.
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall