middleware

func Buffer ¶

func Buffer(cfgs ...BufferConfig) flash.Middleware

Buffer returns middleware that wraps the ResponseWriter with a pooled buffer to reduce syscalls and to set an accurate Content-Length when possible. Not recommended for streaming/SSE. Apply before handlers that generate bounded payloads.

Behavior:

• Buffers writes in-memory up to MaxSize; beyond that, switches to streaming
• Sets Content-Length on close when safe (no Content-Encoding)
• Supports Flush passthrough and zero-allocation HEAD responses

Example:

// Global buffering with defaults (unbounded). Prefer setting MaxSize.
app.Use(middleware.Buffer())

// Per-route configuration
app.GET("/report", handler, middleware.Buffer(middleware.BufferConfig{MaxSize: 2<<20}))

func CORS ¶

func CORS(cfg CORSConfig) flash.Middleware

CORS returns middleware that sets CORS headers and handles preflight requests according to the provided config with enhanced security features.

Security Features:

• Origin validation with wildcard handling
• Prevents credential exposure with wildcard origins
• Validates requested methods and headers against allowed lists
• Adds security headers to prevent content type sniffing
• Proper handling of null and invalid origins

Behavior:

• Sets Access-Control-Allow-Origin, -Credentials, -Expose-Headers on all responses
• For OPTIONS requests with Access-Control-Request-Method header (preflight):
• Validates requested method against allowed methods
• Validates requested headers against allowed headers
• Sets Access-Control-Allow-Methods, -Headers, -Max-Age
• Returns 204 No Content
• For other OPTIONS requests: passes through to handler
• For non-OPTIONS requests: passes through to handler

Performance notes:

• Headers are computed once at middleware creation, not per request
• Origin validation uses efficient string matching
• Preflight responses are cached by browsers according to MaxAge
• No allocations in the hot path for header string joining

Example:

// Simple CORS for API
app.Use(middleware.CORS(middleware.CORSConfig{
	Origins: []string{"https://app.example.com"},
	Methods: []string{"GET", "POST", "PUT", "DELETE"},
	Headers: []string{"Content-Type", "Authorization"},
}))

Example (with credentials and caching):

// CORS for authenticated API
app.Use(middleware.CORS(middleware.CORSConfig{
	Origins:     []string{"https://app.example.com", "https://admin.example.com"},
	Methods:     []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
	Headers:     []string{"Content-Type", "Authorization", "X-Requested-With"},
	Expose:      []string{"X-Total-Count", "X-Rate-Limit-Remaining"},
	Credentials: true,
	MaxAge:      3600, // 1 hour
}))

Security Best Practices:

// Production-ready CORS configuration
app.Use(middleware.CORS(middleware.CORSConfig{
	Origins:     []string{"https://app.example.com"}, // Specific origins, not "*"
	Methods:     []string{"GET", "POST", "PUT", "DELETE"}, // Only needed methods
	Headers:     []string{"Content-Type", "Authorization"}, // Only needed headers
	Credentials: true, // Only if needed
	MaxAge:      86400, // 24 hours - balance security and performance
}))

func CSRF ¶

func CSRF(cfgs ...CSRFConfig) flash.Middleware

CSRF returns middleware that provides CSRF protection using the double-submit cookie pattern.

Behavior:

• For safe methods (GET, HEAD, OPTIONS): sets CSRF cookie if missing, then continues
• For unsafe methods (POST, PUT, PATCH, DELETE): validates token in both cookie and header
• Returns 403 Forbidden if token is missing or invalid
• Uses constant-time comparison to prevent timing attacks

Performance notes:

• Token generation uses crypto/rand for cryptographic security
• Constant-time comparison prevents timing-based attacks
• Cookie validation only occurs for unsafe methods
• Minimal overhead for safe methods (just cookie setting)

Security features:

• Double-submit pattern prevents CSRF attacks
• Cryptographically secure random tokens
• Constant-time token comparison
• Configurable cookie security attributes

Example (using defaults):

app.Use(middleware.CSRF())

Example (custom configuration):

app.Use(middleware.CSRF(middleware.CSRFConfig{
	CookieName:     "csrf_token",
	HeaderName:     "X-CSRF-Header",
	TokenLength:    64, // stronger tokens
	CookieSecure:   true,
	CookieHTTPOnly: true,
	CookieSameSite: http.SameSiteStrictMode,
	TTL:            24 * time.Hour,
}))

Client-side usage:

// JavaScript: read token from cookie and send in header
const token = document.cookie.match('_csrf=([^;]+)')[1];
fetch('/api/data', {
	method: 'POST',
	headers: { 'X-CSRF-Token': token },
	body: JSON.stringify(data)
});

