/ 
PAGI-FastAPI-v1.0.0
/ PAGI::FastAPI::RateLimit::Driver

NAME

PAGI::FastAPI::RateLimit::Driver - Abstract Base Class for Rate Limiting Storage Drivers

VERSION

Version v1.0.0

SYNOPSIS

package PAGI::FastAPI::RateLimit::Driver::Custom;

use v5.38;
use experimental 'class';
use Future;

class PAGI::FastAPI::RateLimit::Driver::Custom :isa(PAGI::FastAPI::RateLimit::Driver) {

    method increment_async ($key, $ttl) {
        # Increment hit count for $key asynchronously...
        return Future->done($new_count, $expires_at);
    }

    method get_async ($key) {
        # Fetch current hit count asynchronously...
        return Future->done($current_count);
    }

    method reset_async ($key) {
        # Clear stored hit count for $key...
        return Future->done(1);
    }
}

DESCRIPTION

PAGI::FastAPI::RateLimit::Driver defines the abstract async interface for all rate-limiting storage backends used by PAGI::FastAPI::Middleware::RateLimit.

Custom storage drivers (e.g., Redis, Memcached, DynamoDB) must inherit from this class and implement its asynchronous methods, ensuring they return Future instances to maintain non-blocking behavior inside the PAGI event loop.

REQUIRED METHODS

Subclasses must override the following methods. Calling any of these directly on the base class will throw an exception.

increment_async($key, $ttl)

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

Increments the request hit counter for the specified $key by 1 and sets or updates its Time-To-Live ($ttl) in seconds.

  • $key - Scalar string uniquely identifying the client bucket (e.g., IP address, API key, user ID).

  • $ttl - Integer window duration in seconds.

Returns a Future resolving to a two-element list ($count, $expires_at):

  • $count - Integer representing the updated hit count for the key.

  • $expires_at - Unix epoch timestamp at which the current window resets. Should remain stable across calls within the same window (i.e. set once on the first hit, not recalculated on every increment).

Note: PAGI::FastAPI::Middleware::RateLimit reads both values via list assignment (my ($count, $reset_at) = await $driver->increment_async(...)) and uses $expires_at to populate the x-ratelimit-reset response header and to compute retry-after on a 429. A driver that resolves with only a single value will leave $expires_at undef, silently disabling the x-ratelimit-reset header and making retry-after fall back to the full window length rather than the time actually remaining in it.

get_async($key)

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

Retrieves the current hit count for the specified $key without altering its expiration.

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

reset_async($key)

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

Clears or expires the tracking record for $key immediately.

Returns a Future resolving to a boolean true value on success.

SEE ALSO

PAGI::FastAPI::RateLimit::Driver::Memory, PAGI::FastAPI::Middleware::RateLimit

AUTHOR

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

REPOSITORY

https://github.com/manwar/PAGI-FastAPI

BUGS

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

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