Advanced

package main

import (
    "net/http"
    "regexp"
    "strings"
    "github.com/gin-gonic/gin"
    "github.com/go-playground/validator/v10"
)

// slugRegexp validates URL-safe slug format: lowercase letters, digits, hyphens
var slugRegexp = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
// => "my-post-title" matches; "My Post" does not

// validateSlug is a custom validator function
func validateSlug(fl validator.FieldLevel) bool {
    return slugRegexp.MatchString(fl.Field().String())
    // => fl.Field().String() returns the field value as string
    // => Returns true if valid, false if invalid
}

// validateNoProfanity is a custom validator
func validateNoProfanity(fl validator.FieldLevel) bool {
    profanity := []string{"spam", "fake"} // => Simplified; use a real list
    content := strings.ToLower(fl.Field().String())
    for _, word := range profanity {
        if strings.Contains(content, word) {
            return false // => Field contains banned word
        }
    }
    return true
}

// PostRequest uses both built-in and custom validators
type PostRequest struct {
    Title   string `json:"title"   binding:"required,min=5,max=200,noProfanity"`
    // => noProfanity: custom tag registered below
    Slug    string `json:"slug"    binding:"required,slug"`
    // => slug: custom tag registered below
    Content string `json:"content" binding:"required,min=10"`
}

func main() {
    r := gin.Default()

    // Register custom validators with Gin's validator engine
    if v, ok := r.Get("validator"); ok { // => This approach doesn't work directly
        _ = v
    }
    // Correct approach: get validator from Gin's binding package
    validate := validator.New()
    validate.RegisterValidation("slug", validateSlug)
    // => "slug" tag now available in all binding tags
    validate.RegisterValidation("noProfanity", validateNoProfanity)

    // Use the custom validator with Gin's binding
    // In Gin v1.9+, register via binding.Validator
    // binding.Validator.Engine().(*validator.Validate).RegisterValidation("slug", validateSlug)

    r.POST("/posts", func(c *gin.Context) {
        var req PostRequest
        if err := c.ShouldBindJSON(&req); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        c.JSON(http.StatusCreated, gin.H{
            "title": req.Title,
            "slug":  req.Slug, // => "my-post-title"
        })
    })

    // Demonstrate manual validation with custom validator
    r.POST("/validate-slug", func(c *gin.Context) {
        var body struct {
            Slug string `json:"slug"`
        }
        c.ShouldBindJSON(&body)

        err := validate.Var(body.Slug, "required,slug") // => Validate single value
        if err != nil {
            c.JSON(http.StatusBadRequest, gin.H{
                "valid": false,
                "slug":  body.Slug,
                "error": err.Error(),
            })
            return
        }
        c.JSON(http.StatusOK, gin.H{"valid": true, "slug": body.Slug})
    })

    r.Run(":8080")
}
// POST /validate-slug {"slug":"valid-slug-123"} => {"valid":true,"slug":"valid-slug-123"}
// POST /validate-slug {"slug":"Invalid Slug!"}  => {"valid":false,"error":"..."}

package main

import (
    "net/http"
    "time"
    "github.com/gin-gonic/gin"
    "go.uber.org/zap"
)

// MiddlewareFactory creates middleware with injected dependencies
type MiddlewareFactory struct {
    logger *zap.Logger
}

// NewMiddlewareFactory injects shared dependencies into all middleware
func NewMiddlewareFactory(logger *zap.Logger) *MiddlewareFactory {
    return &MiddlewareFactory{logger: logger}
}

// Recovery handles panics - must be first (outermost wrapper)
func (f *MiddlewareFactory) Recovery() gin.HandlerFunc {
    return gin.CustomRecovery(func(c *gin.Context, recovered interface{}) {
        f.logger.Error("panic recovered",  // => Structured panic log
            zap.Any("panic", recovered),
            zap.String("path", c.Request.URL.Path),
        )
        c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
    })
}