func Logger ¶

func Logger(options ...LoggerOption) flash.Middleware

Logger returns middleware that logs each HTTP request using structured logging (slog).

This middleware automatically captures and logs the following request information:

• HTTP method (GET, POST, PUT, DELETE, etc.)
• Request path (e.g., "/api/users/123")
• Route pattern (e.g., "/api/users/:id")
• HTTP status code (200, 404, 500, etc.)
• Request duration in milliseconds
• Remote client address
• User agent string
• Request ID (if available via RequestID middleware)
• Custom attributes (if provided via context or CustomAttributesFunc)

The logger is retrieved from the request context or application context. If no status code is set by the handler, it defaults to 200 (OK).

Usage Examples:

// Basic usage - add to your app or group
app := flash.New()
app.Use(middleware.Logger())

// With custom routes
app.Get("/users", func(c flash.Ctx) error {
    // Your handler logic here
    return c.JSON(200, map[string]string{"message": "success"})
})

// Combined with other middleware
app.Use(
    middleware.RequestID(),
    middleware.Logger(), // Logger will include request_id if available
    middleware.Recover(),
)

// On specific route groups
api := app.Group("/api")
api.Use(middleware.Logger())
api.Get("/users", userHandler)
api.Post("/users", createUserHandler)

// With configuration options
app.Use(middleware.Logger(
    middleware.WithExcludeFields("user_agent", "remote"),
    middleware.WithCustomAttributes(func(c flash.Ctx) []any {
        if userID := c.Context().Value("user_id"); userID != nil {
            return []any{"user_id", userID}
        }
        return nil
    }),
    middleware.WithMessage("http_request"),
))

// Add custom attributes in handlers or middleware
app.Use(func(next flash.Handler) flash.Handler {
    return func(c flash.Ctx) error {
        // Add custom attributes to context
        attrs := middleware.NewLoggerAttributes("middleware", "auth", "version", "v2")
        ctx := middleware.WithLoggerAttributes(c.Context(), attrs)
        c.SetRequest(c.Request().WithContext(ctx))
        return next(c)
    }
})

// In handlers, add dynamic attributes
app.Get("/users/:id", func(c flash.Ctx) error {
    userID := c.Param("id")
    attrs := middleware.NewLoggerAttributes("user_id", userID, "operation", "fetch")
    ctx := middleware.WithLoggerAttributes(c.Context(), attrs)
    c.SetRequest(c.Request().WithContext(ctx))

    // Handler logic...
    return c.JSON(200, user)
})

Example log output:

{
  "level": "INFO",
  "msg": "request",
  "method": "GET",
  "path": "/api/users/123",
  "route": "/api/users/:id",
  "status": 200,
  "duration_ms": 45.2,
  "remote": "192.168.1.100:54321",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "request_id": "req_abc123def456",
  "user_id": "123",
  "operation": "fetch",
  "middleware": "auth",
  "version": "v2"
}

Error handling:

// The middleware will log the request even if the handler returns an error
app.Get("/error", func(c flash.Ctx) error {
    return flash.NewError(500, "Internal server error")
})
// Log output will show status: 500 and the error will be returned to the client

Performance considerations:

// The middleware has minimal overhead and is safe to use in production
// Duration is measured in microseconds and converted to milliseconds for readability
// All string operations are efficient and don't allocate unnecessary memory
// Custom attributes are efficiently stored and retrieved from context
// Excluded fields are handled with minimal performance impact

app := flash.New()
app.Use(Logger())
app.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "success"})
})

app := flash.New()

// API routes with detailed logging
api := app.Group("/api")
api.Use(Logger(
	WithCustomAttributes(func(c flash.Ctx) []any {
		return []any{"service", "api", "version", "v1"}
	}),
	WithMessage("api_request"),
))
api.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "users"})
})

// Admin routes with minimal logging (exclude sensitive fields)
admin := app.Group("/admin")
admin.Use(Logger(
	WithExcludeFields("user_agent", "remote", "request_id"),
	WithCustomAttributes(func(c flash.Ctx) []any {
		return []any{"service", "admin", "access_level", "admin"}
	}),
	WithMessage("admin_request"),
))
admin.GET("/stats", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "stats"})
})

// Public routes with standard logging
app.Use(Logger(WithMessage("public_request")))
app.GET("/", func(c flash.Ctx) error {
	return c.String(200, "Hello World")
})

