NAME
RateLimitations - manage per-service rate limitations
SYNOPSIS
use 5.010;
use RateLimitations qw(
rate_limited_services
rate_limits_for_service
within_rate_limits
all_service_consumers
);
# Example using the built-in default "rl_internal_testing" service:
# rl_internal_testing:
# 10s: 2
# 5m: 6
my @rl_services = rate_limited_services();
# ("rl_internal_testing")
my @test_limits = rate_limits_for_service('rl_internal_testing');
# ([10 => 2], [300 => 6])
foreach my $i (1 .. 6) {
my $guy = ($i % 2) ? 'OddGuy' : 'EvenGuy';
my $result = (
within_rate_limits({
service => 'rl_internal_testing',
consumer => $guy,
})) ? 'permitted' : 'denied';
say $result . ' for ' . $guy;
}
# permitted for OddGuy
# permitted for EvenGuy
# permitted for OddGuy
# permitted for EvenGuy
# denied for OddGuy
# denied for EvenGuy
my $consumers = all_service_consumers();
# { rl_internal_testing => ['EvenGuy', 'OddGuy']}
DESCRIPTION
RateLimitations is a module to help enforce per-service rate limits.
The rate limits are checked via a backing Redis store. This persistence
allows for multiple processes to maintain a shared view of resource
usage. Acceptable rates are defined in the
/etc/perl_rate_limitations.yml file.
Several utility functions are provided to help examine the inner state
to help confirm proper operation.
Nothing is exported from this package by default.
FUNCTIONS
within_rate_limits({service => $service, consumer => $consumer_id})
Returns 1 if $consumer_id is permitted further access to $service
under the rate limiting rules for the service; 0 is returned if this
access would exceed those limits.
Will croak unless both elements are supplied and $service is valid.
Note that this call will update the known request rate, even if it is
eventually determined that the request is not within limits. This is
a conservative approach since we cannot know for certain how the
results of this call are used. As such, it is best to use this call
only when legitimately gating service access and to allow a bit of
extra slack in the permitted limits.
verify_rate_limitations_config()
Attempts to load the /etc/perl_rate_limitations.yml file and confirm
that its contents make sense. Parsing the file in much the same way
as importing the module, additional sanity checks are performed on
the supplied rates.
Returns 1 if the file appears to be OK; 0 otherwise.
rate_limited_services()
Returns an array of all known services which have applied rate
limits.
rate_limits_for_service($service)
Returns an array of rate limits applied to requests for a known
$service. Each member of the array is an array reference with two
elements:
[number_of_seconds, number_of_accesses_permitted_in_those_seconds]
all_service_consumers()
Returns a hash reference with all services and their consumers. May
be useful for verifying consumer names are well-formed.
{ service1 => [consumer1, consumer2],
service2 => [consumer1, consumer2],
}
flush_all_service_consumers()
Clears the full list of consumers. Returns the number of items
cleared.
CONFIG FILE FORMAT
The services to be limited are defined in the
/etc/perl_rate_limitations.yml file. This file should be laid out as
follows:
service_name:
time: count
time: count
service_name:
time: count
time: count
service_name is an arbitrary string to uniquely identify the service
time is a string which can be interpreted by Time::Duration::Concise.
This may include using an integer number of seconds.
count is an integer which sets the maximum permitted service_name
accesses per time
AUTHOR
Binary.com <
[email protected]>
COPYRIGHT
Copyright 2015-
LICENSE
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
