Forwarded

​

Overview

​

Installation

import "github.com/go-mizu/mizu/middlewares/forwarded"

​

Quick Start

app := mizu.New()
app.Use(forwarded.New())

​

Configuration

​

Headers Parsed

​

Examples

​

Basic Usage

app.Use(forwarded.New())

app.Get("/", func(c *mizu.Ctx) error {
    info := forwarded.Get(c)
    return c.JSON(200, map[string]any{
        "clientIP": info.ClientIP,
        "proto":    info.Proto,
        "host":     info.Host,
    })
})

​

Trusted Proxies Only

app.Use(forwarded.WithOptions(forwarded.Options{
    TrustProxy: true,
    TrustedProxies: []string{
        "10.0.0.0/8",
        "192.168.1.0/24",
    },
}))

​

Helper Functions

// Get client IP
ip := forwarded.ClientIP(c)

// Get protocol
proto := forwarded.Proto(c)

// Get host
host := forwarded.Host(c)

​

Info Struct

type Info struct {
    For      string    // X-Forwarded-For value
    Host     string    // Original host
    Proto    string    // http or https
    Port     string    // Original port
    Prefix   string    // Path prefix
    ClientIP net.IP    // Parsed client IP
}

​

API Reference

func New() mizu.Middleware
func WithOptions(opts Options) mizu.Middleware
func Get(c *mizu.Ctx) *Info
func FromContext(c *mizu.Ctx) *Info
func ClientIP(c *mizu.Ctx) net.IP
func Proto(c *mizu.Ctx) string
func Host(c *mizu.Ctx) string

​

Technical Details

​

Header Processing Priority

1. X-Forwarded-For: Extracts the client IP from the first entry in the comma-separated list
2. X-Forwarded-Host: Sets the original host requested by the client
3. X-Forwarded-Proto: Determines if the original request was HTTP or HTTPS
4. X-Forwarded-Port: Captures the original port number
5. X-Forwarded-Prefix: Records any path prefix added by reverse proxies
6. Forwarded (RFC 7239): Parses the standardized Forwarded header, which can override previous values

​

Trusted Proxy Validation

• IP addresses are automatically converted to CIDR notation (single IPs get /32)
• The middleware checks if the remote address matches any trusted CIDR ranges
• If no match is found, all X-Forwarded-* headers are ignored and the remote address is used

​

IP Parsing

• Standard IPv4 addresses (e.g., 192.168.1.1)
• IPv6 addresses in RFC 7239 format with brackets (e.g., [2001:db8::1])
• Addresses with port numbers (automatically stripped)

​

Context Storage

​

Best Practices

1. Always specify trusted proxies in production environments to prevent header spoofing
2. Use CIDR notation for trusted proxy ranges to cover entire subnets
3. Validate client IPs after extraction if using them for security decisions
4. Prefer RFC 7239 Forwarded header when possible for better standardization
5. Disable TrustProxy when not behind a reverse proxy to avoid security issues

​

Testing

​

Security Note

​

Related Middlewares

• realip - Simple IP extraction
• proxy - Reverse proxy