README.md

Grape::Attack

A middleware for Grape to add endpoint-specific throttling.

Why

You are probably familiar with Rack::Attack which does a great job. Grape::Attack was built with simplicity in mind. It was also built to be used directly in Grape APIs without any special configurations.

It comes with a little DSL that allows you to protect your Grape API endpoints. It also automaticaly sets custom HTTP headers to let your clients know how much requests they have left.

If you need more advanced feature like black and white listing, you should probably use Rack::Attack. But if you simply want to do API throttling for each of your Grape endpoints, go ahead and continue reading.

Installation

Add this line to your application's Gemfile:

gem 'grape-attack'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-attack

Usage

Mount the middleware in your API:

class MyApi < Grape::API
  use Grape::Attack::Throttle
end

Define limits per endpoints using throttle DSL:

class MyApi < Grape::API

  use Grape::Attack::Throttle

  resources :comments do

    throttle max: 10, per: 1.minute
    get do
      Comment.all
    end

  end
end

Use any ActiveSupport Time extension to Numeric object.

By default it will use the request ip address to identity the client making the request. You can pass your own identifier using a Proc:

class MyApi < Grape::API

  use Grape::Attack::Throttle

  helpers do
    def current_user
      @current_user ||= User.authorize!(env)
    end
  end

  resources :comments do

    throttle max: 100, per: 1.day, identifier: Proc.new { current_user.id }
    get do
      Comment.all
    end

  end
end

When rate limit is reached, it will raise Grape::Attack::RateLimitExceededError exception. You can catch the exception using rescue_from:

class MyApi < Grape::API

  use Grape::Attack::Throttle

  rescue_from Grape::Attack::RateLimitExceededError do |e|
    error!({ message: e.message }, 403)
  end

  resources :comments do

    throttle max: 100, per: 1.day
    get do
      Comment.all
    end

  end
end

Which would result in the following http response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"message":"API rate limit exceeded for xxx.xxx.xxx.xxx."}

Finally the following headers will automatically be set:

• X-RateLimit-Limit -- The maximum number of requests that the consumer is permitted to make per specified period.
• X-RateLimit-Remaining -- The number of requests remaining in the current rate limit window.
• X-RateLimit-Reset -- The time at which the current rate limit window resets in UTC epoch seconds.

Adapters

Adapters are used to store the rate counter. Currently there is only a Redis adapter. You can set redis client url through env['REDIS_URL'] varialble.

Defaults to redis://localhost:6379/0.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/grape-attack.

License

The gem is available as open source under the terms of the MIT License.