Concurrency

​

Overview

• Limit CPU-intensive operations
• Control database connection usage
• Prevent memory exhaustion

​

Installation

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

​

Quick Start

app := mizu.New()

// Max 50 concurrent requests
app.Use(concurrency.New(50))

​

Configuration

​

Options

​

Examples

​

Basic Limit

app.Use(concurrency.New(50))

​

Custom Error

app.Use(concurrency.WithOptions(concurrency.Options{
    Limit: 50,
    ErrorHandler: func(c *mizu.Ctx) error {
        return c.JSON(503, map[string]string{
            "error": "Too many concurrent requests",
        })
    },
}))

​

Per-Route Limits

// Heavy endpoints
heavy := app.Group("/heavy")
heavy.Use(concurrency.New(5))

// Light endpoints
light := app.Group("/api")
light.Use(concurrency.New(100))

​

API Reference

​

Functions

// New creates concurrency limiter
func New(limit int) mizu.Middleware

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

​

Technical Details

​

Implementation Mechanisms

1. Semaphore Pattern: Uses a buffered channel with capacity equal to the maximum concurrent requests limit
2. Non-blocking Acquisition: The default New() and WithOptions() use select with default to immediately reject requests when at capacity
3. Blocking Acquisition: The Blocking() variant blocks requests until a slot becomes available
4. Context-aware: The WithContext() variant respects context cancellation while waiting for a slot

​

Core Components

• Options struct: Configures maximum concurrent requests and custom error handling
• Semaphore channel: Controls access to the handler based on the configured limit
• Deferred release: Ensures semaphore slots are released even if the handler panics
• Retry-After header: Automatically set to “1” second when requests are rejected

​

Behavior Patterns

• Zero or negative limit: Immediately rejects all requests with 503 Service Unavailable
• Default error response: Returns 503 with “Server at capacity” message
• Custom error handler: Allows full control over rejection response format and status code

​

Best Practices

• Set limits based on resource capacity
• Monitor concurrent request counts
• Use different limits for different workloads
• Combine with timeout for hung requests

​

Testing

​

Related Middlewares

• bulkhead - Bulkhead pattern
• ratelimit - Rate limiting
• timeout - Request timeout