Go Strict

---
name: go-strict
description: >
  Go coding standards, clean code, and security rules. Use when writing, reviewing,
  or refactoring Go code. Covers error handling (wrapping with %w), package organization
  (internal/pkg split), concurrency safety (sync.RWMutex, goroutine lifecycle), Gin
  handler patterns, input validation, structured logging with zerolog, graceful shutdown,
  and naming conventions. Derived from production Go services.
---

# Go Strict Standard

Rules extracted from 2 production Go services.

## CRITICAL: Error Handling

### GO-01: Always wrap errors with context

```go
// BAD: no context, impossible to trace
if err != nil {
    return err
}

// GOOD: fmt.Errorf with %w for wrapping
store, err := createStore(path)
if err != nil {
    return nil, fmt.Errorf("create store: %w", err)
}

// GOOD: multiple levels of context
session, err := validateToken(token)
if err != nil {
    return fmt.Errorf("validate session for user %s: %w", userID, err)
}
```

### GO-02: Check errors immediately, never defer

```go
// BAD: error ignored
json.Unmarshal(data, &result)

// GOOD
if err := json.Unmarshal(data, &result); err != nil {
    return fmt.Errorf("unmarshal response: %w", err)
}
```

### GO-03: Drain response bodies for connection reuse

```go
resp, err := http.Get(url)
if err != nil {
    return fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()

if resp.StatusCode != http.StatusOK {
    io.Copy(io.Discard, resp.Body) // DRAIN before closing
    return fmt.Errorf("unexpected status: %d", resp.StatusCode)
}
```

### GO-04: Typed errors for API responses

```go
type APIError struct {
    Status  int    `json:"status"`
    Message string `json:"message"`
    Code    string `json:"code,omitempty"`
}

func (e *APIError) Error() string {
    return fmt.Sprintf("[%d] %s", e.Status, e.Message)
}

func SendError(c *gin.Context, status int, message string) {
    c.JSON(status, APIError{Status: status, Message: message})
}
```

## CRITICAL: Package Organization

### GO-05: internal/ for private, pkg/ for reusable

```
project/
├── cmd/
│   └── server/
│       └── main.go              # Entry point only: no logic
├── internal/
│   ├── handlers/                # HTTP handlers (Gin)
│   ├── middleware/              # Auth, rate limit, CORS, validation
│   ├── services/                # Business logic
│   ├── models/                  # Data structures
│   ├── config/                  # Env var loading
│   └── utils/                   # Helpers
├── pkg/
│   ├── redis/                   # Reusable Redis client
│   └── sqlite/                  # Reusable SQLite wrapper
├── go.mod
└── go.sum
```

`internal/` prevents import from outside the module. Use it.

### GO-06: main.go is thin: wire and run

```go
func main() {
    cfg := config.Load()
    redisClient := redis.NewClient(cfg.RedisURL)
    handlers := handlers.NewHandlers(redisClient, cfg)

    router := setupRouter(handlers, cfg)

    srv := &http.Server{Addr: ":" + cfg.Port, Handler: router}
    go func() { srv.ListenAndServe() }()

    // Graceful shutdown
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
    <-quit

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    srv.Shutdown(ctx)
}
```

## HIGH: Concurrency Safety

### GO-07: sync.RWMutex: read lock for reads, write lock for writes

```go
type RateLimiter struct {
    mu      sync.RWMutex
    entries map[string]*entry
}

func (rl *RateLimiter) GetLimiter(key string) *entry {
    rl.mu.RLock()
    e, ok := rl.entries[key]
    rl.mu.RUnlock()
    if ok { return e }

    rl.mu.Lock()
    defer rl.mu.Unlock()
    // Double-check after acquiring write lock
    if e, ok := rl.entries[key]; ok { return e }
    e = &entry{/* ... */}
    rl.entries[key] = e
    return e
}
```

Pattern: RLock → check → RUnlock → Lock → double-check → create.

### GO-08: Background goroutines with proper lifecycle

```go
func (rl *RateLimiter) evictLoop(interval, maxAge time.Duration) {
    ticker := time.NewTicker(interval)
    defer ticker.Stop()

    for range ticker.C {
        rl.mu.Lock()
        now := time.Now()
        for key, e := range rl.entries {
            if now.Sub(e.lastAccess) > maxAge {
                delete(rl.entries, key)
            }
        }
        rl.mu.Unlock()
    }
}

// Start with: go rl.evictLoop(5*time.Minute, 10*time.Minute)
```

### GO-09: Graceful shutdown with context