// Timing measures request latency - after Recovery, before auth
func (f *MiddlewareFactory) Timing() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()        // => Record start before c.Next()
        c.Next()                   // => Process request
        latency := time.Since(start)
        f.logger.Info("request",   // => Post-handler log includes actual latency
            zap.Duration("latency", latency),
            zap.Int("status", c.Writer.Status()),
            zap.String("path", c.Request.URL.Path),
        )
    }
}

// Auth validates tokens - after logging, before handlers
func (f *MiddlewareFactory) Auth() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
            return
        }
        c.Set("user", "user-42") // => Validated user stored in context
        c.Next()
    }
}

func main() {
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    factory := NewMiddlewareFactory(logger) // => Inject logger into factory

    r := gin.New()
    // Order matters: Recovery outermost, Auth before handlers
    r.Use(factory.Recovery())  // => Layer 1: catch panics
    r.Use(factory.Timing())    // => Layer 2: measure all requests including auth failures
    // Public routes before auth middleware
    r.GET("/health", func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) })

    api := r.Group("/api")
    api.Use(factory.Auth()) // => Layer 3: protect API routes only
    {
        api.GET("/users", func(c *gin.Context) {
            c.JSON(http.StatusOK, gin.H{"user": c.GetString("user")})
        })
    }
    r.Run(":8080")
}

package main

import (
    "log"
    "net/http"
    "time"
    "github.com/gin-gonic/gin"
    "github.com/gorilla/websocket"
)

// upgrader configures WebSocket upgrade parameters
var upgrader = websocket.Upgrader{
    ReadBufferSize:  1024, // => Buffer for reading messages
    WriteBufferSize: 1024, // => Buffer for writing messages
    CheckOrigin: func(r *http.Request) bool {
        return true // => In production: validate r.Header.Get("Origin")
                    // => return r.Header.Get("Origin") == "https://app.example.com"
    },
}

// Message is the JSON structure exchanged over WebSocket
type Message struct {
    Type    string `json:"type"`    // => "message", "ping", "pong"
    Content string `json:"content"` // => Message payload
    Time    string `json:"time"`    // => Timestamp
}

func handleWebSocket(c *gin.Context) {
    // Upgrade HTTP GET to WebSocket protocol
    conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
    // => Sends 101 Switching Protocols response
    // => conn is *websocket.Conn (full-duplex connection)
    if err != nil {
        log.Printf("websocket upgrade failed: %v", err)
        return
    }
    defer conn.Close() // => Close connection when handler returns

    // Set read deadline to detect disconnected clients
    conn.SetReadDeadline(time.Now().Add(60 * time.Second))
    // => ReadMessage returns error if no message within 60s

    // Pong handler resets read deadline on each ping
    conn.SetPongHandler(func(string) error {
        conn.SetReadDeadline(time.Now().Add(60 * time.Second))
        // => Client responded to our ping; reset deadline
        return nil
    })

    // Start ping goroutine to keep connection alive
    go func() {
        ticker := time.NewTicker(30 * time.Second)
        defer ticker.Stop()
        for range ticker.C {
            if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil {
                return // => Connection closed
            }
        }
    }()

    // Welcome message
    conn.WriteJSON(Message{Type: "connected", Content: "welcome!", Time: time.Now().Format(time.RFC3339)})
    // => {"type":"connected","content":"welcome!","time":"2026-03-19T12:00:00+07:00"}

    // Read loop
    for {
        var msg Message
        if err := conn.ReadJSON(&msg); err != nil { // => Blocks until message or timeout
            if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
                log.Printf("websocket error: %v", err)
            }
            break // => Connection closed; exit read loop
        }

        // Echo message back
        response := Message{Type: "echo", Content: msg.Content, Time: time.Now().Format(time.RFC3339)}
        if err := conn.WriteJSON(response); err != nil { // => Send response to same client
            break
        }
    }
}

