Token bucket rate limiter. More...

#include <rate_limiter.h>

Collaboration diagram for kcenon::network::rate_limiter:

Classes
struct	bucket

Public Member Functions
	rate_limiter (rate_limiter_config config={})
	Construct rate limiter with configuration.

bool	allow (std::string_view client_id)
	Check if request should be allowed.

bool	allow (std::string_view client_id, std::string_view session_id)
	Check if request should be allowed (session-aware)

bool	would_allow (std::string_view client_id) const
	Check if request would be allowed (without consuming token)

double	remaining_tokens (std::string_view client_id) const
	Get remaining tokens for a client.

void	reset (std::string_view client_id)
	Reset rate limit for a specific client.

void	reset_all ()
	Reset all rate limits.

size_t	client_count () const
	Get number of tracked clients.

void	set_config (rate_limiter_config config)
	Update configuration.

rate_limiter_config	config () const
	Get current configuration.

Private Member Functions
void	maybe_cleanup (std::chrono::steady_clock::time_point now)

Private Attributes
rate_limiter_config	config_

std::shared_mutex	mutex_

std::unordered_map< std::string, bucket >	buckets_

std::chrono::steady_clock::time_point	last_cleanup_

Detailed Description

Token bucket rate limiter.

Implements a token bucket algorithm for rate limiting. Each client is identified by a string key (typically IP address).

Thread Safety

This class is thread-safe. All public methods can be called from multiple threads concurrently.

Algorithm

Each client has a bucket with capacity = burst_size
Tokens are added at rate = max_requests_per_second
Each request consumes one token
If no tokens available, request is denied

Definition at line 82 of file rate_limiter.h.

Constructor & Destructor Documentation

◆ rate_limiter()

kcenon::network::rate_limiter::rate_limiter ( rate_limiter_config config = {} )

inlineexplicit

Construct rate limiter with configuration.

Parameters

config Rate limiter configuration

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 88 of file rate_limiter.h.

                                                       {})
        : config_(std::move(config))
        , last_cleanup_(std::chrono::steady_clock::now()) {}

Member Function Documentation

◆ allow() [1/2]

bool kcenon::network::rate_limiter::allow ( std::string_view client_id )

inlinenodiscard

Check if request should be allowed.

Parameters

client_id Client identifier (e.g., IP address)

Returns: true if request is allowed, false if rate limited

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 98 of file rate_limiter.h.

                                                       {
        std::unique_lock<std::shared_mutex> lock(mutex_);
 
        auto now = std::chrono::steady_clock::now();
 
        // Periodic cleanup
        if (config_.auto_cleanup) {
            maybe_cleanup(now);
        }
 
        std::string key(client_id);
        auto& bucket = buckets_[key];
 
        // Initialize new bucket
        if (bucket.last_refill.time_since_epoch().count() == 0) {
            bucket.tokens = static_cast<double>(config_.burst_size);
            bucket.last_refill = now;
        }
 
        // Refill tokens based on elapsed time
        auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
            now - bucket.last_refill);
 
        double tokens_to_add = elapsed.count() *
            (static_cast<double>(config_.max_requests_per_second) / 1000.0);
 
        bucket.tokens = std::min(
            static_cast<double>(config_.burst_size),
            bucket.tokens + tokens_to_add);
        bucket.last_refill = now;
 
        // Try to consume a token
        if (bucket.tokens >= 1.0) {
            bucket.tokens -= 1.0;
            return true;
        }
 
        return false;
    }

References kcenon::network::rate_limiter_config::auto_cleanup, buckets_, kcenon::network::rate_limiter_config::burst_size, config_, kcenon::network::rate_limiter::bucket::last_refill, kcenon::network::rate_limiter_config::max_requests_per_second, maybe_cleanup(), mutex_, and kcenon::network::rate_limiter::bucket::tokens.

Referenced by allow().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ allow() [2/2]

bool kcenon::network::rate_limiter::allow	(	std::string_view	client_id,
		std::string_view	session_id )

inlinenodiscard

Check if request should be allowed (session-aware)

Parameters

client_id	Client identifier (e.g., IP address)
session_id	Session identifier for per-session rate limiting

Returns: true if request is allowed, false if rate limited

When session_id is non-empty, a composite key "client_id:session_id" is used, enabling per-session rate limiting. When session_id is empty, falls back to client_id-only behavior.

Definition at line 149 of file rate_limiter.h.

                                                                                  {
        if (session_id.empty()) {
            return allow(client_id);
        }
        std::string composite_key;
        composite_key.reserve(client_id.size() + 1 + session_id.size());
        composite_key.append(client_id);
        composite_key.push_back(':');
        composite_key.append(session_id);
        return allow(std::string_view(composite_key));
    }