app := flash.New()
app.Use(Logger(WithCustomAttributes(func(c flash.Ctx) []any {
	// Add user ID from authentication context
	if userID := c.Context().Value("user_id"); userID != nil {
		return []any{"user_id", userID}
	}
	return nil
})))
app.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "success"})
})

app := flash.New()
app.Use(Logger(WithMessage("http_request")))
app.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "success"})
})

app := flash.New()
// Exclude user agent and remote address for privacy
app.Use(Logger(WithExcludeFields("user_agent", "remote")))
app.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "success"})
})

app := flash.New()
app.Use(Logger(
	WithExcludeFields("user_agent", "remote"),
	WithCustomAttributes(func(c flash.Ctx) []any {
		if userID := c.Context().Value("user_id"); userID != nil {
			return []any{"user_id", userID, "operation", "api_call"}
		}
		return []any{"operation", "api_call"}
	}),
	WithMessage("api_request"),
))
app.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "success"})
})

func RateLimit ¶

func RateLimit(options ...RateLimitOption) flash.Middleware

RateLimit returns middleware that applies rate limiting to HTTP requests.

This middleware integrates any RateLimitStrategy implementation with the HTTP request flow. It extracts a client identifier (key), checks if the request is allowed by the strategy, and returns an appropriate error response if the rate limit is exceeded.

The middleware is highly configurable and supports various rate limiting patterns:

• Different algorithms (token bucket, sliding window, etc.)
• Custom key extraction (IP, user ID, API key, etc.)
• Custom error responses (JSON, HTML, etc.)
• Request whitelisting and skipping
• Secure proxy handling
• Memory management and cleanup

Basic Usage Examples:

// Simple IP-based rate limiting (100 requests per minute)
app.Use(middleware.RateLimit(
	middleware.WithStrategy(middleware.NewTokenBucketStrategy(100, time.Minute)),
))

// API rate limiting with custom error response
app.Use(middleware.RateLimit(
	middleware.WithStrategy(middleware.NewTokenBucketStrategy(1000, time.Hour)),
	middleware.WithErrorResponse(func(c flash.Ctx, retryAfter time.Duration) error {
		return c.Status(429).JSON(map[string]any{
			"error": "API rate limit exceeded",
			"retry_after_seconds": int(retryAfter.Seconds()),
			"limit": 1000,
			"window": "1 hour",
		})
	}),
))

Advanced Usage Examples:

// User-based rate limiting with different limits per user tier
app.Use(middleware.RateLimit(
	middleware.WithStrategy(middleware.NewTokenBucketStrategy(100, time.Minute)),
	middleware.WithKeyFunc(func(c flash.Ctx) string {
		userID := c.Get("user_id")
		userTier := c.Get("user_tier")
		return fmt.Sprintf("%s:%s", userTier, userID)
	}),
	middleware.WithSkipFunc(func(c flash.Ctx) bool {
		// Skip rate limiting for premium users
		return c.Get("user_tier") == "premium"
	}),
))

// Multi-layered rate limiting (per-IP and per-user)
app.Use(middleware.RateLimit(
	middleware.WithStrategy(middleware.NewTokenBucketStrategy(1000, time.Hour)),
	middleware.WithKeyFunc(func(c flash.Ctx) string {
		// Global per-IP limit
		return "ip:" + clientIP(c.Request())
	}),
))
app.Use(middleware.RateLimit(
	middleware.WithStrategy(middleware.NewTokenBucketStrategy(100, time.Minute)),
	middleware.WithKeyFunc(func(c flash.Ctx) string {
		// Per-user limit (more restrictive)
		if userID := c.Get("user_id"); userID != nil {
			return "user:" + userID.(string)
		}
		return "anonymous"
	}),
))

Production Configuration Examples:

// High-traffic API behind AWS Application Load Balancer
app.Use(middleware.RateLimit(
	middleware.WithStrategy(middleware.NewSlidingWindowStrategy(10000, time.Hour)),
	middleware.WithTrustedProxies([]string{
		"10.0.0.0/8",      // Private subnets
		"172.16.0.0/12",   // Private subnets
		"192.168.0.0/16",  // Private subnets
	}),
	middleware.WithMaxKeyLength(128),
	middleware.WithCleanupInterval(5 * time.Minute),
	middleware.WithKeyFunc(func(c flash.Ctx) string {
		// Combine API key and IP for more granular control
		apiKey := c.Header("X-API-Key")
		if apiKey == "" {
			return "no-key:" + clientIP(c.Request())
		}
		return "api:" + apiKey
	}),
	middleware.WithErrorResponse(func(c flash.Ctx, retryAfter time.Duration) error {
		// Include rate limit headers for API clients
		c.Header("X-RateLimit-Limit", "10000")
		c.Header("X-RateLimit-Remaining", "0")
		c.Header("X-RateLimit-Reset", fmt.Sprintf("%d", time.Now().Add(retryAfter).Unix()))
		c.Header("Retry-After", fmt.Sprintf("%.0f", retryAfter.Seconds()))
		return c.Status(429).JSON(map[string]any{
			"error": "rate_limit_exceeded",
			"message": "API rate limit exceeded. Please slow down your requests.",
			"retry_after_seconds": int(retryAfter.Seconds()),
			"documentation": "https://docs.example.com/api/rate-limits",
		})
	}),
	middleware.WithSkipFunc(func(c flash.Ctx) bool {
		// Skip rate limiting for health checks and internal services
		path := c.Path()
		return path == "/health" ||
			   path == "/metrics" ||
			   c.Header("X-Internal-Service") != ""
	}),
))

// WebSocket connection rate limiting
app.Use(middleware.RateLimit(
	middleware.WithStrategy(middleware.NewLeakyBucketStrategy(1.0, 10)), // 1 conn/sec, max 10 queued
	middleware.WithKeyFunc(func(c flash.Ctx) string {
		return "ws:" + clientIP(c.Request())
	}),
	middleware.WithSkipFunc(func(c flash.Ctx) bool {
		// Only apply to WebSocket upgrade requests
		return c.Header("Upgrade") != "websocket"
	}),
))

Strategy Selection Guide:

• TokenBucketStrategy: Best for APIs, allows bursts, good for user-facing applications
• FixedWindowStrategy: Simple and memory efficient, but can have boundary burst issues
• SlidingWindowStrategy: Smooth rate limiting, higher memory usage, best for strict limits
• LeakyBucketStrategy: Constant rate processing, good for resource protection
• AdaptiveStrategy: Experimental, adjusts based on client behavior

Security Considerations:

• Always configure TrustedProxies when behind load balancers/CDNs
• Set appropriate MaxKeyLength to prevent memory exhaustion attacks
• Use secure key extraction to prevent rate limit bypassing
• Consider using HTTPS to prevent header manipulation
• Monitor for suspicious patterns and adjust limits accordingly

Performance Considerations:

• TokenBucket and FixedWindow are most memory efficient
• SlidingWindow uses more memory but provides smoother limiting
• Set appropriate CleanupInterval based on traffic patterns
• Consider using multiple middleware instances for different rate limits
• Use SkipFunc judiciously to avoid unnecessary processing

app := flash.New()
strategy := NewTokenBucketStrategy(100, time.Minute)
app.Use(RateLimit(WithStrategy(strategy)))
app.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "success"})
})

app := flash.New()
strategy := NewTokenBucketStrategy(50, time.Minute)

// Combine multiple options for sophisticated rate limiting
app.Use(RateLimit(
	WithStrategy(strategy),
	WithKeyFunc(func(c flash.Ctx) string {
		// Rate limit by user ID if available, otherwise by IP
		if userID := c.Context().Value("user_id"); userID != nil {
			return "user:" + userID.(string)
		}
		return "ip:" + c.Request().RemoteAddr
	}),
	WithErrorResponse(func(c flash.Ctx, retryAfter time.Duration) error {
		return c.JSON(map[string]interface{}{
			"error":       "Too many requests",
			"retry_after": int(retryAfter.Seconds()),
			"limit":       50,
			"window":      "1 minute",
		})
	}),
	WithSkipFunc(func(c flash.Ctx) bool {
		// Skip for internal health checks
		return c.Path() == "/health" || c.Context().Value("internal") == true
	}),
))

app.GET("/api", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "api response"})
})

app := flash.New()

// Use RateLimit without specifying a strategy (uses default token bucket)
app.Use(RateLimit()) // Default: 100 requests per minute per IP

app.GET("/default", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "default response"})
})

app := flash.New()

// Public routes with generous limits
publicStrategy := NewTokenBucketStrategy(1000, time.Hour)
app.Use(RateLimit(WithStrategy(publicStrategy)))
app.GET("/", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "public"})
})

// API routes with moderate limits
api := app.Group("/api")
apiStrategy := NewSlidingWindowStrategy(100, time.Minute)
api.Use(RateLimit(WithStrategy(apiStrategy)))
api.GET("/users", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "api users"})
})

// Admin routes with strict limits
admin := app.Group("/admin")
adminStrategy := NewFixedWindowStrategy(10, time.Hour)
admin.Use(RateLimit(WithStrategy(adminStrategy)))
admin.GET("/stats", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "admin stats"})
})

