railslove-rack-throttle 0.0.0

Sign up to get free protection for your applications and to get access to all the features.
data/.gitignore ADDED
@@ -0,0 +1,5 @@
1
+ .DS_Store
2
+ .tmp
3
+ .yardoc
4
+ pkg
5
+ tmp
data/.yardopts ADDED
@@ -0,0 +1,11 @@
1
+ --title "Rack::Throttle - HTTP Request Rate Limiter for Rack Applications"
2
+ --output-dir doc/yard
3
+ --protected
4
+ --no-private
5
+ --hide-void-return
6
+ --markup markdown
7
+ --readme README.md
8
+ -
9
+ AUTHORS
10
+ UNLICENSE
11
+ VERSION
data/AUTHORS ADDED
@@ -0,0 +1,2 @@
1
+ * Arto Bendiken <arto.bendiken@gmail.com>
2
+ * Brendon Murphy <disposable.20.xternal@spamourmet.com>
data/README ADDED
@@ -0,0 +1,240 @@
1
+ HTTP Request Rate Limiter for Rack Applications
2
+ ===============================================
3
+
4
+ This is [Rack][] middleware that provides logic for rate-limiting incoming
5
+ HTTP requests to Rack applications. You can use `Rack::Throttle` with any
6
+ Ruby web framework based on Rack, including with Ruby on Rails 3.0 and with
7
+ Sinatra.
8
+
9
+ * <http://github.com/railslove/rack-throttle>
10
+
11
+ The original version can be found:
12
+ * <http://github.com/datagraph/rack-throttle>
13
+
14
+ Difference
15
+ ----------
16
+
17
+ There are two main differences:
18
+
19
+ * Throttling per minute => use Rack::Throttle::PerMinute, :max => 60
20
+ * On reject callback => use Rack::Throttle::PerMinute, :max => 60, :on_reject => Proc.new { puts "Go Away!" }
21
+
22
+ Features
23
+ --------
24
+
25
+ * Throttles a Rack application by enforcing a minimum time interval between
26
+ subsequent HTTP requests from a particular client, as well as by defining
27
+ a maximum number of allowed HTTP requests per a given time period (hourly
28
+ or daily).
29
+ * Compatible with any Rack application and any Rack-based framework.
30
+ * Stores rate-limiting counters in any key/value store implementation that
31
+ responds to `#[]`/`#[]=` (like Ruby's hashes) or to `#get`/`#set` (like
32
+ memcached or Redis).
33
+ * Compatible with the [gdbm][] binding included in Ruby's standard library.
34
+ * Compatible with the [memcached][], [memcache-client][], [memcache][] and
35
+ [redis][] gems.
36
+ * Compatible with [Heroku][]'s [memcached add-on][Heroku memcache]
37
+ (currently available as a free beta service).
38
+
39
+ Examples
40
+ --------
41
+
42
+ ### Adding throttling to a Rails 3.x application
43
+
44
+ # config/application.rb
45
+ require 'rack/throttle'
46
+
47
+ class Application < Rails::Application
48
+ config.middleware.use Rack::Throttle::Interval
49
+ end
50
+
51
+ ### Adding throttling to a Sinatra application
52
+
53
+ #!/usr/bin/env ruby -rubygems
54
+ require 'sinatra'
55
+ require 'rack/throttle'
56
+
57
+ use Rack::Throttle::Interval
58
+
59
+ get('/hello') { "Hello, world!\n" }
60
+
61
+ ### Adding throttling to a Rackup application
62
+
63
+ #!/usr/bin/env rackup
64
+ require 'rack/throttle'
65
+
66
+ use Rack::Throttle::Interval
67
+
68
+ run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }
69
+
70
+ ### Enforcing a minimum 3-second interval between requests
71
+
72
+ use Rack::Throttle::Interval, :min => 3.0
73
+
74
+ ### Allowing a maximum of 100 requests per hour
75
+
76
+ use Rack::Throttle::Hourly, :max => 100
77
+
78
+ ### Allowing a maximum of 1,000 requests per day
79
+
80
+ use Rack::Throttle::Daily, :max => 1000
81
+
82
+ ### Allowing a maximum of 60 requests per minute
83
+
84
+ use Rack::Throttle::PerMinute, :max => 60
85
+
86
+ ### Combining various throttling constraints into one overall policy
87
+
88
+ use Rack::Throttle::Daily, :max => 1000 # requests
89
+ use Rack::Throttle::Hourly, :max => 100 # requests
90
+ use Rack::Throttle::PerMinute, :max => 60 # requests
91
+ use Rack::Throttle::Interval, :min => 3.0 # seconds
92
+
93
+ ### Storing the rate-limiting counters in a GDBM database
94
+
95
+ require 'gdbm'
96
+
97
+ use Rack::Throttle::Interval, :cache => GDBM.new('tmp/throttle.db')
98
+
99
+ ### Storing the rate-limiting counters on a Memcached server
100
+
101
+ require 'memcached'
102
+
103
+ use Rack::Throttle::Interval, :cache => Memcached.new, :key_prefix => :throttle
104
+
105
+ ### Storing the rate-limiting counters on a Redis server
106
+
107
+ require 'redis'
108
+
109
+ use Rack::Throttle::Interval, :cache => Redis.new, :key_prefix => :throttle
110
+
111
+ ### Using a callback when a visitor is rejected
112
+
113
+ # Can be anything that responds to #call
114
+ callback = Proc.new { puts "help!" }
115
+ use Rack::Throttle::PerMinute, :max => 10, :on_reject => callback
116
+
117
+ Throttling Strategies
118
+ ---------------------
119
+
120
+ `Rack::Throttle` supports three built-in throttling strategies:
121
+
122
+ * `Rack::Throttle::Interval`: Throttles the application by enforcing a
123
+ minimum interval (by default, 1 second) between subsequent HTTP requests.
124
+ * `Rack::Throttle::Hourly`: Throttles the application by defining a
125
+ maximum number of allowed HTTP requests per hour (by default, 3,600
126
+ requests per 60 minutes, which works out to an average of 1 request per
127
+ second).
128
+ * `Rack::Throttle::Daily`: Throttles the application by defining a
129
+ maximum number of allowed HTTP requests per day (by default, 86,400
130
+ requests per 24 hours, which works out to an average of 1 request per
131
+ second).
132
+ * `Rack::Throttle::PerMinute`: Throttles the application by defining a
133
+ maximum number of allowed HTTP requests per minute (by default, 60
134
+ requests per minute, which works out to an average of 1 request per
135
+ second).
136
+
137
+ You can fully customize the implementation details of any of these strategies
138
+ by simply subclassing one of the aforementioned default implementations.
139
+ And, of course, should your application-specific requirements be
140
+ significantly more complex than what we've provided for, you can also define
141
+ entirely new kinds of throttling strategies by subclassing the
142
+ `Rack::Throttle::Limiter` base class directly.
143
+
144
+ HTTP Client Identification
145
+ --------------------------
146
+
147
+ The rate-limiting counters stored and maintained by `Rack::Throttle` are
148
+ keyed to unique HTTP clients.
149
+
150
+ By default, HTTP clients are uniquely identified by their IP address as
151
+ returned by `Rack::Request#ip`. If you wish to instead use a more granular,
152
+ application-specific identifier such as a session key or a user account
153
+ name, you need only subclass a throttling strategy implementation and
154
+ override the `#client_identifier` method.
155
+
156
+ HTTP Response Codes and Headers
157
+ -------------------------------
158
+
159
+ ### 403 Forbidden (Rate Limit Exceeded)
160
+
161
+ When a client exceeds their rate limit, `Rack::Throttle` by default returns
162
+ a "403 Forbidden" response with an associated "Rate Limit Exceeded" message
163
+ in the response body.
164
+
165
+ An HTTP 403 response means that the server understood the request, but is
166
+ refusing to respond to it and an accompanying message will explain why.
167
+ This indicates an error on the client's part in exceeding the rate limits
168
+ outlined in the acceptable use policy for the site, service, or API.
169
+
170
+ ### 503 Service Unavailable (Rate Limit Exceeded)
171
+
172
+ However, there exists a widespread practice of instead returning a "503
173
+ Service Unavailable" response when a client exceeds the set rate limits.
174
+ This is technically dubious because it indicates an error on the server's
175
+ part, which is certainly not the case with rate limiting - it was the client
176
+ that committed the oops, not the server.
177
+
178
+ An HTTP 503 response would be correct in situations where the server was
179
+ genuinely overloaded and couldn't handle more requests, but for rate
180
+ limiting an HTTP 403 response is more appropriate. Nonetheless, if you think
181
+ otherwise, `Rack::Throttle` does allow you to override the returned HTTP
182
+ status code by passing in a `:code => 503` option when constructing a
183
+ `Rack::Throttle::Limiter` instance.
184
+
185
+ Documentation
186
+ -------------
187
+
188
+ <http://datagraph.rubyforge.org/rack-throttle/>
189
+
190
+ * {Rack::Throttle}
191
+ * {Rack::Throttle::Interval}
192
+ * {Rack::Throttle::Daily}
193
+ * {Rack::Throttle::Hourly}
194
+ * {Rack::Throttle::PerMinute}
195
+
196
+ Dependencies
197
+ ------------
198
+
199
+ * [Rack](http://rubygems.org/gems/rack) (>= 1.0.0)
200
+
201
+ Installation
202
+ ------------
203
+
204
+ The recommended installation method is via [RubyGems](http://rubygems.org/).
205
+ To install the latest official release of the gem, do:
206
+
207
+ % [sudo] gem install rack-throttle
208
+
209
+ Download
210
+ --------
211
+
212
+ To get a local working copy of the development repository, do:
213
+
214
+ % git clone git://github.com/datagraph/rack-throttle.git
215
+
216
+ Alternatively, you can download the latest development version as a tarball
217
+ as follows:
218
+
219
+ % wget http://github.com/datagraph/rack-throttle/tarball/master
220
+
221
+ Authors
222
+ -------
223
+
224
+ * [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
225
+ * [Brendon Murphy](mailto:disposable.20.xternal@spamourmet.com>) - <http://www.techfreak.net/>
226
+
227
+ License
228
+ -------
229
+
230
+ `Rack::Throttle` is free and unencumbered public domain software. For more
231
+ information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
232
+
233
+ [Rack]: http://rack.rubyforge.org/
234
+ [gdbm]: http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html
235
+ [memcached]: http://rubygems.org/gems/memcached
236
+ [memcache-client]: http://rubygems.org/gems/memcache-client
237
+ [memcache]: http://rubygems.org/gems/memcache
238
+ [redis]: http://rubygems.org/gems/redis
239
+ [Heroku]: http://heroku.com/
240
+ [Heroku memcache]: http://docs.heroku.com/memcache
data/README.md ADDED
@@ -0,0 +1,240 @@
1
+ HTTP Request Rate Limiter for Rack Applications
2
+ ===============================================
3
+
4
+ This is [Rack][] middleware that provides logic for rate-limiting incoming
5
+ HTTP requests to Rack applications. You can use `Rack::Throttle` with any
6
+ Ruby web framework based on Rack, including with Ruby on Rails 3.0 and with
7
+ Sinatra.
8
+
9
+ * <http://github.com/railslove/rack-throttle>
10
+
11
+ The original version can be found:
12
+ * <http://github.com/datagraph/rack-throttle>
13
+
14
+ Difference
15
+ ----------
16
+
17
+ There are two main differences:
18
+
19
+ * Throttling per minute => use Rack::Throttle::PerMinute, :max => 60
20
+ * On reject callback => use Rack::Throttle::PerMinute, :max => 60, :on_reject => Proc.new { puts "Go Away!" }
21
+
22
+ Features
23
+ --------
24
+
25
+ * Throttles a Rack application by enforcing a minimum time interval between
26
+ subsequent HTTP requests from a particular client, as well as by defining
27
+ a maximum number of allowed HTTP requests per a given time period (hourly
28
+ or daily).
29
+ * Compatible with any Rack application and any Rack-based framework.
30
+ * Stores rate-limiting counters in any key/value store implementation that
31
+ responds to `#[]`/`#[]=` (like Ruby's hashes) or to `#get`/`#set` (like
32
+ memcached or Redis).
33
+ * Compatible with the [gdbm][] binding included in Ruby's standard library.
34
+ * Compatible with the [memcached][], [memcache-client][], [memcache][] and
35
+ [redis][] gems.
36
+ * Compatible with [Heroku][]'s [memcached add-on][Heroku memcache]
37
+ (currently available as a free beta service).
38
+
39
+ Examples
40
+ --------
41
+
42
+ ### Adding throttling to a Rails 3.x application
43
+
44
+ # config/application.rb
45
+ require 'rack/throttle'
46
+
47
+ class Application < Rails::Application
48
+ config.middleware.use Rack::Throttle::Interval
49
+ end
50
+
51
+ ### Adding throttling to a Sinatra application
52
+
53
+ #!/usr/bin/env ruby -rubygems
54
+ require 'sinatra'
55
+ require 'rack/throttle'
56
+
57
+ use Rack::Throttle::Interval
58
+
59
+ get('/hello') { "Hello, world!\n" }
60
+
61
+ ### Adding throttling to a Rackup application
62
+
63
+ #!/usr/bin/env rackup
64
+ require 'rack/throttle'
65
+
66
+ use Rack::Throttle::Interval
67
+
68
+ run lambda { |env| [200, {'Content-Type' => 'text/plain'}, "Hello, world!\n"] }
69
+
70
+ ### Enforcing a minimum 3-second interval between requests
71
+
72
+ use Rack::Throttle::Interval, :min => 3.0
73
+
74
+ ### Allowing a maximum of 100 requests per hour
75
+
76
+ use Rack::Throttle::Hourly, :max => 100
77
+
78
+ ### Allowing a maximum of 1,000 requests per day
79
+
80
+ use Rack::Throttle::Daily, :max => 1000
81
+
82
+ ### Allowing a maximum of 60 requests per minute
83
+
84
+ use Rack::Throttle::PerMinute, :max => 60
85
+
86
+ ### Combining various throttling constraints into one overall policy
87
+
88
+ use Rack::Throttle::Daily, :max => 1000 # requests
89
+ use Rack::Throttle::Hourly, :max => 100 # requests
90
+ use Rack::Throttle::PerMinute, :max => 60 # requests
91
+ use Rack::Throttle::Interval, :min => 3.0 # seconds
92
+
93
+ ### Storing the rate-limiting counters in a GDBM database
94
+
95
+ require 'gdbm'
96
+
97
+ use Rack::Throttle::Interval, :cache => GDBM.new('tmp/throttle.db')
98
+
99
+ ### Storing the rate-limiting counters on a Memcached server
100
+
101
+ require 'memcached'
102
+
103
+ use Rack::Throttle::Interval, :cache => Memcached.new, :key_prefix => :throttle
104
+
105
+ ### Storing the rate-limiting counters on a Redis server
106
+
107
+ require 'redis'
108
+
109
+ use Rack::Throttle::Interval, :cache => Redis.new, :key_prefix => :throttle
110
+
111
+ ### Using a callback when a visitor is rejected
112
+
113
+ # Can be anything that responds to #call
114
+ callback = Proc.new { puts "help!" }
115
+ use Rack::Throttle::PerMinute, :max => 10, :on_reject => callback
116
+
117
+ Throttling Strategies
118
+ ---------------------
119
+
120
+ `Rack::Throttle` supports three built-in throttling strategies:
121
+
122
+ * `Rack::Throttle::Interval`: Throttles the application by enforcing a
123
+ minimum interval (by default, 1 second) between subsequent HTTP requests.
124
+ * `Rack::Throttle::Hourly`: Throttles the application by defining a
125
+ maximum number of allowed HTTP requests per hour (by default, 3,600
126
+ requests per 60 minutes, which works out to an average of 1 request per
127
+ second).
128
+ * `Rack::Throttle::Daily`: Throttles the application by defining a
129
+ maximum number of allowed HTTP requests per day (by default, 86,400
130
+ requests per 24 hours, which works out to an average of 1 request per
131
+ second).
132
+ * `Rack::Throttle::PerMinute`: Throttles the application by defining a
133
+ maximum number of allowed HTTP requests per minute (by default, 60
134
+ requests per minute, which works out to an average of 1 request per
135
+ second).
136
+
137
+ You can fully customize the implementation details of any of these strategies
138
+ by simply subclassing one of the aforementioned default implementations.
139
+ And, of course, should your application-specific requirements be
140
+ significantly more complex than what we've provided for, you can also define
141
+ entirely new kinds of throttling strategies by subclassing the
142
+ `Rack::Throttle::Limiter` base class directly.
143
+
144
+ HTTP Client Identification
145
+ --------------------------
146
+
147
+ The rate-limiting counters stored and maintained by `Rack::Throttle` are
148
+ keyed to unique HTTP clients.
149
+
150
+ By default, HTTP clients are uniquely identified by their IP address as
151
+ returned by `Rack::Request#ip`. If you wish to instead use a more granular,
152
+ application-specific identifier such as a session key or a user account
153
+ name, you need only subclass a throttling strategy implementation and
154
+ override the `#client_identifier` method.
155
+
156
+ HTTP Response Codes and Headers
157
+ -------------------------------
158
+
159
+ ### 403 Forbidden (Rate Limit Exceeded)
160
+
161
+ When a client exceeds their rate limit, `Rack::Throttle` by default returns
162
+ a "403 Forbidden" response with an associated "Rate Limit Exceeded" message
163
+ in the response body.
164
+
165
+ An HTTP 403 response means that the server understood the request, but is
166
+ refusing to respond to it and an accompanying message will explain why.
167
+ This indicates an error on the client's part in exceeding the rate limits
168
+ outlined in the acceptable use policy for the site, service, or API.
169
+
170
+ ### 503 Service Unavailable (Rate Limit Exceeded)
171
+
172
+ However, there exists a widespread practice of instead returning a "503
173
+ Service Unavailable" response when a client exceeds the set rate limits.
174
+ This is technically dubious because it indicates an error on the server's
175
+ part, which is certainly not the case with rate limiting - it was the client
176
+ that committed the oops, not the server.
177
+
178
+ An HTTP 503 response would be correct in situations where the server was
179
+ genuinely overloaded and couldn't handle more requests, but for rate
180
+ limiting an HTTP 403 response is more appropriate. Nonetheless, if you think
181
+ otherwise, `Rack::Throttle` does allow you to override the returned HTTP
182
+ status code by passing in a `:code => 503` option when constructing a
183
+ `Rack::Throttle::Limiter` instance.
184
+
185
+ Documentation
186
+ -------------
187
+
188
+ <http://datagraph.rubyforge.org/rack-throttle/>
189
+
190
+ * {Rack::Throttle}
191
+ * {Rack::Throttle::Interval}
192
+ * {Rack::Throttle::Daily}
193
+ * {Rack::Throttle::Hourly}
194
+ * {Rack::Throttle::PerMinute}
195
+
196
+ Dependencies
197
+ ------------
198
+
199
+ * [Rack](http://rubygems.org/gems/rack) (>= 1.0.0)
200
+
201
+ Installation
202
+ ------------
203
+
204
+ The recommended installation method is via [RubyGems](http://rubygems.org/).
205
+ To install the latest official release of the gem, do:
206
+
207
+ % [sudo] gem install rack-throttle
208
+
209
+ Download
210
+ --------
211
+
212
+ To get a local working copy of the development repository, do:
213
+
214
+ % git clone git://github.com/datagraph/rack-throttle.git
215
+
216
+ Alternatively, you can download the latest development version as a tarball
217
+ as follows:
218
+
219
+ % wget http://github.com/datagraph/rack-throttle/tarball/master
220
+
221
+ Authors
222
+ -------
223
+
224
+ * [Arto Bendiken](mailto:arto.bendiken@gmail.com) - <http://ar.to/>
225
+ * [Brendon Murphy](mailto:disposable.20.xternal@spamourmet.com>) - <http://www.techfreak.net/>
226
+
227
+ License
228
+ -------
229
+
230
+ `Rack::Throttle` is free and unencumbered public domain software. For more
231
+ information, see <http://unlicense.org/> or the accompanying UNLICENSE file.
232
+
233
+ [Rack]: http://rack.rubyforge.org/
234
+ [gdbm]: http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html
235
+ [memcached]: http://rubygems.org/gems/memcached
236
+ [memcache-client]: http://rubygems.org/gems/memcache-client
237
+ [memcache]: http://rubygems.org/gems/memcache
238
+ [redis]: http://rubygems.org/gems/redis
239
+ [Heroku]: http://heroku.com/
240
+ [Heroku memcache]: http://docs.heroku.com/memcache