Copyright	(c) 2025 Oleksandr Zhabenko
License	MIT
Maintainer	oleksandr.zhabenko@yahoo.com
Stability	stable
Portability	portable
Safe Haskell	None
Language	Haskell2010

Keter.RateLimiter.IPZones

Contents

IP Zone Identification
Zone-specific Caches
Cache Management
Address to Zone Resolution

Description

This module provides zone-based isolation for rate-limiting caches. It enables each IP zone to maintain its own independent instances of rate-limiting algorithms (e.g., token bucket, leaky bucket, sliding window, etc.). This ensures multi-tenant systems can rate-limit different clients or groups in isolation.

The primary structure here is ZoneSpecificCaches, which contains multiple caches per zone. Utility functions allow dynamic creation, reset, and lookup of caches for specific zones.

Synopsis

type IPZoneIdentifier = Text
defaultIPZone :: IPZoneIdentifier
data ZoneSpecificCaches = ZoneSpecificCaches {
- zscCounterCache :: Cache (InMemoryStore 'FixedWindow)
- zscTimestampCache :: Cache (InMemoryStore 'SlidingWindow)
- zscTokenBucketCache :: Cache (InMemoryStore 'TokenBucket)
- zscLeakyBucketCache :: Cache (InMemoryStore 'LeakyBucket)
- zscTinyLRUCache :: Cache (InMemoryStore 'TinyLRU)
}
createZoneCaches :: IO ZoneSpecificCaches
newZoneSpecificCaches :: IO ZoneSpecificCaches
resetSingleZoneCaches :: ZoneSpecificCaches -> IO ()
resetZoneCache :: ZoneSpecificCaches -> Algorithm -> IO ()
sockAddrToIPZone :: SockAddr -> IO Text

IP Zone Identification

type IPZoneIdentifier = Text Source #

Type alias representing an identifier for an IP zone.

This is used as a logical namespace or grouping key for assigning and isolating rate limiters. Examples: "default", "zone-a", or "192.168.1.0/24".

defaultIPZone :: IPZoneIdentifier Source #

The default IP zone identifier used when no specific zone is assigned.

Used as a fallback when no zone-specific routing is determined.

Zone-specific Caches

data ZoneSpecificCaches Source #

A collection of caches dedicated to a specific IP zone.

Each cache corresponds to one of the supported rate-limiting algorithms, maintained independently per zone.

Constructors

ZoneSpecificCaches

Fields

zscCounterCache :: Cache (InMemoryStore 'FixedWindow)
Cache for Fixed Window counters.
zscTimestampCache :: Cache (InMemoryStore 'SlidingWindow)
Cache for timestamp lists used in Sliding Window.
zscTokenBucketCache :: Cache (InMemoryStore 'TokenBucket)
Token Bucket cache.
zscLeakyBucketCache :: Cache (InMemoryStore 'LeakyBucket)
Leaky Bucket queue-based cache.
zscTinyLRUCache :: Cache (InMemoryStore 'TinyLRU)
Optional auxiliary LRU cache.

createZoneCaches :: IO ZoneSpecificCaches Source #

Create a new set of caches for a single IP zone.

Each algorithm receives its own store. For LeakyBucket, a background cleanup thread is also started to remove inactive entries periodically.

The cleanup thread runs every 60 seconds and removes entries older than 2 hours.

Examples

Expand

zoneCaches <- createZoneCaches
cacheReset (zscTokenBucketCache zoneCaches)

newZoneSpecificCaches :: IO ZoneSpecificCaches Source #

Alias for createZoneCaches.

Useful for more readable builder-based usage or factory patterns.

Cache Management

resetSingleZoneCaches :: ZoneSpecificCaches -> IO () Source #

Reset all caches within the given ZoneSpecificCaches.

Clears all internal state, including token counts, timestamps, and queues.

Examples

Expand

resetSingleZoneCaches zoneCaches

resetZoneCache :: ZoneSpecificCaches -> Algorithm -> IO () Source #

Reset a single cache for a specific algorithm within the given ZoneSpecificCaches.

This is useful when only one type of rate limiter needs a reset.

Examples

Expand

resetZoneCache zoneCaches TokenBucket

Address to Zone Resolution

sockAddrToIPZone :: SockAddr -> IO Text Source #

Convert a socket address into an IP zone identifier.

IPv4 addresses are rendered using fromHostAddress. IPv6 addresses are expanded and zero-padded for consistency. Any unknown or unsupported address formats fall back to defaultIPZone.

Examples

Expand

zone <- sockAddrToIPZone (SockAddrInet 80 0x7f000001)
print zone  -- "127.0.0.1"