func main() {
    r := gin.Default()
    r.GET("/ws", handleWebSocket) // => WebSocket endpoint
    r.GET("/", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"websocket": "ws://localhost:8080/ws"})
    })
    r.Run(":8080")
}
// ws://localhost:8080/ws
// Connect => receives {"type":"connected","content":"welcome!"}
// Send {"type":"message","content":"hello"} => receives {"type":"echo","content":"hello"}

package main

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

func main() {
    r := gin.Default()

    r.GET("/events", func(c *gin.Context) {
        // SSE requires specific headers to enable browser EventSource API
        c.Header("Content-Type", "text/event-stream") // => Enable SSE in browser
        c.Header("Cache-Control", "no-cache")          // => Prevent intermediary caching
        c.Header("Connection", "keep-alive")            // => Keep TCP connection open
        c.Header("X-Accel-Buffering", "no")            // => Disable nginx buffering

        // Send events in a loop
        ticker := time.NewTicker(1 * time.Second) // => Send event every second
        defer ticker.Stop()

        clientGone := c.Request.Context().Done() // => Closed when client disconnects

        for {
            select {
            case <-clientGone:
                return // => Client disconnected; stop sending events

            case t := <-ticker.C:
                // SSE format: "data: <payload>\n\n"
                // Each event is separated by double newline
                event := fmt.Sprintf(`{"time":"%s","value":%d}`,
                    t.Format(time.RFC3339),
                    t.Unix(), // => Unix timestamp as "value"
                )
                fmt.Fprintf(c.Writer, "data: %s\n\n", event)
                // => Writes "data: {"time":"...","value":1710844800}\n\n"
                c.Writer.Flush() // => Flush buffer to send immediately
                                  // => Without Flush, data accumulates in buffer
            }
        }
    })

    // Send named events (different event types for client filtering)
    r.GET("/events/typed", func(c *gin.Context) {
        c.Header("Content-Type", "text/event-stream")
        c.Header("Cache-Control", "no-cache")

        // Named event with ID for reconnection support
        fmt.Fprintf(c.Writer, "id: 1\n")             // => Event ID for reconnection
        fmt.Fprintf(c.Writer, "event: userjoined\n") // => Named event type
        fmt.Fprintf(c.Writer, "data: {\"user\":\"alice\"}\n\n") // => Payload + double newline
        c.Writer.Flush()

        // Retry directive tells browser how long to wait before reconnecting
        fmt.Fprintf(c.Writer, "retry: 3000\n\n") // => Reconnect after 3 seconds
        c.Writer.Flush()
    })

    r.StaticFile("/", "./index.html") // => Serve HTML page with EventSource
    r.Run(":8080")
}
// Browser: const es = new EventSource("/events");
// es.onmessage = (e) => console.log(JSON.parse(e.data));
// => Receives {"time":"2026-03-19T12:00:00+07:00","value":1710844800} every second

package main

import (
    "log"
    "net/http"
    "sync"
    "github.com/gin-gonic/gin"
    "github.com/gorilla/websocket"
)

// Hub manages all active WebSocket connections
type Hub struct {
    clients    map[*websocket.Conn]bool // => Active connections set
    broadcast  chan []byte               // => Messages to send to all clients
    register   chan *websocket.Conn      // => New connection registration
    unregister chan *websocket.Conn      // => Connection removal
    mu         sync.RWMutex             // => Protects clients map
}

func NewHub() *Hub {
    return &Hub{
        clients:    make(map[*websocket.Conn]bool),
        broadcast:  make(chan []byte, 256),  // => Buffered; prevents blocking on slow clients
        register:   make(chan *websocket.Conn),
        unregister: make(chan *websocket.Conn),
    }
}

