Max Connections

​

Overview

• Connection limiting
• Resource protection
• DoS mitigation

​

Installation

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

​

Quick Start

app := mizu.New()

// Limit to 1000 concurrent connections
app.Use(maxconns.New(1000))

​

Configuration

​

Options

​

Examples

​

Basic Limit

app.Use(maxconns.New(1000))

​

Custom Error

app.Use(maxconns.New(maxconns.Options{
    Max: 1000,
    ErrorHandler: func(c *mizu.Ctx) error {
        return c.JSON(503, map[string]string{
            "error": "Server at capacity",
        })
    },
}))

​

With Monitoring

m := maxconns.NewWithMetrics(1000)
app.Use(m.Middleware())

// Monitor in handler
app.Get("/stats", func(c *mizu.Ctx) error {
    return c.JSON(200, map[string]int{
        "active":  m.Active(),
        "max":     m.Max(),
    })
})

​

API Reference

​

Functions

// New creates max connections middleware
func New(max int) mizu.Middleware

// NewWithOptions creates with configuration
func NewWithOptions(opts Options) mizu.Middleware

// NewWithMetrics creates with metrics tracking
func NewWithMetrics(max int) *MaxConns

​

Technical Details

​

Implementation Architecture

• Uses atomic.LoadInt64 and atomic.AddInt64 for lock-free global connection counting
• Atomic operations ensure thread-safe increments/decrements without mutex overhead
• Counter is incremented before processing and decremented via defer after completion

• Maintains a map[string]int for per-IP connection counts
• Protected by sync.RWMutex to allow concurrent reads with exclusive writes
• IP addresses extracted from X-Forwarded-For, X-Real-IP, or RemoteAddr headers
• Map entries automatically cleaned up when IP count reaches zero

1. Check global limit using atomic load operation
2. If PerIP enabled, check IP-specific limit under read lock
3. Increment both counters (atomic for global, locked for per-IP)
4. Process request through handler chain
5. Decrement counters via defer (guarantees cleanup even on errors)

• When Max <= 0, middleware immediately rejects all requests
• Optimized fast path that bypasses counter management

• Default response: 503 Service Unavailable with “Retry-After: 60” header
• Custom error handlers can be configured via Options
• Error handler receives full context for custom responses

​

Key Components

• Provides observable connection metrics
• Exposes Current() and Max() methods for monitoring
• Can be used standalone for custom monitoring solutions

• Global(max): Alias for New(max) for semantic clarity
• PerIP(max): Convenience function setting per-IP limit with high global max (1,000,000)
• getClientIP(): Extracts client IP from standard proxy headers

​

Best Practices

• Set based on server capacity
• Monitor connection counts
• Use with rate limiting
• Return appropriate error response

​

Testing

​

Related Middlewares

• bulkhead - Bulkhead pattern
• ratelimit - Rate limiting
• keepalive - Connection persistence