```go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

if err := srv.Shutdown(ctx); err != nil {
    log.Fatal().Err(err).Msg("server forced to shutdown")
}
```

## HIGH: HTTP Handler Patterns (Gin)

### GO-10: Constructor injection for handlers

```go
type Handlers struct {
    redis  *redis.Client
    config *config.Config
    sqlite *sqlite.Client
}

func NewHandlers(r *redis.Client, cfg *config.Config, s *sqlite.Client) *Handlers {
    return &Handlers{redis: r, config: cfg, sqlite: s}
}
```

### GO-11: Middleware chaining

```go
router := gin.New()
router.Use(middleware.CORS())
router.Use(middleware.InjectConfig(cfg))

// Group with shared auth
internal := router.Group("/", middleware.InternalAuth(cfg))
internal.GET("/validate-token", h.ValidateToken)

// Per-route rate limiting
router.POST("/login", middleware.RateLimit(10, time.Minute), h.Login)
```

### GO-12: Input validation in middleware

```go
func ValidateLicenseKey() gin.HandlerFunc {
    pattern := regexp.MustCompile(`^A-[A-Z0-9]{6}-[A-Z0-9]{8}-[A-Z0-9]{7}$`)
    return func(c *gin.Context) {
        key := c.Query("license_key")
        if key == "" {
            key = c.PostForm("license_key")
        }
        if !pattern.MatchString(key) {
            c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid license format"})
            c.Abort()
            return
        }
        c.Set("license_key", key)
        c.Next()
    }
}
```

Compile regex once in closure, not per-request.

## MEDIUM: Naming Conventions

### GO-13: Follow Go idioms strictly

```go
// Receivers: single letter matching type
func (rl *RateLimiter) GetLimiter(key string) { ... }
func (m *Manager) CreateInstance(cfg Config) { ... }
func (h *Handlers) ValidateToken(c *gin.Context) { ... }

// Constructors: NewType()
func NewHandlers(...) *Handlers { ... }
func NewRateLimiter(max int) *RateLimiter { ... }

// Getters: no Get prefix (unless disambiguating)
func (u *User) Name() string { return u.name }       // Not GetName()
func (u *User) SetName(n string) { u.name = n }      // Set prefix OK

// Boolean: use Is/Has/Can
func (s *Session) IsExpired() bool { ... }
func (u *User) HasPermission(p string) bool { ... }

// Packages: lowercase, no underscores
package handlers  // Not package http_handlers
package middleware // Not package Middleware

// Constants: PascalCase (exported), camelCase (unexported)
const MaxRetries = 3
const defaultTimeout = 30 * time.Second
```

### GO-14: Use typed structs, not `gin.H{}` in hot paths

```go
// BAD: heap allocation per response
c.JSON(200, gin.H{"status": "ok", "data": result})

// GOOD: stack-allocated struct
type Response struct {
    Status string      `json:"status"`
    Data   interface{} `json:"data"`
}
c.JSON(200, Response{Status: "ok", Data: result})
```

## MEDIUM: Logging

### GO-15: Use zerolog for structured logging

```go
import "github.com/rs/zerolog"

// Setup
logger := zerolog.New(os.Stderr).With().Timestamp().Logger()

// Usage
logger.Info().Str("component", "auth").Str("user", userID).Msg("login successful")
logger.Error().Err(err).Str("endpoint", path).Msg("request failed")
logger.Warn().Int("attempts", count).Msg("approaching rate limit")
```

Never `log.Printf` in production: it's unstructured and hard to query.

### GO-16: Component context in loggers

```go
func NewManager(logger zerolog.Logger) *Manager {
    return &Manager{
        log: logger.With().Str("component", "instance-mgr").Logger(),
    }
}
```

## Security Rules

### GO-17: No secrets in source code

```go
// BAD
const apiKey = "sk-abc123..."

// GOOD
apiKey := os.Getenv("API_KEY")
if apiKey == "" {
    log.Fatal().Msg("API_KEY environment variable required")
}
```

### GO-18: Validate all external input

Never trust query params, POST bodies, or headers. Validate format, length, and type.

### GO-19: Use `http.StatusXxx` constants

```go
// BAD
c.JSON(401, gin.H{"error": "unauthorized"})

// GOOD
c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
```

## HIGH: Context and Error Plumbing

### GO-20: `context.Context` is the first argument

```go
// BAD: caller cannot cancel or propagate deadlines
func FetchUser(id string) (*User, error) { ... }

// GOOD
func FetchUser(ctx context.Context, id string) (*User, error) {
    req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
    return doRequest(req)
}
```