// Run is the Hub's main goroutine; all map mutations happen here (no race conditions)
func (h *Hub) Run() {
    for {
        select {
        case conn := <-h.register:    // => New client connected
            h.mu.Lock()
            h.clients[conn] = true    // => Add to active set
            h.mu.Unlock()
            log.Printf("client connected, total: %d", len(h.clients))

        case conn := <-h.unregister:  // => Client disconnected
            h.mu.Lock()
            if _, ok := h.clients[conn]; ok {
                delete(h.clients, conn) // => Remove from active set
                conn.Close()            // => Close underlying connection
            }
            h.mu.Unlock()

        case message := <-h.broadcast: // => Message to send to everyone
            h.mu.RLock()
            for conn := range h.clients {
                // Write to each client; remove if write fails (disconnected)
                if err := conn.WriteMessage(websocket.TextMessage, message); err != nil {
                    h.unregister <- conn // => Queue for removal
                }
            }
            h.mu.RUnlock()
        }
    }
}

var upgrader = websocket.Upgrader{CheckOrigin: func(r *http.Request) bool { return true }}

func main() {
    hub := NewHub()
    go hub.Run() // => Start hub goroutine

    r := gin.Default()

    r.GET("/ws", func(c *gin.Context) {
        conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
        if err != nil { return }

        hub.register <- conn // => Register new client

        // Read messages from this client and broadcast to all
        for {
            _, msg, err := conn.ReadMessage()
            if err != nil {
                hub.unregister <- conn // => Client disconnected
                break
            }
            hub.broadcast <- msg // => Send to all connected clients
        }
    })

    // HTTP endpoint to send messages to all WebSocket clients
    r.POST("/broadcast", func(c *gin.Context) {
        var body struct {
            Message string `json:"message" binding:"required"`
        }
        if err := c.ShouldBindJSON(&body); err != nil {
            c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
            return
        }
        hub.broadcast <- []byte(body.Message) // => Broadcast to all WebSocket clients
        c.JSON(http.StatusOK, gin.H{"sent": true})
    })

    r.Run(":8080")
}
// Connect ws://localhost:8080/ws (from multiple browsers)
// POST /broadcast {"message":"hello everyone"}
// => All connected WebSocket clients receive "hello everyone"

package main

import (
    "net/http"
    "strconv"
    "time"
    "github.com/gin-gonic/gin"
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

// Define Prometheus metrics with meaningful labels
var (
    // Counter tracks total requests by method, path, and status code
    requestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "gin_requests_total",
            Help: "Total number of HTTP requests",
        },
        []string{"method", "path", "status"}, // => Label dimensions
    )

    // Histogram tracks request latency distribution
    requestDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "gin_request_duration_seconds",
            Help:    "HTTP request latency",
            Buckets: prometheus.DefBuckets, // => [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
        },
        []string{"method", "path"},
    )

    // Gauge tracks current in-flight requests
    inFlightRequests = prometheus.NewGauge(
        prometheus.GaugeOpts{
            Name: "gin_requests_in_flight",
            Help: "Current number of requests being processed",
        },
    )
)

func init() {
    // Register metrics with the default Prometheus registry
    prometheus.MustRegister(requestsTotal, requestDuration, inFlightRequests)
}

// PrometheusMiddleware records metrics for every request
func PrometheusMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        inFlightRequests.Inc() // => Increment in-flight counter
        defer inFlightRequests.Dec() // => Decrement when handler returns

        c.Next() // => Process request

        duration := time.Since(start).Seconds()  // => Latency in seconds
        status := strconv.Itoa(c.Writer.Status()) // => "200", "404", etc.
        path := c.FullPath()                      // => Route template "/users/:id"
                                                   // => Not the actual path (prevents label explosion)

        requestsTotal.WithLabelValues(c.Request.Method, path, status).Inc()
        // => Increments counter for this method+path+status combination

        requestDuration.WithLabelValues(c.Request.Method, path).Observe(duration)
        // => Records duration in histogram bucket
    }
}

