peiji

A bucket-wise quota service.

Usage

You should use the included Dockerfile (and images generated by it) to run this application.

The following environment variables must be set:

1. REDIS_URI should point to a Redis instance, for example: redis://redis-instance. At least version 7.0 is required.
2. CONFIG_FILE_PATH should be the path to an accessible TOML config file, for example: /app/config.toml
3. LISTEN_IP should be set to the IP address of the interface to listen for connections on, for example 0.0.0.0 to listen on all interfaces.
4. LISTEN_PORT should be set to an available TCP port to listen for connections on, for example 8080

The application will expose an HTTP service at <LISTEN_IP>:<LISTEN_PORT>.

Configuration

The configuration file should describe the quota limits for each bucket.

The following example config file will allow:

• the bkt::test-client::global bucket to be charged 15 times per hour.
• the bkt::test-client::service-a::read bucket to be charged 50 times per day.
• the bkt::other-client::global bucket to be charged 1250 times per month.

[[limits]]
bucket = "bkt::test-client::global"
type = "hourly"
freq = 15

[[limits]]
bucket = "bkt::test-client::service-a::read"
type = "daily"
freq = 50

[[limits]]
bucket = "bkt::other-client::global"
type = "monthly"
freq = 1250

The available types are secondly, minutely, hourly, daily, weekly, and monthly. Note that a monthly quota period is always exactly 30 days.

API

The service exposes the following route:

POST /api/v1/buckets/:bucket_id/charges

where :bucket_id is replaced with the name of a bucket.

An application/json payload is expected with a charge, for example:

{
    "amount": 3
}

A bucket may only be charged at most 1000 units at a time.

The application will respond with one of the following string JSON string payloads:

• ok means the charges were applied and there is still available quota in each bucket.
• slow_down means the charges were applied, and there is still available quota in each bucket, but at least one bucket is over 90% full for the current period.
• stop means the bucket is already full for the current period. The bucket will be blocked for a few seconds to throttle the owner.
• block means a request for a bucket is being made after the owner was already warned to stop. The bucket is blocked for (at least) one minute.