// Authentication routes with very strict limits
auth := app.Group("/auth")
authStrategy := NewLeakyBucketStrategy(1.0, 5) // 1 request per second
auth.Use(RateLimit(WithStrategy(authStrategy)))
auth.POST("/login", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "login"})
})

app := flash.New()

// Adaptive strategy adjusts rate based on client behavior
strategy := NewAdaptiveStrategy(10.0, 1.0, 100.0, time.Minute) // 10-100 req/sec range
app.Use(RateLimit(WithStrategy(strategy)))

app.GET("/adaptive", func(c flash.Ctx) error {
	// In your application logic, provide feedback to the strategy
	// strategy.UpdateRate(clientKey, true)  // Good behavior
	// strategy.UpdateRate(clientKey, false) // Bad behavior
	return c.JSON(map[string]string{"message": "adaptive response"})
})

app := flash.New()
strategy := NewTokenBucketStrategy(5, time.Minute)

// Custom error response with JSON format
app.Use(RateLimit(
	WithStrategy(strategy),
	WithErrorResponse(func(c flash.Ctx, retryAfter time.Duration) error {
		return c.JSON(map[string]interface{}{
			"error":       "Rate limit exceeded",
			"retry_after": int(retryAfter.Seconds()),
			"limit_type":  "token_bucket",
		})
	}),
))

app.GET("/api", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "api response"})
})

app := flash.New()
strategy := NewTokenBucketStrategy(10, time.Minute)

// Rate limit by user ID instead of IP
app.Use(RateLimit(
	WithStrategy(strategy),
	WithKeyFunc(func(c flash.Ctx) string {
		if userID := c.Context().Value("user_id"); userID != nil {
			return userID.(string)
		}
		return "anonymous"
	}),
))

app.GET("/user", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "user response"})
})

app := flash.New()

// Fixed window resets counter at fixed intervals (allows bursts at boundaries)
strategy := NewFixedWindowStrategy(100, time.Hour) // 100 requests per hour window
app.Use(RateLimit(WithStrategy(strategy)))

app.GET("/public", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "public response"})
})

app := flash.New()

// Leaky bucket processes requests at fixed rate, queues excess
strategy := NewLeakyBucketStrategy(5.0, 10) // 5 requests per second, capacity for 10 queued
app.Use(RateLimit(WithStrategy(strategy)))

app.GET("/streaming", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "streaming response"})
})

app := flash.New()
strategy := NewTokenBucketStrategy(10, time.Minute)

// Skip rate limiting for admin users or health checks
app.Use(RateLimit(
	WithStrategy(strategy),
	WithSkipFunc(func(c flash.Ctx) bool {
		// Skip for admin users
		if c.Context().Value("admin") == true {
			return true
		}
		// Skip for health checks
		if c.Path() == "/health" {
			return true
		}
		return false
	}),
))

app.GET("/api", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "api response"})
})

app.GET("/health", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"status": "healthy"})
})

app := flash.New()

// Sliding window provides smooth rate limiting without burst issues
strategy := NewSlidingWindowStrategy(10, time.Minute) // 10 requests per 1-minute sliding window
app.Use(RateLimit(WithStrategy(strategy)))

app.GET("/sensitive", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "sensitive response"})
})

app := flash.New()

// Token bucket allows bursts up to capacity, then refills over time
strategy := NewTokenBucketStrategy(50, time.Minute) // 50 requests per minute with burst support
app.Use(RateLimit(WithStrategy(strategy)))

app.GET("/api", func(c flash.Ctx) error {
	return c.JSON(map[string]string{"message": "api response"})
})

func Recover ¶

func Recover(cfgs ...RecoverConfig) flash.Middleware

Recover returns middleware that recovers from panics in HTTP handlers with enhanced security and logging.

Security Features:

• Never exposes stack traces or panic details to clients by default
• Configurable logging to prevent information leakage
• Structured error responses without sensitive information
• Safe handling of panic values that might contain sensitive data

This middleware is essential for production applications as it prevents panics from crashing the entire server. When a panic occurs in any handler, the middleware catches it and returns a generic HTTP 500 error response to the client while allowing the server to continue processing other requests.

The middleware uses Go's built-in recover() mechanism to catch panics and converts them to HTTP errors. It's recommended to use this middleware early in the middleware chain, typically as one of the first middleware applied to your application.

Usage Examples:

// Basic usage - secure defaults
app := flash.New()
app.Use(middleware.Recover())