func main() {
    r := gin.Default()
    r.Use(PrometheusMiddleware())

    // Prometheus scrape endpoint
    r.GET("/metrics", gin.WrapH(promhttp.Handler()))
    // => promhttp.Handler() serves Prometheus text format
    // => gin.WrapH wraps http.Handler into gin.HandlerFunc

    r.GET("/users/:id", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"id": c.Param("id")})
    })

    r.Run(":8080")
}
// GET /metrics
// => # HELP gin_requests_total Total number of HTTP requests
// => # TYPE gin_requests_total counter
// => gin_requests_total{method="GET",path="/users/:id",status="200"} 42
// => gin_request_duration_seconds_bucket{method="GET",path="/users/:id",le="0.01"} 40

package main

import (
    "context"
    "net/http"
    "github.com/gin-gonic/gin"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/trace"
)

// OtelMiddleware starts a span for each request and propagates trace context
func OtelMiddleware(tracer trace.Tracer) gin.HandlerFunc {
    return func(c *gin.Context) {
        // Extract parent context from incoming request headers
        // (for cross-service trace propagation)
        ctx := c.Request.Context()

        // Start a new span for this request
        ctx, span := tracer.Start(ctx, c.Request.Method+" "+c.FullPath(),
            // => Span name: "GET /users/:id"
            trace.WithSpanKind(trace.SpanKindServer), // => This span represents a server operation
        )
        defer span.End() // => End span when handler returns (records duration)

        // Add HTTP attributes to the span
        span.SetAttributes(
            attribute.String("http.method", c.Request.Method),   // => "GET"
            attribute.String("http.route", c.FullPath()),         // => "/users/:id"
            attribute.String("http.url", c.Request.URL.String()), // => Full URL
            attribute.String("net.peer.ip", c.ClientIP()),        // => Client IP
        )

        // Store span context in Gin context for handlers to use
        c.Set("otelCtx", ctx) // => Handlers access this to create child spans
        c.Set("span", span)

        // Update request context with trace context
        c.Request = c.Request.WithContext(ctx)

        c.Next() // => Execute handler

        // Record response attributes after handler completes
        span.SetAttributes(
            attribute.Int("http.status_code", c.Writer.Status()), // => 200
        )
    }
}

// getUserFromDB demonstrates creating a child span for a sub-operation
func getUserFromDB(ctx context.Context, userID string) map[string]string {
    tracer := otel.Tracer("my-service")
    _, span := tracer.Start(ctx, "db.query.get_user") // => Child span
    defer span.End()

    span.SetAttributes(
        attribute.String("db.operation", "SELECT"),
        attribute.String("db.table", "users"),
        attribute.String("user.id", userID),
    )
    // Simulate database query
    return map[string]string{"id": userID, "name": "Alice"}
}

func main() {
    tracer := otel.Tracer("my-service") // => In production: configure OTLP exporter

    r := gin.Default()
    r.Use(OtelMiddleware(tracer))

    r.GET("/users/:id", func(c *gin.Context) {
        ctx, _ := c.Get("otelCtx")        // => Retrieve trace context
        traceCtx := ctx.(context.Context) // => Type assert to context.Context

        user := getUserFromDB(traceCtx, c.Param("id"))
        // => Creates child span "db.query.get_user" under request span

        c.JSON(http.StatusOK, user)
        // => Trace shows: GET /users/:id -> db.query.get_user
    })

    r.Run(":8080")
}
// Traces visible in Jaeger/Zipkin/Grafana Tempo:
// Trace: GET /users/:id (duration: 5ms)
//   -> db.query.get_user (duration: 3ms)

package main

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

// CircuitState represents the current state of the circuit breaker
type CircuitState int

const (
    StateClosed   CircuitState = iota // => Normal operation; requests pass through
    StateOpen                         // => Circuit open; requests fail immediately
    StateHalfOpen                     // => Testing if dependency recovered
)

// CircuitBreaker prevents calls to a failing service
type CircuitBreaker struct {
    state        CircuitState
    failures     int           // => Consecutive failure count
    threshold    int           // => Failures before opening circuit
    timeout      time.Duration // => How long to stay open before half-open
    lastFailure  time.Time
    mu           sync.Mutex
}

