Go for Grit Developers

package main

import "fmt"

func main() {
    fmt.Println("Hello, Grit!")
}

package main

import "fmt"

const AppName = "my-saas"

func main() {
    // Explicit declaration
    var name string = "Grit"
    var port int = 8080

    // Short assignment (type inferred)
    host := "localhost"
    debug := true
    price := 29.99

    // Multiple assignment
    width, height := 1920, 1080

    fmt.Println(name, host, port, debug, price, width, height)
    fmt.Println("App:", AppName)
}

package models

import (
    "time"
    "gorm.io/gorm"
)

type User struct {
    ID        uint           `gorm:"primarykey" json:"id"`
    Name      string         `gorm:"size:255;not null" json:"name" binding:"required"`
    Email     string         `gorm:"size:255;uniqueIndex;not null" json:"email" binding:"required,email"`
    Password  string         `gorm:"size:255;not null" json:"-"`
    Role      string         `gorm:"size:20;default:USER" json:"role"`
    Active    bool           `gorm:"default:true" json:"active"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

package main

import (
    "errors"
    "fmt"
)

// Functions return (result, error)
func divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("cannot divide by zero")
    }
    return a / b, nil
}

func calculateDiscount(price, percent float64) (float64, error) {
    result, err := divide(price * percent, 100)
    if err != nil {
        // Wrap the error with context
        return 0, fmt.Errorf("calculating discount: %w", err)
    }
    return result, nil
}

func main() {
    discount, err := calculateDiscount(100.0, 20.0)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    fmt.Println("Discount:", discount) // 20.0
}

package main

import "fmt"

type User struct {
    FirstName string
    LastName  string
    Email     string
}

// A regular function — takes User as an argument
func getFullName(u User) string {
    return u.FirstName + " " + u.LastName
}

// A method — attached to User with a value receiver
// Use value receiver when you only READ the struct
func (u User) FullName() string {
    return u.FirstName + " " + u.LastName
}

// A method with a pointer receiver
// Use pointer receiver when you MODIFY the struct
func (u *User) SetEmail(email string) {
    u.Email = email // Modifies the original, not a copy
}

func main() {
    user := User{FirstName: "John", LastName: "Doe"}

    // Calling a function — pass the struct as argument
    fmt.Println(getFullName(user)) // "John Doe"

    // Calling a method — use dot notation on the struct
    fmt.Println(user.FullName()) // "John Doe"

    // Pointer receiver method modifies the original
    user.SetEmail("john@example.com")
    fmt.Println(user.Email) // "john@example.com"
}

package main

import "fmt"

func main() {
    // Slices
    names := []string{"Alice", "Bob", "Charlie"}
    names = append(names, "Diana")

    for i, name := range names {
        fmt.Printf("%d: %s\n", i, name)
    }

    // Maps
    user := map[string]any{
        "id":    1,
        "name":  "Alice",
        "email": "alice@example.com",
    }

    for key, value := range user {
        fmt.Printf("%s = %v\n", key, value)
    }

    // Access a single value
    fmt.Println("Name:", user["name"])
}

package main

import "fmt"

// Define an interface
type Notifier interface {
    Send(to string, message string) error
}

// EmailNotifier implements Notifier (implicitly)
type EmailNotifier struct {
    From string
}

func (e *EmailNotifier) Send(to string, message string) error {
    fmt.Printf("Email from %s to %s: %s\n", e.From, to, message)
    return nil
}

// SlackNotifier also implements Notifier
type SlackNotifier struct {
    Channel string
}

func (s *SlackNotifier) Send(to string, message string) error {
    fmt.Printf("Slack #%s -> %s: %s\n", s.Channel, to, message)
    return nil
}

// Works with ANY Notifier
func alert(n Notifier, user string) {
    n.Send(user, "Your report is ready")
}

func main() {
    email := &EmailNotifier{From: "noreply@app.com"}
    slack := &SlackNotifier{Channel: "alerts"}

    alert(email, "alice@example.com")
    alert(slack, "alice")
}

package main

import "fmt"

func doubleValue(n int) {
    n = n * 2 // Modifies the COPY, not the original
}

func doublePointer(n *int) {
    *n = *n * 2 // Modifies the ORIGINAL via pointer
}

func main() {
    x := 10

    doubleValue(x)
    fmt.Println(x) // Still 10 — the copy was doubled

    doublePointer(&x)
    fmt.Println(x) // Now 20 — modified through pointer

    // Nil pointer: indicates "no value"
    var name *string = nil
    if name == nil {
        fmt.Println("Name is not set")
    }
}

package main

import (
    "fmt"
    "sync"
    "time"
)

func fetchData(source string, wg *sync.WaitGroup) {
    defer wg.Done() // Signal completion when function returns
    time.Sleep(100 * time.Millisecond) // Simulate work
    fmt.Println("Fetched from:", source)
}

func main() {
    var wg sync.WaitGroup

    sources := []string{"database", "cache", "api"}

    for _, src := range sources {
        wg.Add(1)
        go fetchData(src, &wg) // Run concurrently
    }

    wg.Wait() // Wait for all goroutines to finish
    fmt.Println("All data fetched!")

    // Channel example
    ch := make(chan string)

    go func() {
        ch <- "hello from goroutine" // Send
    }()

    msg := <-ch // Receive
    fmt.Println(msg)
}

apps/api/
├── cmd/server/
│   └── main.go          # Entry point (package main)
├── cmd/migrate/
│   └── main.go          # Migration CLI (go run cmd/migrate)
├── cmd/seed/
│   └── main.go          # Seeder CLI (go run cmd/seed)
├── internal/
│   ├── config/
│   │   └── config.go    # package config — Config struct, Load()
│   ├── database/
│   │   ├── database.go  # package database — Connect()
│   │   ├── migrate.go   # DropAll() for fresh migrations
│   │   └── seed.go      # Seed() — populate dev data
│   ├── models/
│   │   ├── user.go      # package models — User struct (exported)
│   │   └── upload.go    # package models — Upload struct (exported)
│   ├── handlers/
│   │   ├── auth.go      # package handlers — Login(), Register()
│   │   └── user.go      # package handlers — UserHandler CRUD
│   ├── services/
│   │   └── auth.go      # package services — AuthService (JWT)
│   ├── middleware/
│   │   ├── auth.go      # package middleware — Auth(), RequireRole()
│   │   ├── cors.go      # CORS configuration
│   │   └── logger.go    # Request logging
│   └── routes/
│       └── routes.go    # package routes — Setup() wires everything
└── go.mod               # Module definition

package config

import (
    "os"
    "strconv"
    "github.com/joho/godotenv"
)

type Config struct {
    Port       int
    DBHost     string
    DBPort     int
    DBName     string
    DBUser     string
    DBPassword string
    JWTSecret  string
    Debug      bool
}

func Load() *Config {
    // Load .env file (ignored in production)
    godotenv.Load()

    port, _ := strconv.Atoi(getEnv("PORT", "8080"))
    dbPort, _ := strconv.Atoi(getEnv("DB_PORT", "5432"))

    return &Config{
        Port:       port,
        DBHost:     getEnv("DB_HOST", "localhost"),
        DBPort:     dbPort,
        DBName:     getEnv("DB_NAME", "grit_dev"),
        DBUser:     getEnv("DB_USER", "postgres"),
        DBPassword: getEnv("DB_PASSWORD", "postgres"),
        JWTSecret:  getEnv("JWT_SECRET", "change-me"),
        Debug:      getEnv("DEBUG", "false") == "true",
    }
}

func getEnv(key, fallback string) string {
    if value := os.Getenv(key); value != "" {
        return value
    }
    return fallback
}

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func main() {
    // Create a Gin engine (bare, no default middleware)
    r := gin.New()

    // Add middleware globally
    r.Use(gin.Logger())    // Log every request
    r.Use(gin.Recovery())  // Recover from panics

    // Simple route
    r.GET("/api/health", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "status": "ok",
        })
    })

    // Start server on port 8080
    r.Run(":8080")
}

// Public routes — no authentication
auth := r.Group("/api/auth")
{
    auth.POST("/register", authHandler.Register)
    auth.POST("/login", authHandler.Login)
    auth.POST("/refresh", authHandler.Refresh)
}

// Protected routes — requires valid JWT token
protected := r.Group("/api")
protected.Use(middleware.Auth(db, authService))  // Apply auth middleware
{
    protected.GET("/auth/me", authHandler.Me)
    protected.GET("/users/:id", userHandler.GetByID)
}

// Admin routes — requires ADMIN role
admin := r.Group("/api")
admin.Use(middleware.Auth(db, authService))
admin.Use(middleware.RequireRole("ADMIN"))        // Stack middleware
{
    admin.GET("/users", userHandler.List)
    admin.POST("/users", userHandler.Create)
    admin.PUT("/users/:id", userHandler.Update)
    admin.DELETE("/users/:id", userHandler.Delete)
}

func exampleHandler(c *gin.Context) {
    // ── Reading the request ──────────────────────────────
    id := c.Param("id")                     // URL param: /users/:id
    page := c.Query("page")                 // Query string: ?page=2
    page = c.DefaultQuery("page", "1")      // With default value

    var input CreateUserInput
    err := c.ShouldBindJSON(&input)         // Parse + validate JSON body

    token := c.GetHeader("Authorization")   // Read a header

    // ── Sending responses ────────────────────────────────
    c.JSON(200, gin.H{"data": "hello"})     // Send JSON
    c.JSON(404, gin.H{                      // Send error
        "error": gin.H{
            "code":    "NOT_FOUND",
            "message": "User not found",
        },
    })

    // ── Middleware data ──────────────────────────────────
    c.Set("user_id", uint(42))              // Store data (middleware → handler)
    userID, _ := c.Get("user_id")           // Retrieve data

    // ── Control flow ────────────────────────────────────
    c.Abort()                               // Stop the middleware chain
    c.Next()                                // Continue to next middleware/handler
}

// Gin validates this struct automatically
type CreateUserInput struct {
    Name     string `json:"name" binding:"required"`           // Must be present
    Email    string `json:"email" binding:"required,email"`    // Must be valid email
    Password string `json:"password" binding:"required,min=8"` // Min 8 characters
    Age      int    `json:"age" binding:"gte=18,lte=120"`      // Between 18-120
    Role     string `json:"role" binding:"oneof=USER EDITOR"`  // Must be one of these
}

func createUser(c *gin.Context) {
    var input CreateUserInput
    if err := c.ShouldBindJSON(&input); err != nil {
        // Gin returns detailed validation errors automatically
        c.JSON(422, gin.H{
            "error": gin.H{
                "code":    "VALIDATION_ERROR",
                "message": err.Error(),
            },
        })
        return
    }

    // input is now validated and safe to use
    fmt.Println(input.Name, input.Email)
}

// A middleware is just a gin.HandlerFunc that calls c.Next()
func Logger() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()

        c.Next() // ← Run the next handler/middleware

        // This runs AFTER the handler returns
        duration := time.Since(start)
        status := c.Writer.Status()
        log.Printf("%s %s → %d (%v)", c.Request.Method, c.Request.URL.Path, status, duration)
    }
}

// Middleware that blocks requests (c.Abort)
func RequireAPIKey() gin.HandlerFunc {
    return func(c *gin.Context) {
        key := c.GetHeader("X-API-Key")
        if key != "valid-key" {
            c.JSON(401, gin.H{"error": "Invalid API key"})
            c.Abort() // ← Stop the chain, handler never runs
            return
        }
        c.Next()
    }
}

Request → Logger → CORS → Auth → RequireRole → Handler
                                                         ↓
Response ← Logger ← CORS ← Auth ← RequireRole ← Handler

// If Auth calls c.Abort():
Request → Logger → CORS → Auth ✗ (returns 401, handler never runs)

r := gin.New()

// Global middleware — runs on EVERY request
r.Use(middleware.Logger())
r.Use(gin.Recovery())
r.Use(middleware.CORS(cfg.CORSOrigins))

// Group middleware — runs only on routes in this group
protected := r.Group("/api")
protected.Use(middleware.Auth(db, authService))   // Only protected routes
{
    protected.GET("/users/:id", userHandler.GetByID)
}

// Stacking middleware — multiple on one group
admin := r.Group("/api")
admin.Use(middleware.Auth(db, authService))        // Must be logged in
admin.Use(middleware.RequireRole("ADMIN"))          // AND must be admin
{
    admin.DELETE("/users/:id", userHandler.Delete)
}

package middleware

import (
    "strings"
    "github.com/gin-gonic/gin"
)

// CORS returns middleware that allows cross-origin requests.
func CORS(allowedOrigins string) gin.HandlerFunc {
    origins := strings.Split(allowedOrigins, ",")

    return func(c *gin.Context) {
        origin := c.GetHeader("Origin")

        // Check if the request origin is allowed
        for _, allowed := range origins {
            if strings.TrimSpace(allowed) == origin {
                c.Header("Access-Control-Allow-Origin", origin)
                c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
                c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
                c.Header("Access-Control-Allow-Credentials", "true")
                break
            }
        }

        // Handle preflight requests
        if c.Request.Method == "OPTIONS" {
            c.AbortWithStatus(204)
            return
        }

        c.Next()
    }
}

# Comma-separated list of allowed frontend origins
CORS_ORIGINS=http://localhost:3000,http://localhost:3001

package handlers

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "gorm.io/gorm"

    "myapp/apps/api/internal/models"
    "myapp/apps/api/internal/services"
)

// Handler struct holds dependencies
type AuthHandler struct {
    DB          *gorm.DB
    AuthService *services.AuthService
}

// Request struct — what the client sends
type loginRequest struct {
    Email    string `json:"email" binding:"required,email"`
    Password string `json:"password" binding:"required"`
}

// Login authenticates a user and returns JWT tokens.
func (h *AuthHandler) Login(c *gin.Context) {
    // 1. Parse & validate
    var req loginRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusUnprocessableEntity, gin.H{
            "error": gin.H{
                "code":    "VALIDATION_ERROR",
                "message": err.Error(),
            },
        })
        return
    }

    // 2. Find user in database
    var user models.User
    if err := h.DB.Where("email = ?", req.Email).First(&user).Error; err != nil {
        c.JSON(http.StatusUnauthorized, gin.H{
            "error": gin.H{
                "code":    "INVALID_CREDENTIALS",
                "message": "Invalid email or password",
            },
        })
        return
    }

    // 3. Check password (delegate to model method)
    if !user.CheckPassword(req.Password) {
        c.JSON(http.StatusUnauthorized, gin.H{
            "error": gin.H{
                "code":    "INVALID_CREDENTIALS",
                "message": "Invalid email or password",
            },
        })
        return
    }

    // 4. Generate tokens (delegate to auth service)
    tokens, err := h.AuthService.GenerateTokenPair(user.ID, user.Email, user.Role)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{
            "error": gin.H{
                "code":    "TOKEN_ERROR",
                "message": "Failed to generate tokens",
            },
        })
        return
    }

    // 5. Respond
    c.JSON(http.StatusOK, gin.H{
        "data": gin.H{
            "user":   user,
            "tokens": tokens,
        },
        "message": "Logged in successfully",
    })
}

package services

import (
    "fmt"
    "math"

    "gorm.io/gorm"

    "myapp/apps/api/internal/models"
)

// Service struct — holds the database connection
type ProductService struct {
    DB *gorm.DB
}

// All operations are methods on the service

// List returns paginated products with search and sorting.
func (s *ProductService) List(page, pageSize int, search, sortBy, sortOrder string) ([]models.Product, int64, int, error) {
    query := s.DB.Model(&models.Product{})

    if search != "" {
        query = query.Where("name ILIKE ?", "%"+search+"%")
    }

    var total int64
    query.Count(&total)

    var items []models.Product
    offset := (page - 1) * pageSize
    err := query.Order(sortBy + " " + sortOrder).
        Offset(offset).
        Limit(pageSize).
        Find(&items).Error

    if err != nil {
        return nil, 0, 0, fmt.Errorf("fetching products: %w", err)
    }

    pages := int(math.Ceil(float64(total) / float64(pageSize)))
    return items, total, pages, nil
}

// GetByID returns a single product.
func (s *ProductService) GetByID(id uint) (*models.Product, error) {
    var item models.Product
    if err := s.DB.First(&item, id).Error; err != nil {
        return nil, fmt.Errorf("product not found: %w", err)
    }
    return &item, nil
}

// Create adds a new product.
func (s *ProductService) Create(item *models.Product) error {
    if err := s.DB.Create(item).Error; err != nil {
        return fmt.Errorf("creating product: %w", err)
    }
    return nil
}

// Delete soft-deletes a product.
func (s *ProductService) Delete(id uint) error {
    var item models.Product
    if err := s.DB.First(&item, id).Error; err != nil {
        return fmt.Errorf("product not found: %w", err)
    }
    return s.DB.Delete(&item).Error
}

type ProductHandler struct {
    Service *services.ProductService
}

func (h *ProductHandler) GetByID(c *gin.Context) {
    id, _ := strconv.ParseUint(c.Param("id"), 10, 64)

    // Delegate to service
    product, err := h.Service.GetByID(uint(id))
    if err != nil {
        c.JSON(404, gin.H{"error": gin.H{"code": "NOT_FOUND", "message": "Product not found"}})
        return
    }

    // Respond
    c.JSON(200, gin.H{"data": product})
}

package database

import (
    "fmt"
    "log"

    "gorm.io/driver/postgres"
    "gorm.io/gorm"
    "gorm.io/gorm/logger"
)

func Connect(dsn string) (*gorm.DB, error) {
    db, err := gorm.Open(postgres.New(postgres.Config{
        DSN:                  dsn,
        PreferSimpleProtocol: true,
    }), &gorm.Config{
        Logger: logger.Default.LogMode(logger.Info),
    })
    if err != nil {
        return nil, fmt.Errorf("failed to connect: %w", err)
    }

    // Configure connection pool
    sqlDB, _ := db.DB()
    sqlDB.SetMaxIdleConns(10)
    sqlDB.SetMaxOpenConns(100)

    log.Println("Database connected successfully")
    return db, nil
}

// ── CREATE ─────────────────────────────────────────────
product := models.Product{Name: "Widget", Price: 29.99}
db.Create(&product)          // INSERT INTO products ...
fmt.Println(product.ID)      // ID is auto-set after create

// ── READ — single record ──────────────────────────────
var found models.Product
db.First(&found, 42)                          // WHERE id = 42
db.Where("email = ?", "alice@test.com").First(&found)  // WHERE email = ...

// ── READ — multiple records ───────────────────────────
var products []models.Product
db.Find(&products)                            // SELECT * FROM products
db.Where("price > ?", 20.0).Find(&products)  // With condition

// ── READ — pagination and sorting ─────────────────────
db.Order("created_at desc").
    Offset(0).    // Skip 0 records (page 1)
    Limit(20).    // Take 20 records
    Find(&products)

// ── READ — count ──────────────────────────────────────
var total int64
db.Model(&models.Product{}).Count(&total)

// ── READ — search with ILIKE (case-insensitive) ──────
search := "widget"
db.Where("name ILIKE ?", "%"+search+"%").Find(&products)

// ── UPDATE ────────────────────────────────────────────
db.Model(&found).Update("price", 34.99)      // Single field
db.Model(&found).Updates(map[string]any{      // Multiple fields
    "name":  "Super Widget",
    "price": 39.99,
})

// ── DELETE (soft delete) ──────────────────────────────
db.Delete(&found)            // Sets deleted_at, doesn't remove row
// To permanently delete: db.Unscoped().Delete(&found)

// Models with relationships
type Category struct {
    ID       uint      `gorm:"primarykey" json:"id"`
    Name     string    `json:"name"`
    Products []Product `json:"products"`  // has many
}

type Product struct {
    ID         uint     `gorm:"primarykey" json:"id"`
    Name       string   `json:"name"`
    CategoryID uint     `json:"category_id"`           // foreign key
    Category   Category `json:"category"`               // belongs to
}

// Without Preload — category field will be empty {}
db.First(&product, 1)
fmt.Println(product.Category.Name) // "" (empty!)

// With Preload — category is loaded
db.Preload("Category").First(&product, 1)
fmt.Println(product.Category.Name) // "Electronics"

import "golang.org/x/crypto/bcrypt"

// BeforeCreate runs automatically before INSERT
func (u *User) BeforeCreate(tx *gorm.DB) error {
    if u.Password != "" {
        hashed, err := bcrypt.GenerateFromPassword(
            []byte(u.Password), bcrypt.DefaultCost,
        )
        if err != nil {
            return err
        }
        u.Password = string(hashed)
    }
    return nil
}

// CheckPassword compares plaintext against stored hash
func (u *User) CheckPassword(password string) bool {
    err := bcrypt.CompareHashAndPassword(
        []byte(u.Password), []byte(password),
    )
    return err == nil
}

// Usage — password is hashed automatically
user := models.User{
    Email:    "alice@example.com",
    Password: "mypassword123",  // Plaintext here
}
db.Create(&user) // BeforeCreate hashes it before INSERT

package models

import (
    "log"
    "gorm.io/gorm"
)

// Models returns ALL models in migration order.
// Models with no foreign key dependencies come first.
func Models() []interface{} {
    return []interface{}{
        &User{},
        &Upload{},
        &Blog{},
        // grit:models  ← new models are injected here
    }
}

// Migrate creates tables that don't exist yet.
func Migrate(db *gorm.DB) error {
    models := Models()

    for _, model := range models {
        // Skip if table already exists
        if db.Migrator().HasTable(model) {
            log.Printf("  ✓ %T — already exists, skipping", model)
            continue
        }

        if err := db.AutoMigrate(model); err != nil {
            return fmt.Errorf("migrating %T: %w", model, err)
        }
        log.Printf("  ✓ %T — created", model)
    }

    return nil
}

package database

import (
    "log"
    "myapp/apps/api/internal/models"
    "gorm.io/gorm"
)

// Seed populates the database with initial data.
func Seed(db *gorm.DB) error {
    if err := seedAdminUser(db); err != nil {
        return fmt.Errorf("seeding admin: %w", err)
    }
    if err := seedDemoUsers(db); err != nil {
        return fmt.Errorf("seeding users: %w", err)
    }
    // grit:seeders  ← new seeders injected here
    return nil
}

// Idempotent seeder — checks before creating
func seedAdminUser(db *gorm.DB) error {
    var count int64
    db.Model(&models.User{}).Where("email = ?", "admin@example.com").Count(&count)
    if count > 0 {
        log.Println("Admin already exists, skipping...")
        return nil
    }

    admin := models.User{
        FirstName: "Admin",
        LastName:  "User",
        Email:     "admin@example.com",
        Password:  "password",     // Hashed by BeforeCreate hook
        Role:      "ADMIN",
        Active:    true,
    }

    if err := db.Create(&admin).Error; err != nil {
        return fmt.Errorf("creating admin: %w", err)
    }

    log.Println("Created admin: admin@example.com / password")
    return nil
}

// 1. JWT contains "claims" — data about the user
type Claims struct {
    UserID uint   `json:"user_id"`
    Email  string `json:"email"`
    Role   string `json:"role"`
    jwt.RegisteredClaims          // Expiry, issued-at, etc.
}

// 2. Server creates a token by signing claims with a secret
claims := &Claims{
    UserID: 42,
    Email:  "alice@example.com",
    Role:   "ADMIN",
    RegisteredClaims: jwt.RegisteredClaims{
        ExpiresAt: jwt.NewNumericDate(time.Now().Add(15 * time.Minute)),
        IssuedAt:  jwt.NewNumericDate(time.Now()),
    },
}

token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
tokenString, _ := token.SignedString([]byte("my-secret-key"))
// tokenString = "eyJhbGciOiJIUzI1NiIs..."

// 3. Later, server validates the token
parsed, _ := jwt.ParseWithClaims(tokenString, &Claims{}, func(t *jwt.Token) (interface{}, error) {
    return []byte("my-secret-key"), nil
})
claims = parsed.Claims.(*Claims)
fmt.Println(claims.UserID) // 42

┌─────────────────────────────────────────────────────────────────┐
│ 1. REGISTER                                                     │
│                                                                 │
│  Client sends:    POST /api/auth/register                       │
│                   { "email": "alice@test.com",                  │
│                     "password": "mypassword" }                  │
│                                                                 │
│  Server does:     ① Validate input (binding tags)               │
│                   ② Check email doesn't already exist           │
│                   ③ Create user (BeforeCreate hashes password)  │
│                   ④ Generate access token (15min) + refresh     │
│                     token (7 days)                              │
│                   ⑤ Return { user, tokens }                     │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 2. LOGIN                                                        │
│                                                                 │
│  Client sends:    POST /api/auth/login                          │
│                   { "email": "alice@test.com",                  │
│                     "password": "mypassword" }                  │
│                                                                 │
│  Server does:     ① Find user by email (db.Where)              │
│                   ② Check password (bcrypt.CompareHashAndPassword)│
│                   ③ Check account is active                     │
│                   ④ Generate new token pair                     │
│                   ⑤ Return { user, tokens }                     │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 3. AUTHENTICATED REQUEST                                        │
│                                                                 │
│  Client sends:    GET /api/users                                │
│                   Authorization: Bearer eyJhbGciOi...           │
│                                                                 │
│  Middleware does:  ① Extract token from "Bearer <token>"        │
│                    ② Validate signature + check expiry          │
│                    ③ Load user from DB by claims.UserID         │
│                    ④ Set user data in context                   │
│                    ⑤ Call c.Next() → handler runs               │
│                                                                 │
│  Handler does:    Read c.Get("user") → return response          │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 4. TOKEN REFRESH                                                │
│                                                                 │
│  When access token expires (15min), client sends:               │
│  POST /api/auth/refresh { "refresh_token": "eyJ..." }          │
│                                                                 │
│  Server validates the refresh token and returns new tokens.     │
│  Client never needs to log in again until the refresh           │
│  token expires (7 days).                                        │
└─────────────────────────────────────────────────────────────────┘

type AuthService struct {
    Secret        string
    AccessExpiry  time.Duration  // e.g., 15 minutes
    RefreshExpiry time.Duration  // e.g., 7 days
}

type TokenPair struct {
    AccessToken  string `json:"access_token"`
    RefreshToken string `json:"refresh_token"`
    ExpiresAt    int64  `json:"expires_at"`
}

// GenerateTokenPair creates both access and refresh tokens.
func (s *AuthService) GenerateTokenPair(userID uint, email, role string) (*TokenPair, error) {
    // Access token — short-lived, used for API requests
    accessToken, expiresAt, err := s.generateToken(userID, email, role, s.AccessExpiry)
    if err != nil {
        return nil, fmt.Errorf("generating access token: %w", err)
    }

    // Refresh token — long-lived, used only to get new access tokens
    refreshToken, _, err := s.generateToken(userID, email, role, s.RefreshExpiry)
    if err != nil {
        return nil, fmt.Errorf("generating refresh token: %w", err)
    }

    return &TokenPair{
        AccessToken:  accessToken,
        RefreshToken: refreshToken,
        ExpiresAt:    expiresAt,
    }, nil
}

// ValidateToken parses and verifies a token string.
func (s *AuthService) ValidateToken(tokenString string) (*Claims, error) {
    token, err := jwt.ParseWithClaims(tokenString, &Claims{},
        func(token *jwt.Token) (interface{}, error) {
            // Verify the signing method is HMAC (prevent algorithm attacks)
            if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
                return nil, fmt.Errorf("unexpected signing method")
            }
            return []byte(s.Secret), nil
        },
    )
    if err != nil {
        return nil, fmt.Errorf("parsing token: %w", err)
    }

    claims, ok := token.Claims.(*Claims)
    if !ok || !token.Valid {
        return nil, fmt.Errorf("invalid token")
    }

    return claims, nil
}