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 <perl@binary.com>

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