func NewCircuitBreaker(threshold int, timeout time.Duration) *CircuitBreaker {
    return &CircuitBreaker{
        state:     StateClosed, // => Start closed (normal operation)
        threshold: threshold,
        timeout:   timeout,
    }
}

// Call executes fn if circuit is closed or half-open
func (cb *CircuitBreaker) Call(fn func() error) error {
    cb.mu.Lock()
    defer cb.mu.Unlock()

    switch cb.state {
    case StateOpen:
        if time.Since(cb.lastFailure) > cb.timeout {
            cb.state = StateHalfOpen // => Try one request (half-open)
        } else {
            return errors.New("circuit open: dependency unavailable") // => Fast fail
        }

    case StateClosed, StateHalfOpen:
        // Proceed with the call
    }

    err := fn() // => Execute the actual operation

    if err != nil {
        cb.failures++                    // => Increment failure count
        cb.lastFailure = time.Now()      // => Record failure time
        if cb.failures >= cb.threshold { // => Threshold exceeded
            cb.state = StateOpen         // => Open the circuit
        }
        return err
    }

    // Success - reset circuit
    cb.failures = 0         // => Reset failure counter
    cb.state = StateClosed  // => Close circuit (or keep closed)
    return nil
}

// Simulate external service call
func callExternalService() error {
    // In real code: HTTP call, database query, etc.
    return errors.New("connection refused") // => Simulating failing service
}

func main() {
    cb := NewCircuitBreaker(3, 10*time.Second) // => Open after 3 failures; retry after 10s

    r := gin.Default()

    r.GET("/data", func(c *gin.Context) {
        err := cb.Call(func() error {
            return callExternalService() // => Wrapped in circuit breaker
        })

        if err != nil {
            // Check if circuit is open (fast fail) vs service failure
            c.JSON(http.StatusServiceUnavailable, gin.H{
                "error":    err.Error(),      // => "circuit open: dependency unavailable"
                "fallback": "cached data",    // => Serve cached/default data
            })
            return
        }

        c.JSON(http.StatusOK, gin.H{"data": "live data"})
    })

    r.Run(":8080")
}
// First 3 requests: 503 {"error":"connection refused","fallback":"cached data"}
// 4th request:      503 {"error":"circuit open: dependency unavailable","fallback":"cached data"}
// After 10 seconds: half-open; next request tries real call

package main

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

// ProxyHandler creates a reverse proxy for the given upstream URL
func ProxyHandler(upstream string) gin.HandlerFunc {
    target, err := url.Parse(upstream) // => Parse upstream URL
    if err != nil {
        panic("invalid upstream URL: " + err.Error())
    }

    proxy := httputil.NewSingleHostReverseProxy(target)
    // => httputil.ReverseProxy forwards requests to target
    // => Handles hop-by-hop header stripping automatically

    // Customize the director to modify requests before forwarding
    originalDirector := proxy.Director
    proxy.Director = func(req *http.Request) {
        originalDirector(req) // => Set target host and URL

        // Add upstream identification headers
        req.Header.Set("X-Forwarded-By", "gin-proxy")
        // => Identifies this proxy in upstream logs
        req.Header.Set("X-Real-IP", req.Header.Get("X-Forwarded-For"))
        // => Preserve original client IP for upstream logging

        // Rewrite path: strip /api/v1 prefix before forwarding
        req.URL.Path = strings.TrimPrefix(req.URL.Path, "/api/v1")
        if req.URL.Path == "" {
            req.URL.Path = "/"
        }
    }

    // Handle errors from upstream (connection refused, timeout, etc.)
    proxy.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
        w.WriteHeader(http.StatusBadGateway) // => 502 Bad Gateway
        w.Write([]byte(`{"error":"upstream service unavailable"}`))
    }

    return func(c *gin.Context) {
        proxy.ServeHTTP(c.Writer, c.Request) // => Forward to upstream
    }
}

