This PR implements a RateLimiter for airframe-control using a token bucket algorithm to control the rate of operations. This addresses the need for rate limiting and retry budget control mentioned in the issue.

Features

Core Functionality

• Token bucket algorithm with configurable permits per second and burst size
• Thread-safe implementation using atomic operations with immutable state
• Cross-platform compatibility (JVM, JS, Native) using Compat.sleep
• Blocking and non-blocking operations: acquire() and tryAcquire() methods
• Timeout support: tryAcquire(permits, timeout, unit)

Usage Examples

Basic rate limiting:

import wvlet.airframe.control.RateLimiter

// Allow 10 permits per second
val limiter = RateLimiter.create(10.0)

// Acquire a permit (blocks if necessary)
limiter.acquire()

// Try to acquire without blocking
if (limiter.tryAcquire()) {
  // Permit acquired
}

Burst control:

// Allow 5 permits/sec with burst of up to 20 permits
val limiter = RateLimiter.create(5.0, 20)

// Can immediately acquire up to 20 permits
for (_ <- 1 to 20) {
  limiter.tryAcquire() // All succeed immediately
}

Per-host rate limiting:

import scala.collection.concurrent.TrieMap

val hostLimiters = TrieMap.empty[String, RateLimiter]

def getRateLimiter(host: String): RateLimiter = {
  hostLimiters.getOrElseUpdate(host, RateLimiter.create(10.0))
}

def makeRequest(host: String, request: Request): Response = {
  val limiter = getRateLimiter(host)
  limiter.acquire() // Wait for permit
  sendRequest(host, request)
}

Implementation Details

Key Design Decisions

• Separate blocking/non-blocking logic: tryReservePermits (non-blocking) doesn't allow token bucket to go negative, while reservePermits (blocking) can reserve future tokens
• Atomic state management: Uses AtomicReference[RateLimiterState] with immutable case class for thread safety
• Configurable burst size: Defaults to permitsPerSecond but can be customized
• Cross-platform sleep: Uses Compat.sleep for millisecond-level precision across platforms

Test Coverage

• 22 comprehensive tests covering basic functionality, edge cases, concurrency, and time-based behavior
• Manual ticker support for deterministic testing
• Parameter validation and error handling

Documentation

Added comprehensive documentation to airframe-control.md with:

• Basic usage examples
• Burst control configuration
• Integration patterns with retry mechanisms
• Per-host rate limiting implementation

The implementation provides a foundation for maintaining average traffic rates and implementing retry budgets as mentioned in the original issue, complementing the existing retry and circuit breaker functionality in airframe-control.

Fixes #1027.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.