/ 
PAGI-FastAPI-RateLimit-Driver-Redis-v0.1.0
/ PAGI::FastAPI::RateLimit::Driver::Redis

NAME

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

VERSION

Version v0.1.0

SYNOPSIS

use PAGI::FastAPI;
use PAGI::FastAPI::RateLimit::Driver::Redis;
use Redis;

# Initialize Redis client instance
my $redis = Redis->new(server => '127.0.0.1:6379');

# Instantiate rate limiting driver
my $driver = PAGI::FastAPI::RateLimit::Driver::Redis->new(
    redis      => $redis,
    key_prefix => 'api_rl:', # Optional namespace prefix
);

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

# Register middleware with Redis driver
$app->add_rate_limit(
    requests => 100,
    window   => 60,
    driver   => $driver,
);

DESCRIPTION

PAGI::FastAPI::RateLimit::Driver::Redis is a high-performance, distributed storage driver for PAGI::FastAPI::Middleware::RateLimit.

It enables PAGI::FastAPI web applications to maintain centralized, multi-worker hit counts across server clusters using an external Redis instance. Increments and TTL assignments are executed atomically via Lua scripts to prevent race conditions during heavy concurrent request bursts.

CONSTRUCTOR

new(%options)

Instantiates a new Redis rate-limiting driver.

Accepts the following named parameters:

  • redis (Required)

    An instantiated Redis client object (e.g., Redis, Redis::Fast, or Mojo::Redis).

  • key_prefix (Optional)

    A scalar string prepended to keys inside Redis to avoid key 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);

Atomically increments the request counter for $key and sets the TTL window if the bucket is new.

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

get_async($key)

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

Fetches the current request count for $key without altering its TTL.

Returns a Future resolving to an integer hit count (or 0 if the key does not exist or has expired).

reset_async($key)

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

Deletes the key immediately from Redis.

Returns a Future resolving to a true value on success.

SEE ALSO

PAGI::FastAPI::RateLimit::Driver, PAGI::FastAPI::Middleware::RateLimit, Redis

AUTHOR

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

REPOSITORY

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

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/PAGI-FastAPI-RateLimit-Driver-Redis/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::Redis

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).