Download the PHP package largerio/laravel-concurrent-limiter without Composer

Laravel Concurrent Limiter

A Laravel middleware package that limits the number of concurrent requests per user (or IP). Unlike rate limiting which counts requests over time, this package controls how many requests can be processed simultaneously.

Features

• HTTP Middleware - Limit concurrent requests per user/IP with automatic queuing
• Job Middleware - Limit concurrent queue job execution to protect external APIs
• Adaptive Limiting - Auto-adjust limits based on latency using AIMD algorithm
• Prometheus Metrics - Built-in /metrics endpoint for monitoring
• Fail-safe - Configurable behavior when cache is unavailable
• Events - Full request lifecycle tracking (wait, acquire, release, exceed)
• Extensible - Custom key resolvers and response handlers

Requirements

• PHP 8.3 or higher
• Laravel 11.x or 12.x
• Cache store with atomic operations (Redis recommended)

Table of Contents

• Quick Start
• Installation
• HTTP Middleware
• Job Middleware
• Configuration
• Adaptive Limiting
• Events
• Custom Key Resolver
• Custom Response Handler
• Prometheus Metrics
• Cache
• Artisan Commands
• Troubleshooting
• License

Quick Start

This limits each user to 5 concurrent requests, waiting up to 30 seconds for a slot before returning 503.

Installation

Install via Composer:

The service provider is auto-discovered. To publish the config file:

HTTP Middleware

Apply the middleware to routes using the concurrent.limit alias:

Or use the static helper:

How it works:

1. Generates a unique key based on user ID (or IP if unauthenticated)
2. Increments a counter in cache
3. If over limit, waits (polling every 100ms) until a slot is free
4. If timeout reached, returns 503 with JSON error
5. After processing, decrements the counter

Job Middleware

Limit concurrent execution of queued jobs to protect external APIs or shared resources:

Parameters:

Use Cases:

• Limit API calls to third-party services (Stripe, Twilio, etc.)
• Prevent database overload from batch processing
• Control concurrent file processing or exports

Configuration

Adaptive Limiting

Automatically adjust maxParallel based on observed response latency using algorithms inspired by Netflix's concurrency-limits library.

Available Algorithms

Vegas (default) - Based on TCP Vegas congestion control:

• Tracks minimum RTT (best-case latency) as baseline
• Compares current latency to baseline to detect queueing
• Uses dynamic alpha/beta thresholds based on current limit
• Best for: Server-side protection, proactive congestion detection

Gradient2 - Based on EWMA divergence:

• Tracks short-term and long-term EWMA
• Detects latency trends by comparing the two averages
• Configurable tolerance for latency increase
• Best for: Detecting gradual degradation, noisy environments

Enable Adaptive Limiting

How Adaptive Interacts with maxParallel

When adaptive limiting is enabled, the maxParallel parameter from your route acts as a hard cap:

This ensures that adaptive limiting is a safety optimization - it can reduce load when latency degrades, but never allows more concurrent requests than you explicitly configured.

Vegas Algorithm Details

Formula:

Example: With limit=10, minRTT=100ms, avgRTT=100ms:

• gradient = 1.0, queueUse = 0
• 0 < alpha (1) → increase to 11

Gradient2 Algorithm Details

Formula:

Example: With tolerance=2.0, shortEWMA=200ms, longEWMA=100ms:

• gradient = 0.5, threshold = 0.5
• 0.5 >= 0.5 → stable (just within tolerance)

Use Cases

• Auto-scaling protection: Automatically reduce concurrency when backend is overloaded
• Variable workloads: Handle traffic spikes without manual tuning
• Proactive detection: Vegas detects congestion before timeouts occur

Monitoring

Access metrics programmatically:

Events

The middleware dispatches events for monitoring and logging:

Example listener:

Custom Key Resolver

By default, the middleware uses the authenticated user ID or IP address. Implement KeyResolver to customize:

Register in config:

Custom Response Handler

Customize the 503 response by implementing ResponseHandler:

Register in config:

Prometheus Metrics

Enable Prometheus-compatible metrics for monitoring:

Available Metrics:

Example Output:

Grafana Tips:

• Alert on rate(concurrent_limiter_exceeded_total[5m]) > 10
• Monitor p99 wait time with histogram quantiles
• Track cache failures for infrastructure issues

Cache

Store Recommendations

The middleware requires a cache store that supports atomic operations:

Configure in config/concurrent-limiter.php:

Key Structure

Failure Handling

By default, if cache is unavailable, requests are allowed through (fail-open). For critical endpoints:

Artisan Commands

Check Counter Status

Clear Stuck Counters

Troubleshooting

Always getting 503 errors

1. Check maxParallel setting - It might be too low for your traffic
2. Verify cache is working - Test with Cache::put('test', 1); Cache::get('test');
3. Check for stuck counters - They expire after maxWaitTime + ttl_buffer seconds

Requests not being limited

1. Verify middleware is applied - Run php artisan route:list
2. Check cache store - array driver doesn't persist between requests
3. Different users/IPs - Each user/IP has their own limit

Performance issues

1. Use Redis - Fastest option with proper locking support
2. Reduce maxWaitTime - Lower wait times free up resources faster
3. Tune maxParallel - Balance between protection and throughput

Debugging

Enable logging to see when limits are exceeded:

Changelog

See CHANGELOG.md for release history.

License

This package is open-sourced software licensed under the MIT license.