// With custom logging (production-safe)
app.Use(middleware.Recover(middleware.RecoverConfig{
	OnPanic: func(c flash.Ctx, err interface{}) {
		logger := ctx.LoggerFromContext(c.Context())
		logger.Error("panic recovered",
			"error", fmt.Sprintf("%v", err),
			"method", c.Method(),
			"path", c.Path(),
			"user_agent", c.Request().Header.Get("User-Agent"),
		)
	},
}))

// With custom error response
app.Use(middleware.Recover(middleware.RecoverConfig{
	ErrorResponse: func(c flash.Ctx, err interface{}) error {
		return c.JSON(http.StatusInternalServerError, map[string]interface{}{
			"error": "Service temporarily unavailable",
			"code":  "SERVICE_ERROR",
			"retry_after": 60,
		})
	},
}))

// Development configuration (with stack traces)
if os.Getenv("ENV") == "development" {
	app.Use(middleware.Recover(middleware.RecoverConfig{
		EnableStack: true,
		OnPanic: func(c flash.Ctx, err interface{}) {
			log.Printf("PANIC: %v\nStack: %s", err, debug.Stack())
		},
	}))
}

// With other essential middleware
app.Use(
    middleware.RequestID(),
    middleware.Logger(),
    middleware.Recover(), // Should be early in the chain
)

// Example handler that might panic
app.Get("/users/:id", func(c flash.Ctx) error {
    id := c.Param("id")
    if id == "panic" {
        panic("intentional panic for testing")
    }
    // Normal handler logic
    return c.JSON(200, map[string]string{"id": id})
})

// On specific route groups
api := app.Group("/api")
api.Use(middleware.Recover())
api.Get("/data", func(c flash.Ctx) error {
    // This handler is protected from panics
    return c.JSON(200, map[string]string{"data": "protected"})
})

Error Response (default):

// When a panic occurs, the client receives:
// HTTP/1.1 500 Internal Server Error
// Content-Type: text/plain; charset=utf-8
// X-Content-Type-Options: nosniff
// Content-Length: 21
//
// Internal Server Error

Panic Scenarios Handled:

// 1. Nil pointer dereference
app.Get("/nil", func(c flash.Ctx) error {
    var data *map[string]string
    _ = (*data)["key"] // This would panic without Recover middleware
    return nil
})

// 2. Array/slice index out of bounds
app.Get("/bounds", func(c flash.Ctx) error {
    arr := []int{1, 2, 3}
    _ = arr[10] // This would panic without Recover middleware
    return nil
})

// 3. Type assertions
app.Get("/assert", func(c flash.Ctx) error {
    var i interface{} = "string"
    _ = i.(int) // This would panic without Recover middleware
    return nil
})

// 4. Division by zero
app.Get("/divide", func(c flash.Ctx) error {
    x := 10
    y := 0
    _ = x / y // This would panic without Recover middleware
    return nil
})

// 5. Manual panics
app.Get("/manual", func(c flash.Ctx) error {
    panic("something went wrong")
})

Best Practices:

// 1. Always use Recover middleware in production
// 2. Place it early in the middleware chain
// 3. Combine with logging middleware to track panics
// 4. Never expose panic details to clients in production
// 5. Use structured logging for panic analysis

app.Use(
    middleware.RequestID(),
    middleware.Logger(),
    middleware.Recover(), // Early in chain
    middleware.CORS(),
    middleware.Timeout(30 * time.Second),
)

Performance Impact:

// The Recover middleware has minimal performance overhead
// It only adds a defer function that's only executed when panics occur
// In normal operation, there's virtually no performance cost

func RequestID ¶

func RequestID(cfgs ...RequestIDConfig) flash.Middleware

RequestID returns middleware that adds a unique request ID to each request/response. The request ID is set in the configured header and made available in the request context.

func RequestIDFromContext ¶

func RequestIDFromContext(ctx context.Context) (string, bool)

RequestIDFromContext returns the request ID from the context, if available.

func RequestSize ¶

func RequestSize(cfg RequestSizeConfig) flash.Middleware

RequestSize returns middleware that limits the maximum size of request bodies.

Security Features:

• Prevents memory exhaustion attacks through large request bodies
• Early rejection before body parsing to minimize resource usage
• Configurable limits for different application needs
• Secure error responses that don't leak sensitive information

Performance Features:

• Zero-allocation size checking using Content-Length header
• Early rejection prevents unnecessary request processing
• Minimal overhead for requests within size limits
• No impact on request streaming or processing speed

Behavior:

• Checks Content-Length header before processing request body
• Returns 413 Request Entity Too Large for oversized requests
• Allows requests without Content-Length header (e.g., chunked encoding)
• Works with all HTTP methods and content types

