@eltonssouza/development-utility-kit 0.10.0

package/.claude/stacks/go/gin-1.10.md

@@ -0,0 +1,570 @@
+---
+stack: go/gin-1.10
+versions_covered: "1.10.x — 1.12.x"
+last_validated: 2026-05-28
+validated_against: "reference pack — Go 1.23 + Gin 1.10 + GORM 1.25 + golang-migrate 4.18"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-28
+next_review_due: 2027-05-28
+---
+
+# Go 1.23+ + Gin 1.10+
+
+Canonical knowledge pack for Go HTTP services on Gin 1.10+. Gin is the right pick when the service is HTTP-heavy with middleware-friendly routing and modest dependency footprint. For projects targeting standard `net/http` + chi or echo, the patterns transfer with minor mechanical changes; this pack assumes Gin.
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: Go 1.23+ + Gin 1.10+` in `## Project Identity`.
+- `go.mod` declares `go 1.23` (or newer) and a direct dependency on `github.com/gin-gonic/gin v1.10.x`.
+- Service is API-first (REST), modest throughput target (Gin can handle 50k+ req/s with care; for extreme throughput consider `fasthttp` or hand-rolled `net/http`).
+- For pure CLI / batch jobs without HTTP: do not use this pack — use a plain Go project with cobra/urfave-cli.
+- For full-stack with server-rendered HTML: not Gin's strength; consider `templ` + chi or Buffalo.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Go | 1.23 (min) / 1.24 (latest stable) | Generics maduros; iterators (range-over-func) na 1.23; toolchain directive in go.mod |
+| Gin | 1.10.x — 1.12.x | Stable middleware API; HTTP/2 native; `gin.Context` is the canonical handler signature |
+| ORM | GORM 1.25.x | OR `sqlc` (typed queries from SQL) for SQL purists |
+| Migrations | golang-migrate 4.18.x | Pure-Go; embedded SQL files via `embed.FS` |
+| Validation | `go-playground/validator` 10.x | Used by Gin's `c.ShouldBindJSON()`; struct tag-driven |
+| Build | `go build` + Makefile | Module mode mandatory; `go mod tidy` in CI |
+| Tests | `testing` stdlib + `testify` 1.10.x | `gomock` 0.5 for mocking; Testcontainers Go 0.34 for integration |
+| Mutation | `go-mutesting` (community) | Target ≥70% on `domain/` + `application/` |
+| Coverage | `go test -coverprofile=cov.out -covermode=atomic` | Target ≥85% lines (`go tool cover -func=cov.out`) |
+| Static analysis | `golangci-lint` v1.61+ (or `v2.0+`) | Bundles 50+ linters; `revive`, `govet`, `staticcheck`, `gosec` |
+| Security scan | `govulncheck` (golang.org/x/vuln) + `gosec` | `govulncheck ./...` checks CVE in code path; `gosec` scans code patterns |
+| Observability | OpenTelemetry SDK + `otelgin` middleware | W3C Trace Context; auto-instruments HTTP, GORM, http.Client |
+| HTTP client | `net/http` with `&http.Client{Timeout: 10*time.Second}` | NEVER `http.Get(url)` directly (no timeout = leaked goroutines) |
+| Config | `kelseyhightower/envconfig` OR `spf13/viper` | env-driven; validated at startup |
+
+## 3. Project structure (DDD / hexagonal)
+
+```
+service/
+├── go.mod
+├── go.sum
+├── Makefile
+├── cmd/
+│   └── server/
+│       └── main.go               # bootstrap: cfg → DI graph → start gin
+├── internal/                     # not importable by other modules
+│   ├── domain/                   # pure Go; no Gin, no GORM
+│   │   ├── product/
+│   │   │   ├── entity.go
+│   │   │   ├── repository.go     # interface
+│   │   │   └── service.go        # pure domain service
+│   │   └── shared/
+│   ├── application/              # use cases (1 method per type)
+│   │   ├── product/
+│   │   │   ├── create_product.go
+│   │   │   └── list_products.go
+│   │   └── shared/
+│   ├── infrastructure/           # GORM, http.Client, AWS SDK, etc.
+│   │   ├── db/
+│   │   │   ├── gorm.go           # *gorm.DB initializer
+│   │   │   └── migration.go      # golang-migrate runner
+│   │   ├── product/
+│   │   │   ├── model.go          # GORM struct
+│   │   │   └── repository.go     # adapter for domain.Repository
+│   │   └── http/
+│   │       └── client.go         # shared http.Client
+│   ├── api/                      # Gin routes + handlers + DTOs
+│   │   ├── product/
+│   │   │   ├── handler.go
+│   │   │   ├── dto.go            # request/response structs
+│   │   │   └── router.go
+│   │   └── shared/
+│   │       ├── error_handler.go  # RFC 9457 ProblemDetails
+│   │       └── middleware.go
+│   └── config/
+│       └── config.go             # envconfig struct
+├── migrations/                   # SQL files for golang-migrate
+│   ├── 000001_create_products.up.sql
+│   └── 000001_create_products.down.sql
+└── tests/
+    ├── unit/
+    ├── integration/
+    └── e2e/
+```
+
+**Rule**: `internal/` makes the layers un-importable by other modules. `domain/` and `application/` contain **zero Gin and zero GORM imports** — pure Go testable without any infra. `infrastructure/` is the only place importing `gorm.io/...`. `api/` is the only place importing `gin-gonic/gin`.
+
+## 4. Code patterns
+
+### Domain entity (no GORM, no Gin)
+
+```go
+// internal/domain/product/entity.go
+package product
+
+import (
+    "errors"
+    "time"
+    "github.com/google/uuid"
+)
+
+type Product struct {
+    ID        uuid.UUID
+    Name      string
+    Price     int64 // cents — never float for money
+    Stock     int
+    CreatedAt time.Time
+}
+
+func (p Product) Reserve(qty int) (Product, error) {
+    if qty <= 0 {
+        return Product{}, errors.New("qty must be positive")
+    }
+    if qty > p.Stock {
+        return Product{}, errors.New("insufficient stock")
+    }
+    p.Stock -= qty
+    return p, nil
+}
+```
+
+**Rule**: money in `int64` cents (or `decimal.Decimal` if shopspring/decimal is acceptable). NEVER `float64` for money — precision loss is real. Domain methods take and return value types; immutability by convention.
+
+### Domain port (interface) + infrastructure adapter
+
+```go
+// internal/domain/product/repository.go
+package product
+
+import (
+    "context"
+    "github.com/google/uuid"
+)
+
+type Repository interface {
+    Get(ctx context.Context, id uuid.UUID) (*Product, error)
+    Save(ctx context.Context, p Product) error
+}
+```
+
+```go
+// internal/infrastructure/product/model.go
+package product
+
+import (
+    "time"
+    "github.com/google/uuid"
+)
+
+type ProductGORM struct {
+    ID        uuid.UUID `gorm:"type:uuid;primaryKey"`
+    Name      string    `gorm:"size:120;index"`
+    Price     int64
+    Stock     int
+    CreatedAt time.Time
+}
+
+func (ProductGORM) TableName() string { return "products" }
+```
+
+```go
+// internal/infrastructure/product/repository.go
+package product
+
+import (
+    "context"
+    "errors"
+    "github.com/google/uuid"
+    "gorm.io/gorm"
+    domain "service/internal/domain/product"
+)
+
+type GormRepository struct {
+    db *gorm.DB
+}
+
+func New(db *gorm.DB) *GormRepository {
+    return &GormRepository{db: db}
+}
+
+func (r *GormRepository) Get(ctx context.Context, id uuid.UUID) (*domain.Product, error) {
+    var row ProductGORM
+    if err := r.db.WithContext(ctx).First(&row, "id = ?", id).Error; err != nil {
+        if errors.Is(err, gorm.ErrRecordNotFound) {
+            return nil, nil
+        }
+        return nil, err
+    }
+    return toDomain(row), nil
+}
+
+func (r *GormRepository) Save(ctx context.Context, p domain.Product) error {
+    row := ProductGORM{
+        ID: p.ID, Name: p.Name, Price: p.Price, Stock: p.Stock, CreatedAt: p.CreatedAt,
+    }
+    return r.db.WithContext(ctx).Save(&row).Error
+}
+
+func toDomain(r ProductGORM) *domain.Product {
+    return &domain.Product{
+        ID: r.ID, Name: r.Name, Price: r.Price, Stock: r.Stock, CreatedAt: r.CreatedAt,
+    }
+}
+```
+
+**Rule**: domain `Repository` is an interface in `domain/`. Implementation in `infrastructure/`. Use cases depend on the interface. UUID primary key — never auto-increment for distributed systems.
+
+### Gin handler (thin)
+
+```go
+// internal/api/product/dto.go
+package product
+
+import "time"
+
+type CreateProductRequest struct {
+    Name  string `json:"name"  binding:"required,min=1,max=120"`
+    Price int64  `json:"price" binding:"required,gt=0"`
+    Stock int    `json:"stock" binding:"gte=0"`
+}
+
+type ProductResponse struct {
+    ID        string    `json:"id"`
+    Name      string    `json:"name"`
+    Price     int64     `json:"price"`
+    Stock     int       `json:"stock"`
+    CreatedAt time.Time `json:"created_at"`
+}
+```
+
+```go
+// internal/api/product/handler.go
+package product
+
+import (
+    "net/http"
+    "github.com/gin-gonic/gin"
+    "service/internal/application/product"
+)
+
+type Handler struct {
+    createUC *product.CreateProductUseCase
+}
+
+func NewHandler(uc *product.CreateProductUseCase) *Handler {
+    return &Handler{createUC: uc}
+}
+
+func (h *Handler) Create(c *gin.Context) {
+    var req CreateProductRequest
+    if err := c.ShouldBindJSON(&req); err != nil {
+        c.JSON(http.StatusBadRequest, gin.H{"detail": err.Error()})
+        return
+    }
+    p, err := h.createUC.Execute(c.Request.Context(), req.Name, req.Price, req.Stock)
+    if err != nil {
+        c.Error(err) // central error handler converts to ProblemDetails
+        return
+    }
+    c.JSON(http.StatusCreated, ProductResponse{
+        ID: p.ID.String(), Name: p.Name, Price: p.Price, Stock: p.Stock, CreatedAt: p.CreatedAt,
+    })
+}
+```
+
+**Rule**: handlers are thin — bind, validate (via `binding:` tags), call use case, serialize. Business logic stays in `application/`.
+
+### Router + middleware
+
+```go
+// internal/api/product/router.go
+package product
+
+import "github.com/gin-gonic/gin"
+
+func Register(r *gin.RouterGroup, h *Handler) {
+    products := r.Group("/products")
+    products.POST("", h.Create)
+}
+```
+
+```go
+// cmd/server/main.go
+package main
+
+import (
+    "github.com/gin-gonic/gin"
+    "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
+    // ... wire other deps
+)
+
+func main() {
+    cfg := loadConfig()
+    db := initDB(cfg)
+    runMigrations(db)
+
+    repo := productInfra.New(db)
+    createUC := productApp.NewCreateProductUseCase(repo)
+    handler := productAPI.NewHandler(createUC)
+
+    r := gin.New()
+    r.Use(gin.Recovery())
+    r.Use(otelgin.Middleware("products-service"))
+    r.Use(requestIDMiddleware())
+    r.Use(errorHandlerMiddleware()) // converts c.Error to RFC 9457
+    r.Use(rateLimiterMiddleware())
+
+    api := r.Group("/api/v1")
+    productAPI.Register(api, handler)
+
+    srv := &http.Server{
+        Addr:              ":8080",
+        Handler:           r,
+        ReadHeaderTimeout: 5 * time.Second,
+        WriteTimeout:      15 * time.Second,
+        IdleTimeout:       60 * time.Second,
+    }
+    log.Fatal(srv.ListenAndServe())
+}
+```
+
+**Rule**: use `http.Server` with explicit timeouts. Default `srv.ListenAndServe()` has no `ReadHeaderTimeout` — slowloris vulnerability. Always set.
+
+## 5. Testing
+
+### Unit (table-driven, idiomatic Go)
+
+```go
+// internal/domain/product/entity_test.go
+package product
+
+import (
+    "testing"
+    "github.com/google/uuid"
+)
+
+func TestReserve(t *testing.T) {
+    tests := []struct {
+        name    string
+        stock   int
+        qty     int
+        wantErr bool
+    }{
+        {"decreases stock", 10, 3, false},
+        {"refuses zero", 10, 0, true},
+        {"refuses excess", 10, 11, true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            p := Product{ID: uuid.New(), Stock: tt.stock}
+            _, err := p.Reserve(tt.qty)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("got err=%v, wantErr=%v", err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+### Integration (Testcontainers + httptest)
+
+```go
+// tests/integration/api_test.go
+package integration
+
+import (
+    "context"
+    "net/http/httptest"
+    "testing"
+    "github.com/stretchr/testify/require"
+    "github.com/testcontainers/testcontainers-go/modules/postgres"
+)
+
+func TestCreateProduct(t *testing.T) {
+    ctx := context.Background()
+    pg, err := postgres.Run(ctx, "postgres:16-alpine",
+        postgres.WithDatabase("test"),
+        postgres.WithUsername("test"),
+        postgres.WithPassword("test"),
+    )
+    require.NoError(t, err)
+    t.Cleanup(func() { pg.Terminate(ctx) })
+
+    // wire app with the postgres connection
+    r := buildRouter(t, pg)
+    ts := httptest.NewServer(r)
+    t.Cleanup(ts.Close)
+
+    // POST + assert response
+    // ...
+}
+```
+
+**Rule**: never SQLite for integration tests if prod is Postgres. Testcontainers Go is the standard.
+
+### Mutation
+
+```bash
+go-mutesting --exec internal/domain/... internal/application/...
+# Target: killed/total >= 70%
+```
+
+## 6. Build & run commands
+
+```bash
+# Setup
+go mod download
+go mod tidy
+
+# Run
+go run ./cmd/server
+
+# Build (with version info)
+go build -ldflags "-X main.version=$(git rev-parse HEAD)" -o bin/server ./cmd/server
+
+# Cross-compile (Linux from any OS)
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o bin/server-linux ./cmd/server
+
+# Tests
+go test ./...                                            # all
+go test -race ./...                                      # data race detector (slow but mandatory in CI)
+go test -coverprofile=cov.out -covermode=atomic ./...
+go tool cover -func=cov.out | tail -1                    # total coverage
+
+# Lint
+golangci-lint run ./...
+
+# Security
+govulncheck ./...
+gosec ./...
+
+# Migrations (golang-migrate)
+migrate -path migrations -database "$DATABASE_URL" up
+migrate -path migrations -database "$DATABASE_URL" down 1
+migrate create -ext sql -dir migrations -seq create_products
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+
+- **JWT**: `github.com/golang-jwt/jwt/v5`. RS256 preferred; HS256 acceptable single-service. Set `Issuer`, `Audience`, `ExpiresAt` claims. Validate `kid` for rotation.
+- **OAuth2**: `golang.org/x/oauth2` with provider-specific endpoints. PKCE for SPAs.
+- **Password hashing**: `golang.org/x/crypto/bcrypt` with cost 12 minimum. NEVER plaintext, NEVER MD5/SHA1, NEVER unsalted SHA256.
+- **API keys (internal)**: `crypto/rand` + `base64url`. Hash before storage (`sha256` is acceptable for non-user secrets).
+- **Authorization**: middleware that parses JWT, populates `gin.Context` with user/roles, then per-route middleware checks role. Object-level checks inside the use case.
+
+### 7.2 CORS
+
+```go
+import "github.com/gin-contrib/cors"
+
+r.Use(cors.New(cors.Config{
+    AllowOrigins:     []string{"https://app.example.com"},   // NEVER ["*"] in prod
+    AllowMethods:     []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
+    AllowHeaders:     []string{"Authorization", "Content-Type"},
+    AllowCredentials: true,
+    MaxAge:           12 * time.Hour,
+}))
+```
+
+### 7.3 Validation & input sanitization
+
+- **SQL injection**: GORM parameterizes by default. NEVER `db.Raw(fmt.Sprintf("... %s ...", input))` — use `db.Raw("... ?", input)`.
+- **`validator` tags**: `binding:"required,min=1,max=120"` on every request struct field. Custom validators registered at startup.
+- **Path traversal**: `filepath.Clean` + check the resolved path is inside an allowlisted base before opening.
+- **NoSQL injection (Mongo)**: use the typed bson builder, not `bson.M{}` dict concatenation with user input.
+
+### 7.4 Secrets management
+
+- `envconfig` struct loaded at startup, validation via `validator` tags.
+- `.env` gitignored; `env.example` committed.
+- Prefer Secrets Manager (AWS / GCP / Vault) in prod over `.env`. `envconfig` doesn't read from there directly — wrap with a `secretsLoader` interface.
+
+### 7.5 Rate limiting
+
+```go
+import "github.com/gin-contrib/limiter"
+
+// 100 req/min/IP
+r.Use(limiter.NewRateLimiter(limiter.Rate{
+    Period: time.Minute,
+    Limit:  100,
+}))
+```
+
+- `5/min` on `/login`, `/signup`, `/password-reset`. Use per-route group:
+
+```go
+auth := r.Group("/auth", limiter.NewRateLimiter(...))
+auth.POST("/login", h.Login)
+```
+
+- Behind reverse proxy: trust `X-Forwarded-For` only from known proxy IPs.
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in Go + Gin |
+|---|---|
+| A01 Broken Access Control | JWT middleware + per-route role check; object-level check in use case; default-deny |
+| A02 Cryptographic Failures | bcrypt cost 12; TLS at reverse proxy; HSTS via `c.Header("Strict-Transport-Security", ...)` in middleware |
+| A03 Injection | GORM parameterization; `validator` tags on every struct; never `db.Raw` with f-strings |
+| A04 Insecure Design | DDD layering (`domain/` no Gin/GORM); use case = single public method per type; ADRs document deviations |
+| A05 Security Misconfiguration | `gin.SetMode(gin.ReleaseMode)` in prod; `Server.ReadHeaderTimeout` explicit; `cors` allowlist explicit |
+| A06 Vulnerable Components | `govulncheck ./...` in CI; `dependabot` or `renovate` for `go.mod` bumps |
+| A07 Auth Failures | rate-limit on auth endpoints; bcrypt with cost 12; account lock via Redis counter |
+| A08 Data Integrity | `go mod verify`; `go.sum` committed; SBOM via `syft`/`cyclonedx-go` |
+| A09 Logging Failures | Structured JSON via `slog` (stdlib 1.21+) or `zerolog`; correlation ID middleware; **NEVER** log request body raw (PII) |
+| A10 SSRF | Centralized `http.Client` with allowlist of outbound hosts; reject private CIDRs (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.169.254`) by default |
+
+### 7.7 LGPD / GDPR / compliance specifics
+
+- **PII tagging**: convention `// pii: true` in struct comments + a custom `golangci-lint` rule (`revive` config) to flag missing tags on string fields named `Email`, `CPF`, `Document`.
+- **Soft delete**: `DeletedAt *time.Time` column + GORM `gorm.DeletedAt` type. NEVER hard delete user-owned data.
+- **Data subject access**: `GET /api/v1/me/export` returns user data as JSON or zipped CSV.
+- **Erasure**: `DELETE /api/v1/me` sets PII fields to anonymized values while preserving FKs.
+- **Encryption at rest**: PostgreSQL TDE (cloud-managed) or column-level via `pgcrypto` + Go's `crypto/aes` for AES-256-GCM application-level.
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `http.Get(url)` directly | `client := &http.Client{Timeout: 10*time.Second}; client.Get(url)` | No timeout = leaked goroutines on slow upstream |
+| `srv.ListenAndServe()` without timeouts | `&http.Server{ReadHeaderTimeout: 5*time.Second, ...}` | Slowloris attack works against default |
+| `db.Raw(fmt.Sprintf("SELECT ... WHERE id = %s", id))` | `db.Raw("SELECT ... WHERE id = ?", id)` | SQL injection via concatenation |
+| `gin.SetMode(gin.DebugMode)` in prod | `gin.SetMode(gin.ReleaseMode)` from env | Debug mode exposes routes + verbose errors |
+| `float64` or `float32` for money | `int64` (cents) or `shopspring/decimal` | Float precision loss is real |
+| `panic` inside handler not caught | `gin.Recovery()` middleware first in chain | Single bad request crashes the worker |
+| Goroutine spawned in handler without `defer wg.Done()` | Explicit `errgroup.Group` with `ctx` propagation | Goroutine leaks on early return |
+| GORM `AutoMigrate` in prod startup | `golang-migrate` with reviewed SQL files | Schema changes need explicit review |
+| Catching `error` and ignoring with `_` | Always handle: `if err != nil { return err }` OR explicit comment why ignoring | Silent errors = silent bugs |
+| Returning ORM struct directly from handler | DTO with `json:` tags; explicit conversion | API contract leaks data model |
+| Hardcoded `time.Sleep` in tests | Channels + `time.After` for timeouts | Flaky tests on slow CI |
+| `interface{}` (or `any`) when a concrete type fits | Generic `func F[T any](v T)` or concrete type | Type safety wins |
+
+## 9. Migration hints — Gin 1.9 → 1.10+
+
+Breaking changes worth flagging when `migrator` agent runs Gin 1.9 → 1.10+:
+
+- **Go 1.21 minimum** (Gin 1.10); 1.23 recommended for `slog` + generics improvements.
+- **`Context.IsAborted()`** signature unchanged but rendered errors flow through `c.Error(...)` more strictly. Audit any custom error responses.
+- **`gin.H`** is unchanged but consider replacing with typed `gin.H{}` returns by named response structs for OpenAPI compatibility.
+- **`Routes()` method** on `Engine`: minor signature consolidation. Custom route enumerators may need adjustment.
+- **HTTP/2** is enabled by default. If your service is behind a proxy doing HTTP/1.1 only, explicitly disable: `srv.TLSNextProto = make(map[string]func(*http.Server, *tls.Conn, http.Handler))`.
+- **`testify`** mock vs `gomock`: if migrating away from `testify/mock`, `gomock` 0.5 has go-generate based generation that integrates better with new code.
+
+Hand off to `migrator` with: current Gin version, current Go toolchain, list of custom middleware that touches `gin.Context` internals.
+
+## 10. References
+
+- [Gin official docs](https://gin-gonic.com/docs/)
+- [GORM 1.25 docs](https://gorm.io/docs/)
+- [golang-migrate docs](https://github.com/golang-migrate/migrate/blob/master/GETTING_STARTED.md)
+- [go-playground/validator](https://github.com/go-playground/validator)
+- [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck)
+- [gosec](https://github.com/securego/gosec)
+- [Testcontainers Go](https://golang.testcontainers.org/)
+- [OpenTelemetry Go](https://opentelemetry.io/docs/languages/go/)
+- [OWASP Go Secure Coding Practices](https://github.com/OWASP/Go-SCP)
+- ADR-007 (Senior+ gate thresholds — coverage ≥85%, mutation ≥70%)
+- ADR-026 (Generic agents + stack packs architecture)
+- ADR-027 (Pack governance — frontmatter + security mandatory + CODEOWNERS + annual review)
+- ADR-029 (Canonical pack format — this document follows it)