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-setup-and-echo.md

View on GitHub
# WebSocket — Upgrader Setup & Basic Echo Handler

See also: `websocket-hub-and-client.md`, `websocket-auth-and-keepalive.md`, `websocket-shutdown-and-messages.md`, `websocket-testing.md`

## Overview

Gin handles the HTTP upgrade handshake through its normal routing and middleware chain. After upgrade, all communication is raw WebSocket — Gin is no longer involved.

## Upgrader Setup

`websocket.Upgrader` converts an HTTP connection to a WebSocket connection. Configure it once at the package level — it is safe to use concurrently.

```go
// internal/ws/upgrader.go
package ws

import (
    "net/http"

    "github.com/gorilla/websocket"
)

// upgrader is the shared upgrader for all WebSocket endpoints.
// ReadBufferSize / WriteBufferSize tune internal I/O buffers — not message
// size limits. 1024 bytes is a safe default for typical JSON payloads.
var upgrader = websocket.Upgrader{
    ReadBufferSize:  1024,
    WriteBufferSize: 1024,

    // CheckOrigin gates which origins may open a WebSocket connection.
    // Never return true unconditionally in production — that allows
    // cross-site WebSocket hijacking (CSWSH).
    CheckOrigin: func(r *http.Request) bool {
        origin := r.Header.Get("Origin")
        if origin == "" {
            return true
        }
        allowed := map[string]bool{
            "https://example.com":     true,
            "https://app.example.com": true,
        }
        return allowed[origin]
    },
}
```

**Why `CheckOrigin` matters:** Browsers automatically send the `Origin` header on WebSocket requests. Without validation, any website can open a WebSocket to your server using the visitor's credentials (cookies/sessions).

**`SetReadLimit`** — set a per-connection message size limit to prevent memory exhaustion:

```go
// After upgrading, before the read loop:
conn.SetReadLimit(512 * 1024) // 512 KB max per message
```

---

## Basic Echo Handler

The simplest handler: upgrade the connection, read messages in a loop, write each one back.

```go
// internal/ws/echo.go
package ws

import (
    "log/slog"

    "github.com/gin-gonic/gin"
    "github.com/gorilla/websocket"
)

// EchoHandler upgrades the HTTP connection and echoes every message back.
func EchoHandler(c *gin.Context) {
    conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
    if err != nil {
        // Upgrade already wrote a 400 response on failure; just log.
        slog.Error("websocket upgrade failed", "err", err)
        return
    }
    defer conn.Close()

    conn.SetReadLimit(512 * 1024)

    for {
        msgType, msg, err := conn.ReadMessage()
        if err != nil {
            if websocket.IsUnexpectedCloseError(err,
                websocket.CloseGoingAway,
                websocket.CloseNormalClosure,
            ) {
                slog.Warn("websocket read error", "err", err)
            }
            return
        }

        if err := conn.WriteMessage(msgType, msg); err != nil {
            slog.Warn("websocket write error", "err", err)
            return
        }
    }
}
```

Register the handler like any Gin route — middleware runs during the HTTP upgrade request:

```go
r := gin.New()
r.Use(middleware.Logger(), middleware.Recovery())
r.GET("/ws/echo", ws.EchoHandler)
```

**Why `IsUnexpectedCloseError`:** When a client disconnects cleanly, gorilla/websocket returns `CloseGoingAway`. Logging that as an error is noise. `IsUnexpectedCloseError` filters out expected close codes so you only log genuine errors.
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