Usage Examples:

// Basic usage with 5MB limit
app.Use(middleware.RequestSize(middleware.RequestSizeConfig{
	MaxSize: 5 << 20, // 5MB
}))

// API-specific limits
app.Use(middleware.RequestSize(middleware.RequestSizeConfig{
	MaxSize: 1 << 20, // 1MB for JSON APIs
}))

// File upload endpoints with higher limits
uploadGroup := app.Group("/upload")
uploadGroup.Use(middleware.RequestSize(middleware.RequestSizeConfig{
	MaxSize: 100 << 20, // 100MB for file uploads
}))

// Custom error handling
app.Use(middleware.RequestSize(middleware.RequestSizeConfig{
	MaxSize: 10 << 20, // 10MB
	ErrorResponse: func(c flash.Ctx, size, limit int64) error {
		// Log the attempt
		logger := ctx.LoggerFromContext(c.Context())
		logger.Warn("request size limit exceeded",
			"size", size,
			"limit", limit,
			"path", c.Path(),
			"method", c.Method(),
			"remote_addr", c.Request().RemoteAddr,
		)

		return c.Status(http.StatusRequestEntityTooLarge).JSON(map[string]interface{}{
			"error": "Request entity too large",
			"code":  "REQUEST_TOO_LARGE",
			"max_size_bytes": limit,
		})
	},
}))

Security Best Practices:

// Production configuration
app.Use(middleware.RequestSize(middleware.RequestSizeConfig{
	MaxSize: 5 << 20, // Start conservative - 5MB
	ErrorResponse: func(c flash.Ctx, size, limit int64) error {
		// Log for monitoring but don't expose details to client
		logger := ctx.LoggerFromContext(c.Context())
		logger.Warn("request size limit exceeded",
			"size", size,
			"limit", limit,
			"user_agent", c.Request().Header.Get("User-Agent"),
			"remote_addr", c.Request().RemoteAddr,
		)

		return c.Status(http.StatusRequestEntityTooLarge).JSON(map[string]interface{}{
			"error": "Request entity too large",
		})
	},
}))

Common Size Limits:

• JSON APIs: 1MB (1 << 20)
• Form submissions: 5MB (5 << 20)
• File uploads: 50-100MB (50 << 20 to 100 << 20)
• Image uploads: 10MB (10 << 20)
• Document uploads: 25MB (25 << 20)

Performance Impact:

• Minimal overhead: only checks Content-Length header
• No memory allocation for size validation
• Early rejection prevents wasted CPU cycles
• Zero impact on legitimate requests within limits

func Sessions ¶

func Sessions(cfg SessionConfig) flash.Middleware

Sessions returns middleware that provides secure session management for HTTP requests.

This middleware handles the complete session lifecycle including loading existing sessions, creating new sessions, managing session data, and persisting changes. It integrates with any Store implementation and provides comprehensive security features.

Key Features:

• Automatic session loading and saving
• Secure session ID generation with cryptographic randomness
• Session regeneration to prevent fixation attacks
• Flexible transport via cookies and/or headers
• Configurable security attributes (Secure, HTTPOnly, SameSite)
• Support for both web applications and APIs
• Efficient change tracking to minimize storage operations
• Integration with the flash.Ctx context system

Basic Usage:

app := flash.New()
app.Use(middleware.Sessions(middleware.SessionConfig{
	Store:      middleware.NewMemoryStore(),
	TTL:        24 * time.Hour,
	CookieName: "session_id",
	HTTPOnly:   true,
	Secure:     true, // Enable in production
}))

app.GET("/login", func(c flash.Ctx) error {
	session := middleware.SessionFromCtx(c)
	session.Set("user_id", "12345")
	return c.JSON(200, map[string]string{"status": "logged in"})
})

Advanced Usage with Security Features:

store := middleware.NewMemoryStore()
store.StartCleanup(5 * time.Minute) // Prevent memory leaks
defer store.StopCleanup()

app.Use(middleware.Sessions(middleware.SessionConfig{
	Store:         store,
	TTL:           12 * time.Hour,
	CookieName:    "secure_session",
	CookiePath:    "/",
	Domain:        ".example.com",
	Secure:        true,
	HTTPOnly:      true,
	SameSite:      http.SameSiteStrictMode,
	HeaderName:    "X-Session-ID",
	IdleTimeout:   30 * time.Minute,
	MaxAge:        7 * 24 * time.Hour,
}))