In handlers, derive from the request: `ctx := c.Request.Context()`. Never call `context.Background()` inside a request path.

### GO-21: Inspect wrapped errors with `errors.Is` / `errors.As`

```go
// Sentinel error
var ErrNotFound = errors.New("not found")

if err != nil {
    if errors.Is(err, ErrNotFound) {
        return c.JSON(http.StatusNotFound, ...)
    }
    var apiErr *APIError
    if errors.As(err, &apiErr) {
        return c.JSON(apiErr.Status, apiErr)
    }
    return c.JSON(http.StatusInternalServerError, ...)
}
```

`==` comparison on wrapped errors fails. Always unwrap with `Is`/`As`.

### GO-22a: `log/slog` is the structured logger, not third-party libs

```go
// Old: zerolog / zap / logrus
// New (Go 1.21+): stdlib log/slog
import "log/slog"

logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
slog.SetDefault(logger)

slog.Info("user signed in", "user_id", uid, "tenant", tenantID)
slog.Error("save failed", "err", err, "request_id", reqID)
```

`slog` covers JSON output, log levels, attribute groups, and context propagation. New code should not pull in zerolog or zap unless there's a specific reason.

### GO-22b: `math/rand/v2` for non-cryptographic randomness

```go
// BAD: math/rand needs explicit seeding, has known bias issues
import "math/rand"

// GOOD: math/rand/v2 (Go 1.22+) seeds from a CSPRNG by default
import "math/rand/v2"

n := rand.IntN(100)        // 0..99
shuffled := rand.Perm(10)  // permutation
```

For tokens, secrets, or anything cryptographic, still use `crypto/rand`.

### GO-22c: `os.Root` for filesystem-confined access (Go 1.24+)

```go
// Confine FS access to a directory, prevents path traversal
root, err := os.OpenRoot("/var/app/uploads")
if err != nil {
    return err
}
defer root.Close()

// All operations resolve relative to root, ".." escapes are blocked
f, err := root.Open(userPath)
```

Use `os.Root` for any filesystem code that touches user-supplied paths.

### GO-22ca: Go 1.26 highlights (Feb 2026)

- **Green Tea garbage collector** is now default. Real-world programs see 10-40% lower GC overhead, no source change required.
- **`crypto/hpke`** stdlib package implements RFC 9180 Hybrid Public Key Encryption with post-quantum hybrid KEMs. Use this for new key-agreement code instead of pulling in `cloudflare/circl`.
- **`new(expr)`**: `new` accepts an expression and returns a pointer to its initial value. Replaces `x := expr; p := &x`.
- **Self-referencing generic types**: a type can name itself in its own type-parameter list. Simplifies trees, graphs, and CRTP-style APIs.
- **`GOEXPERIMENT=simd`** opens the experimental `simd/archsimd` package. Useful for hot loops, still subject to change.
- **cgo overhead** down ~30% baseline. Tighten cgo budgets accordingly.

### GO-22d: `range` over functions and integers

```go
// Go 1.22+: range over int
for i := range 10 { ... }

// Go 1.23+: range over function (custom iterators)
for k, v := range myMap.All() {
    fmt.Println(k, v)
}

// Define an iterator
func (m *Map[K, V]) All() iter.Seq2[K, V] {
    return func(yield func(K, V) bool) {
        for k, v := range m.data {
            if !yield(k, v) { return }
        }
    }
}
```

Replaces hand-rolled `Iterator` interfaces. Pair with the `iter` package.

### GO-22e: Never expose `/debug/pprof` publicly

```go
// BAD: pprof leaks heap, goroutine names, source paths to anyone
import _ "net/http/pprof"
http.ListenAndServe(":8080", nil)

// GOOD: separate port, bound to localhost or behind auth
go http.ListenAndServe("127.0.0.1:6060", nil)
```

Same for `expvar`. Either gate behind auth middleware or bind to loopback.

## Vulnerability Checklist

- [ ] All errors wrapped with `fmt.Errorf("context: %w", err)`
- [ ] Response bodies drained before close (`io.Copy(io.Discard, resp.Body)`)
- [ ] No secrets in source (use env vars)
- [ ] Input validated in middleware (regex compiled once)
- [ ] RWMutex with double-check locking pattern
- [ ] Background goroutines have shutdown mechanism
- [ ] Graceful shutdown with 30s timeout
- [ ] Structured logging (zerolog, not fmt/log)
- [ ] No `gin.H{}` in hot paths (use typed structs)
- [ ] `c.Abort()` called after error responses in middleware