simple_rate_limiter - Rate Limiting for Eiffel

Overview

simple_rate_limiter is a native rate limiting library for Eiffel. It supports both token bucket and sliding window algorithms, with RFC 6585 compliant HTTP headers for rate limit responses.

Part of the simple_* ecosystem of focused, single-purpose Eiffel libraries.

Quick Start

Installation

Add to your ECF file:

<library name="simple_rate_limiter" location="$SIMPLE_RATE_LIMITER/simple_rate_limiter.ecf"/>

Set environment variable:

set SIMPLE_RATE_LIMITER=D:\path\to\simple_rate_limiter

Basic Usage

local
    limiter: SIMPLE_RATE_LIMITER
    result: RATE_LIMIT_RESULT
do
    -- Create with defaults: 100 requests per minute
    create limiter.make

    -- Check rate limit for a key
    result := limiter.check_limit ("user_123")

    if result.is_allowed then
        -- Process request
        print ("Allowed, " + result.remaining.out + " remaining")
    else
        -- Rate limited
        print ("Try again in " + result.retry_after.out + " seconds")
    end
end

Custom Limits

-- 50 requests per 30 seconds
create limiter.make_with_limit (50, 30)

-- Or configure after creation
limiter.set_limit (200, 60)  -- 200 per minute

Sliding Window Algorithm

-- Use sliding window instead of token bucket
create limiter.make_sliding_window (100, 120)  -- 100 per 2 minutes

Whitelist/Blacklist

-- VIP users bypass rate limiting
limiter.add_whitelist ("admin")

-- Block abusive users entirely
limiter.add_blacklist ("spammer_ip")

HTTP Response Headers

local
    headers: HASH_TABLE [STRING, STRING]
do
    headers := limiter.rate_limit_headers ("user_123")
    -- Returns: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
    -- Plus Retry-After when rate limited
end

Features

Token Bucket Algorithm

Smooth rate limiting with configurable burst support and gradual token refill.

Sliding Window

Simple fixed-window counting for predictable rate limits.

RFC 6585 Headers

Standard-compliant RateLimit-* headers for HTTP responses.

Whitelist/Blacklist

First-class support for VIP users and blocked keys.

Burst Control

Separate burst limit from sustained rate for flexible policies.

Per-Key Tracking

Independent rate limits for each identifier (user, IP, API key).

Rich Result Object

Detailed response with remaining tokens, reset time, and retry-after.

Design by Contract

Full preconditions, postconditions, and class invariants.

API Summary

Initialization

Feature	Description
`make`	Default: 100 requests per 60 seconds, token bucket
`make_with_limit (limit, window)`	Custom limit and window duration
`make_sliding_window (limit, window)`	Use sliding window algorithm

Configuration

Feature	Description
`set_limit (requests, window)`	Change rate limit settings
`set_burst_limit (max)`	Set maximum burst size

Whitelist/Blacklist

Feature	Description
`add_whitelist (key)`	Always allow this key
`add_blacklist (key)`	Always deny this key
`remove_whitelist (key)`	Remove from whitelist
`remove_blacklist (key)`	Remove from blacklist
`is_whitelisted (key)`	Check if key is whitelisted
`is_blacklisted (key)`	Check if key is blacklisted

Rate Limiting

Feature	Description
`check_limit (key): RATE_LIMIT_RESULT`	Check and consume 1 token
`is_allowed (key): BOOLEAN`	Quick allow/deny check
`consume (key, tokens): BOOLEAN`	Consume multiple tokens
`remaining (key): INTEGER`	Tokens remaining for key
`reset_time (key): DATE_TIME`	When limits reset
`reset (key)`	Reset single key
`reset_all`	Reset all keys

Response Headers

Feature	Description
`rate_limit_headers (key)`	Generate RateLimit-* HTTP headers

RATE_LIMIT_RESULT

Feature	Description
`is_allowed: BOOLEAN`	Was request allowed?
`remaining: INTEGER`	Requests remaining
`reset_time: DATE_TIME`	When window resets
`retry_after: INTEGER`	Seconds until next token

Algorithm Comparison

Algorithm	Pros	Cons
Token Bucket	Smooth rate limiting, allows bursts, gradual refill	Slightly more complex state
Sliding Window	Simple, predictable, exact count	Can allow double rate at window boundaries

Testing

The library includes a comprehensive test suite with 24 tests covering:

Initialization (default, custom limits, sliding window)
Configuration (limits, burst)
Whitelist/blacklist management
Token bucket algorithm
Sliding window algorithm
Reset functionality
HTTP header generation

-- Run tests
ec.exe -batch -config simple_rate_limiter.ecf -target simple_rate_limiter_tests -c_compile
./EIFGENs/simple_rate_limiter_tests/W_code/simple_rate_limiter.exe