/ 
PAGI-FastAPI-RateLimit-Driver-CHI-v0.0.1
/ PAGI::FastAPI::RateLimit::Driver::CHI

NAME

PAGI::FastAPI::RateLimit::Driver::CHI - CHI Storage Driver for PAGI::FastAPI Rate Limiting

VERSION

Version v0.0.1

SYNOPSIS

use PAGI::FastAPI;
use PAGI::FastAPI::RateLimit::Driver::CHI;
use CHI;

# Initialise any CHI driver instance
my $chi = CHI->new(
    driver    => 'Memcached',
    servers   => [ "127.0.0.1:11211" ],
    namespace => 'pagi_rate_limit',
);

# Instantiate the rate limiting driver
my $driver = PAGI::FastAPI::RateLimit::Driver::CHI->new(
    chi        => $chi,
    key_prefix => 'api_rl:', # Optional custom prefix
);

my $app = PAGI::FastAPI->new();

# Register rate limiter with the CHI driver
$app->add_rate_limit(
    requests => 100,
    window   => 60,
    driver   => $driver,
);

DESCRIPTION

PAGI::FastAPI::RateLimit::Driver::CHI is a storage driver plugin for PAGI::FastAPI::Middleware::RateLimit. It enables PAGI::FastAPI applications to leverage any caching backend supported by CHI, including Memcached, Redis, FastMmap, SharedMemory, and File-based caches.

By delegating state management to CHI, you can easily share rate-limiting hit counters across multiple web server worker processes or distributed application nodes.

CONSTRUCTOR

new(%options)

Instantiates a new CHI rate-limiting driver.

Accepts the following named parameters:

  • chi (Required)

    An initialised CHI cache instance.

  • key_prefix (Optional)

    A scalar string prepended to keys inside the CHI cache to prevent namespace collisions. Defaults to 'pagi_rl:'.

METHODS

Inherits all methods from PAGI::FastAPI::RateLimit::Driver.

increment_async($key, $ttl)

my $future = $driver->increment_async($key, $ttl);

Increments the hit count for $key by 1 within the CHI cache and manages window expiration timestamps.

Returns a Future resolving to an integer containing the updated request count.

get_async($key)

my $future = $driver->get_async($key);

Fetches the current hit count for $key from the CHI cache if the active window has not expired.

Returns a Future resolving to an integer hit count (or 0 if missing or expired).

reset_async($key)

my $future = $driver->reset_async($key);

Removes the tracked record for $key immediately from the CHI cache.

Returns a Future resolving to 1.

CAVEATS AND PERFORMANCE NOTES

CHI provides a synchronous caching interface. While this driver wraps responses inside Future objects to maintain full compatibility with PAGI's async middleware pipeline, blocking CHI backends (such as direct file access or slow network calls) may block the event loop.

For maximum async throughput in high-concurrency environments, consider using native asynchronous drivers like PAGI::FastAPI::RateLimit::Driver::Redis.

SEE ALSO

PAGI::FastAPI::RateLimit::Driver, PAGI::FastAPI::Middleware::RateLimit, CHI

AUTHOR

Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/PAGI-FastAPI-RateLimit-Driver-CHI

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI-RateLimit-Driver-CHI/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PAGI::FastAPI::RateLimit::Driver::CHI

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0).