limitation-proxy

CI
Latest Version
Documentation
Crate Downloads
GitHub Downloads
License

Table of Contents

• About
• Installation
  • Cargo Install
  • From Source
• Usage
• Ideas and Future Work
• CI Status
  • Build (master branch)
  • Test (master branch)
  • Check (master branch)
• Code of Conduct
• Issues
• Contributing
• Release History
• Authors
• License

A reverse proxy service with configurable rate limiting

About

The limitation-proxy service is an HTTP reverse proxy which sits in front of another HTTP service and will perform rate limiting on all requests that pass through it. The rate limiting is a variant of a fixed window rate limiting strategy and Redis is used for its persistence.

        +------------------+            +-----------------------+
        |                  |            |                       |
        |                  |            |                       |
    --->+ limitation-proxy +----------->+        proxied        |
        |                  +<-----------+        back end       |
        |                  |            |                       |
        |                  |            |                       |
        +--------+---------+            +-----------------------+
                 |
                 v
        +--------+---------+
        |                  |
        |                  |
        |      Redis       |
        |                  |
        |                  |
        +------------------+

Installation

Cargo Install

If Rust is installed, then installing with Cargo is straight forward:

$ cargo install limitation-proxy

From Source

To install from source, you can clone the Git repository, build with Cargo and copy the binary into a destination directory. This will build the project from the latest commit on the master branch, which may not correspond to the latest stable release:

$ git clone https://github.com/fnichol/limitation.git
$ cd limitation
$ cargo build --bin limitation-proxy --release
$ cp ./target/release/limitation-proxy /dest/path/

Usage

You can use the -h/--help flag to get:

$ limitation-proxy
limitation-proxy 0.1.1
Fletcher Nichol <fnichol@nichol.ca>

A reverse proxy service with configurable rate limiting

Project home page: https://github.com/fnichol/limitation

USAGE:
    limitation-proxy

OPTIONS:
    -b, --bind <BIND>        Bind address for the service [env: BIND_ADDR]
                             [default: 0.0.0.0:8080]
    -H, --header <HEADER>    Header to be used as the key for rate-limiting
                             [default: authorization]
    -l, --limit <LIMIT>      Maximum number of requests per key in the period
                             [default: 5000]
    -P, --period <PERIOD>    Duration of period window in seconds [default:
                             3600]
    -p, --proxy <PROXY>      Backend proxy URL target [env: PROXY_URL]
                             [default: http://127.0.0.1:8000]
    -r, --redis <REDIS>      Redis URL for persistence [env: REDIS_URL]
                             [default: redis://127.0.0.1/]
    -h, --help               Prints help information
    -V, --version            Prints version information

A running Redis instance is required for limitation-proxy, so we'll assume one is running locally and reachable at 127.0.0.1:6379 which happens to be this service's default as well. Starting the service without any arguments runs with the default settings:

$ limitation-proxy

You can also override the defaults with the arguments. For example, this will run the service limiting up to 100 requests in a 60 second window:

$ limitation-proxy --limit 100 --period 60

Ideas and Future Work

These are some ideas and potential future work for this project. If you're reading this, then maybe you're curious or interested in helping out? Great! Be sure to check out the [Contributing][#contributing] section and dig in!

• Allowing configurable rules to match particular HTTP requests, possibly by HTTP verb, path, headers, etc.
• Allow more granular matching inside the header value. Currently, an Authorization header will only key on the full value string which may include both basic authentication and token based authentication.
• Support incoming TLS and/or TLS to the proxied back end.
• Add an API path to check a user's current limit status. Note that there would likely be some small feature work in the limitation crate to support this.
• Allow this service to cover a sub-path on the proxied back end. Currently a request to /a/b will be proxied to the back end's /a/b path. It might be useful if the service could take /a/b and send it to /api/v1/a/b on the back end

CI Status

Build (master branch)

Operating System	Stable Rust	Nightly Rust	MSRV
FreeBSD
Linux
macOS
Windows

Test (master branch)

Operating System	Stable Rust	Nightly Rust	MSRV
FreeBSD
Linux
macOS
Windows

Check (master branch)

	Status
Lint
Format

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to fnichol@nichol.ca.

Issues

If you have any problems with or questions about this project, please contact us through a GitHub issue.

Contributing

You are invited to contribute to new features, fixes, or updates, large or small; we are always thrilled to receive pull requests, and do our best to process them as fast as we can.

Before you start to code, we recommend discussing your plans through a GitHub issue, especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing.

Release History

See the changelog for a full release history.

Authors

Created and maintained by Fletcher Nichol (fnichol@nichol.ca).

License

Licensed under the Mozilla Public License Version 2.0 (LICENSE.txt).

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the MPL-2.0 license, shall be licensed as above, without any additional terms or conditions.