func main() {
    r := gin.Default()

    // Forward /api/v1/* to internal service at :9090 (path stripped)
    r.Any("/api/v1/*path", ProxyHandler("http://localhost:9090"))
    // => GET /api/v1/users => GET http://localhost:9090/users
    // => POST /api/v1/items => POST http://localhost:9090/items

    // Load-balanced proxy: use multiple upstreams with custom transport
    r.GET("/health", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"proxy": "running"})
    })

    r.Run(":8080")
}
// GET http://localhost:8080/api/v1/users
// => Forwarded to http://localhost:9090/users
// => Adds X-Forwarded-By: gin-proxy header
// GET http://localhost:8080/health => {"proxy":"running"} (not proxied)

package main

import (
    "encoding/json"
    "net/http"
    "sync"
    "time"
    "github.com/gin-gonic/gin"
)

// CacheEntry stores a cached response with expiration
type CacheEntry struct {
    Data      []byte    // => Serialized response body
    ExpiresAt time.Time // => When this cache entry expires
}

// ResponseCache is a simple in-memory cache with TTL
type ResponseCache struct {
    entries map[string]*CacheEntry
    mu      sync.RWMutex
}

func NewResponseCache() *ResponseCache {
    cache := &ResponseCache{entries: make(map[string]*CacheEntry)}
    // Start background cleanup goroutine
    go func() {
        for range time.Tick(5 * time.Minute) { // => Clean expired entries every 5 minutes
            cache.mu.Lock()
            for key, entry := range cache.entries {
                if time.Now().After(entry.ExpiresAt) {
                    delete(cache.entries, key) // => Remove expired entries
                }
            }
            cache.mu.Unlock()
        }
    }()
    return cache
}

func (c *ResponseCache) Get(key string) ([]byte, bool) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    entry, ok := c.entries[key]
    if !ok || time.Now().After(entry.ExpiresAt) {
        return nil, false // => Cache miss or expired
    }
    return entry.Data, true // => Cache hit
}

func (c *ResponseCache) Set(key string, data []byte, ttl time.Duration) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.entries[key] = &CacheEntry{
        Data:      data,
        ExpiresAt: time.Now().Add(ttl), // => Entry valid for ttl duration
    }
}

// CacheMiddleware returns cached responses for matching requests
func CacheMiddleware(cache *ResponseCache, ttl time.Duration) gin.HandlerFunc {
    return func(c *gin.Context) {
        if c.Request.Method != "GET" {
            c.Next() // => Only cache GET requests
            return
        }

        key := c.Request.URL.RequestURI() // => "/api/products?page=1" as cache key
        if data, ok := cache.Get(key); ok { // => Cache hit
            c.Header("X-Cache", "HIT")      // => Inform client response is cached
            c.Data(http.StatusOK, "application/json", data)
            c.Abort() // => Skip handler; use cached response
            return
        }

        c.Header("X-Cache", "MISS") // => Inform client response is fresh
        c.Next()                     // => Execute handler

        // Cache the response if it was successful
        if c.Writer.Status() == http.StatusOK {
            // For this to work, we need to capture the response body
            // Production: use a response writer wrapper to capture body
        }
    }
}

func main() {
    cache := NewResponseCache()
    r := gin.Default()

    r.GET("/api/products", CacheMiddleware(cache, 5*time.Minute), func(c *gin.Context) {
        // Simulate expensive database query
        time.Sleep(100 * time.Millisecond)           // => Simulated DB query: 100ms
        products := []gin.H{{"id": 1, "name": "Laptop"}, {"id": 2, "name": "Phone"}}
        data, _ := json.Marshal(gin.H{"products": products})

        // Manually store in cache (in production: capture via response writer wrapper)
        cache.Set(c.Request.URL.RequestURI(), data, 5*time.Minute)

        c.Data(http.StatusOK, "application/json", data)
    })

    r.Run(":8080")
}
// First GET /api/products   => X-Cache: MISS, response in ~100ms
// Second GET /api/products  => X-Cache: HIT, response in ~0ms