// Login handler with session regeneration
app.POST("/login", func(c flash.Ctx) error {
	// Authenticate user...
	if !authenticateUser(username, password) {
		return c.Status(401).String("Invalid credentials")
	}

	session := middleware.SessionFromCtx(c)
	session.Regenerate() // Prevent session fixation
	session.Set("user_id", userID)
	session.Set("authenticated", true)
	session.Set("login_time", time.Now())

	return c.JSON(200, map[string]string{"status": "logged in"})
})

// Logout handler
app.POST("/logout", func(c flash.Ctx) error {
	session := middleware.SessionFromCtx(c)
	session.Clear() // Clear all session data
	return c.JSON(200, map[string]string{"status": "logged out"})
})

API Usage (Header-based):

app.Use(middleware.Sessions(middleware.SessionConfig{
	Store:      redisStore,
	TTL:        2 * time.Hour,
	HeaderName: "X-Session-Token",
	// No cookie settings for API-only usage
}))

Security Considerations:

• Always set Secure=true in production with HTTPS
• Use HTTPOnly=true to prevent XSS attacks
• Consider SameSite=Strict for maximum CSRF protection
• Implement proper session cleanup to prevent memory leaks
• Use session regeneration after authentication or privilege changes
• Set appropriate TTL values based on your security requirements
• Consider using IdleTimeout for additional security

Performance Considerations:

• Sessions are only saved when data changes (efficient change tracking)
• Use memory-efficient stores like Redis for high-traffic applications
• Configure appropriate cleanup intervals for memory stores
• Consider session data size impact on storage and network
• Use header-based transport for APIs to avoid cookie overhead

func Timeout ¶

func Timeout(cfg TimeoutConfig) flash.Middleware

Timeout returns middleware that applies a timeout to the request context with enhanced security features.

Security Features:

• Proper context cancellation to prevent goroutine leaks
• Safe timeout handling with race condition prevention
• Protected timeout callbacks to prevent secondary failures

Performance Features:

• Efficient goroutine management with proper cleanup
• Minimal overhead for requests that complete within timeout
• Optimized header handling to reduce allocations

Example Usage:

// Basic timeout
app.Use(middleware.Timeout(middleware.TimeoutConfig{
	Duration: 30 * time.Second,
}))

// With longer timeout for slow operations
app.Use(middleware.Timeout(middleware.TimeoutConfig{
	Duration: 60 * time.Second, // 1 minute for file processing
}))

// With custom timeout handling
app.Use(middleware.Timeout(middleware.TimeoutConfig{
	Duration: 30 * time.Second,
	OnTimeout: func(c flash.Ctx) {
		// Log timeout (non-blocking)
		go func() {
			log.Printf("Request timeout: %s %s from %s",
				c.Method(), c.Path(), c.Request().RemoteAddr)
		}()
	},
	ErrorResponse: func(c flash.Ctx) error {
		return c.JSON(http.StatusGatewayTimeout, map[string]interface{}{
			"error":   "Request timeout",
			"code":    "GATEWAY_TIMEOUT",
			"timeout": "30s",
		})
	},
}))

func WithLoggerAttributes ¶

func WithLoggerAttributes(ctx context.Context, attrs *LoggerAttributes) context.Context

WithLoggerAttributes adds custom attributes to the context for logging. These attributes will be included in the request log when using the Logger middleware.

Usage Examples:

// Add custom attributes in middleware or handlers
attrs := middleware.NewLoggerAttributes("user_id", "123", "operation", "create")
ctx := middleware.WithLoggerAttributes(c.Context(), attrs)
c.SetRequest(c.Request().WithContext(ctx))

// Or add attributes directly
ctx := middleware.WithLoggerAttributes(c.Context(),
    middleware.NewLoggerAttributes("user_id", "123", "operation", "create"))
c.SetRequest(c.Request().WithContext(ctx))

app := flash.New()
app.Use(Logger())

// Middleware that adds custom attributes
app.Use(func(next flash.Handler) flash.Handler {
	return func(c flash.Ctx) error {
		// Add custom attributes to context
		attrs := NewLoggerAttributes("middleware", "auth", "version", "v2")
		ctx := WithLoggerAttributes(c.Context(), attrs)
		c.SetRequest(c.Request().WithContext(ctx))
		return next(c)
	}
})

app.GET("/users/:id", func(c flash.Ctx) error {
	// Add dynamic attributes in handler
	userID := c.Param("id")
	attrs := NewLoggerAttributes("user_id", userID, "operation", "fetch")
	ctx := WithLoggerAttributes(c.Context(), attrs)
	c.SetRequest(c.Request().WithContext(ctx))

	return c.JSON(map[string]string{"id": userID})
})