NAME

RateLimitations::Pluggable - pluggabe manager of per-service rate limitations

STATUS

SYNOPSIS

    my $storage = {};

    my $rl = RateLimitations::Pluggable->new({
        limits => {
            sample_service => {
                60   => 2,  # per minute limits
                3600 => 5,  # per hour limits
            }
        },
        # define an subroutine where hits are stored: redis, db, file, in-memory, cookies
        getter => sub {
            my ($service, $consumer) = @_;
            return $storage->{$service}->{$consumer};
        },
        # optional, notify back when hits are updated
        setter => sub {
            my ($service, $consumer, $hits) = @_;
            $storage->{$service}->{$consumer} = $hits;
        },
    });

    $rl->within_rate_limits('sample_service', 'some_client_id');  # true!
    $rl->within_rate_limits('sample_service', 'some_client_id');  # true!
    $rl->within_rate_limits('sample_service', 'some_client_id'),  # false!

DESCRIPTION

The module access to build-in time function every time you invoke within_rate_limits method, and checks whether limits are hits or not.

Each time the method within_rate_limits is invoked it appends to the array of hit current time. It check that array will not grow endlessly, and holds in per $service (or per $service/$consumer) upto max_time integers.

The array can be stored anywhere (disk, redis, DB, in-memory), hence the module name is.

ATTRIBUTES

limits

Defines per-service limits. Below

    {
        service_1 => {
            60   => 20,    # up to 20 service_1 invocations per 1 minute
            3600 => 50,    # OR up to 50 service_1 invocations per 1 hour
        },

        service_2 => {
            60   => 25,
            3600 => 60,
        }

    }

Mandatory.

getter->($service, $consumer)

Mandatory coderef which returns an array of hits for the service and some consumer.

setter->($service, $consumer, $hits)

Optional callback for storing per service/consumer array of hits.

METHODS

within_rate_limits

 within_rate_limits($service, $consumer)

Appends service/consumer hits array with additional hit.

Returns true if the service limits aren't exhausted.

The $service string must be defined in the limits attribute; the $consumer string is arbitrary object defined by application logic. Cannot be undef

SOURCE CODE

GitHub

AUTHOR

binary.com, <perl at binary.com>

BUGS

Please report any bugs or feature requests to https://github.com/binary-com/perl-RateLimitations-Pluggable/issues.

cpanm RateLimitations::Pluggable

perl -MCPAN -e shell
install RateLimitations::Pluggable