References allow().

Here is the call graph for this function:

◆ client_count()

size_t kcenon::network::rate_limiter::client_count ( ) const

inlinenodiscard

Get number of tracked clients.

Returns: Number of clients in rate limiter

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 236 of file rate_limiter.h.

                                              {
        std::shared_lock<std::shared_mutex> lock(mutex_);
        return buckets_.size();
    }

References buckets_, and mutex_.

◆ config()

rate_limiter_config kcenon::network::rate_limiter::config ( ) const

inlinenodiscard

Get current configuration.

Returns: Current configuration

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 254 of file rate_limiter.h.

                                                     {
        std::shared_lock<std::shared_mutex> lock(mutex_);
        return config_;
    }

References config_, and mutex_.

Referenced by set_config().

Here is the caller graph for this function:

◆ maybe_cleanup()

void kcenon::network::rate_limiter::maybe_cleanup ( std::chrono::steady_clock::time_point now )

inlineprivate

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 265 of file rate_limiter.h.

                                                            {
        // Cleanup at most once per minute
        auto since_cleanup = std::chrono::duration_cast<std::chrono::seconds>(
            now - last_cleanup_);
 
        if (since_cleanup < std::chrono::seconds(60)) {
            return;
        }
 
        last_cleanup_ = now;
 
        // Remove stale entries
        for (auto it = buckets_.begin(); it != buckets_.end();) {
            auto since_refill = std::chrono::duration_cast<std::chrono::seconds>(
                now - it->second.last_refill);
 
            if (since_refill > config_.stale_timeout) {
                it = buckets_.erase(it);
            } else {
                ++it;
            }
        }
    }

References buckets_, config_, last_cleanup_, and kcenon::network::rate_limiter_config::stale_timeout.

Referenced by allow().

Here is the caller graph for this function:

◆ remaining_tokens()

double kcenon::network::rate_limiter::remaining_tokens ( std::string_view client_id ) const

inlinenodiscard

Get remaining tokens for a client.

Parameters

client_id Client identifier

Returns: Number of remaining tokens

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 195 of file rate_limiter.h.

                                                                          {
        std::shared_lock<std::shared_mutex> lock(mutex_);
 
        auto it = buckets_.find(std::string(client_id));
        if (it == buckets_.end()) {
            return static_cast<double>(config_.burst_size);
        }
 
        auto now = std::chrono::steady_clock::now();
        auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
            now - it->second.last_refill);
 
        double tokens_to_add = elapsed.count() *
            (static_cast<double>(config_.max_requests_per_second) / 1000.0);
 
        return std::min(
            static_cast<double>(config_.burst_size),
            it->second.tokens + tokens_to_add);
    }

References buckets_, kcenon::network::rate_limiter_config::burst_size, config_, kcenon::network::rate_limiter_config::max_requests_per_second, and mutex_.

◆ reset()

void kcenon::network::rate_limiter::reset ( std::string_view client_id )

inline

Reset rate limit for a specific client.

Parameters

client_id Client identifier

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 219 of file rate_limiter.h.

                                         {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        buckets_.erase(std::string(client_id));
    }

References buckets_, and mutex_.

◆ reset_all()

void kcenon::network::rate_limiter::reset_all ( )

inline

Reset all rate limits.

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 227 of file rate_limiter.h.

                     {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        buckets_.clear();
    }

References buckets_, and mutex_.

◆ set_config()

void kcenon::network::rate_limiter::set_config ( rate_limiter_config config )

inline

Update configuration.

Parameters

config New configuration

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 245 of file rate_limiter.h.

                                                {
        std::unique_lock<std::shared_mutex> lock(mutex_);
        config_ = std::move(config);
    }

References config(), config_, and mutex_.

Here is the call graph for this function:

◆ would_allow()

bool kcenon::network::rate_limiter::would_allow ( std::string_view client_id ) const

inlinenodiscard

Check if request would be allowed (without consuming token)

Parameters

client_id Client identifier

Returns: true if a request would be allowed

Examples: /home/runner/work/network_system/network_system/src/internal/utils/rate_limiter.h.

Definition at line 167 of file rate_limiter.h.

                                                                   {
        std::shared_lock<std::shared_mutex> lock(mutex_);
 
        auto it = buckets_.find(std::string(client_id));
        if (it == buckets_.end()) {
            return true; // New client would have full bucket
        }
 
        auto now = std::chrono::steady_clock::now();
        auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
            now - it->second.last_refill);
 
        double tokens_to_add = elapsed.count() *
            (static_cast<double>(config_.max_requests_per_second) / 1000.0);
 
        double available = std::min(
            static_cast<double>(config_.burst_size),
            it->second.tokens + tokens_to_add);
 
        return available >= 1.0;
    }