Class: Cybertrain::RateLimit
- Inherits:
-
Object
- Object
- Cybertrain::RateLimit
- Defined in:
- cybertrain/rate_limit.rb
Overview
One Controller.rate_limit declaration: its options, and the counter
of store: :memory.
Counts are shared through the cache by default (store: :cache): each
request adds one to a Cache row (Cache.increment, in the
application’s SQLite database), so every process and thread serving
the application counts together, and the counts survive a restart.
The windows are fixed and aligned to the epoch: the row’s key is
"rate-limit:<controller_path>:<name>:<key>:<now / within>", key
being the client’s address or the value of the by: method, and
now Cache.now; the to-th request of a window is the last one let
through, and an exhausted client’s Retry-After is the rest of the
window, within - now % within (plan decision 17). Only the part
after the name can come from a client, and a name holds no :, so a
client cannot pick a key that counts against another limit or
controller.
The rate-limit: prefix of the cache’s keys is the framework’s: an
application’s own Cache keys must not start with it.
Each client opens one row per window, which expires at the window’s
end; nothing deletes it then but the cache’s prune: with
cybertrain/jobs the scheduled "cybertrain cache prune" task
(Cache.prune, every Config#cache_prune_interval seconds), without
it the counting writes themselves (Cache.prune_if_due: once per
interval, at most 1000 expired rows per write). Between two prunes the
table grows by one row per client and window, so a flood of addresses
costs disk until the next prune, never memory.
store: :memory keeps the counts in this object instead, per process
and lost on restart (several processes each count on their own), with
a window per key that the key’s first request opens and that closes
within seconds later. Counting happens under one Mutex, before the
action runs; only the actions the declaration names take it (NOTES
rule 57: a lock on every request stalls under several workers, so keep
only: narrow). Its memory is bounded: at most #max_keys keys
(10 000 by default). The keys are kept in the order their windows
opened (a key whose window reopens is moved to the end), so when a new
key finds the table full the expired windows are at its front; they
go first, then the oldest open ones, a tenth of the table at a time. A
flood of addresses can therefore end a client’s window early (it
starts again from zero), never grow the process.
Constant Summary collapse
- MAX_KEYS =
The most keys one limiter keeps.
10_000- BODY =
The body of the default answer, a 429.
"Too Many Requests"
Instance Attribute Summary collapse
-
#alert_message ⇒ String
readonly
The flash alert set before that redirect (
"": none). -
#by_method ⇒ Symbol?
readonly
The controller method whose value keys the count (
by: :user_key); nil to count by the client’s address. -
#if_method ⇒ Symbol?
readonly
The controller method that must answer true for the limit to apply (
if:); nil when there is none. -
#limit_count ⇒ Integer
readonly
Requests allowed per window (
to:). -
#limit_name ⇒ String
readonly
The declaration’s
name:(""by default), part of the cache key. -
#max_keys ⇒ Integer
The most keys kept before eviction.
-
#period_seconds ⇒ Integer
readonly
The window, in seconds (
within:). -
#redirect_path ⇒ String
readonly
Where an exhausted client is redirected (
"": a 429 instead). -
#unless_method ⇒ Symbol?
readonly
The controller method that, answering true, lifts the limit (
unless:); nil when there is none. -
#with_method ⇒ Symbol?
readonly
The controller method that answers an exhausted client (
with:); nil for the 429 or the redirect.
Class Method Summary collapse
-
.all ⇒ Array<RateLimit>
Every declared limiter, in declaration order (to reach one from a test).
-
.current_time ⇒ Integer
The time the
store: :memorylimiters count with, in epoch seconds: Clock.now, so a test moves a window withtravel_to/travel. -
.reset_all! ⇒ nil
Forgets every count of every limiter: the
store: :memorytables, and, when a limiter counts in the cache, the cache’s rate-limit rows.
Instance Method Summary collapse
-
#by_remote_addr? ⇒ Boolean
True for
by: :remote_addr, false for the defaultby: :client_ip. -
#hit(key, now) ⇒ Integer
Counts one request for
keyatnow(epoch seconds) and answers 0 when it is allowed, or else the seconds until the key’s window closes (at least 1: the Retry-After value). -
#memory_store? ⇒ Boolean
True for
store: :memory(this object counts), false for the defaultstore: :cache. -
#reset! ⇒ nil
Forgets every count.
-
#tracked?(key) ⇒ Boolean
Whether the table holds
key. -
#tracked_keys ⇒ Integer
How many keys the table holds now.
Instance Attribute Details
#alert_message ⇒ String (readonly)
Returns the flash alert set before that redirect ("": none).
87 88 89 |
# File 'cybertrain/rate_limit.rb', line 87 def @alert_message end |
#by_method ⇒ Symbol? (readonly)
Returns the controller method whose value keys the
count (by: :user_key); nil to count by the client’s address.
96 97 98 |
# File 'cybertrain/rate_limit.rb', line 96 def by_method @by_method end |
#if_method ⇒ Symbol? (readonly)
Returns the controller method that must answer true
for the limit to apply (if:); nil when there is none.
106 107 108 |
# File 'cybertrain/rate_limit.rb', line 106 def if_method @if_method end |
#limit_count ⇒ Integer (readonly)
Returns requests allowed per window (to:).
74 75 76 |
# File 'cybertrain/rate_limit.rb', line 74 def limit_count @limit_count end |
#limit_name ⇒ String (readonly)
Returns the declaration’s name: ("" by default), part
of the cache key.
116 117 118 |
# File 'cybertrain/rate_limit.rb', line 116 def limit_name @limit_name end |
#max_keys ⇒ Integer
Returns the most keys kept before eviction.
91 92 93 |
# File 'cybertrain/rate_limit.rb', line 91 def max_keys @max_keys end |
#period_seconds ⇒ Integer (readonly)
Returns the window, in seconds (within:).
78 79 80 |
# File 'cybertrain/rate_limit.rb', line 78 def period_seconds @period_seconds end |
#redirect_path ⇒ String (readonly)
Returns where an exhausted client is redirected ("": a
429 instead).
83 84 85 |
# File 'cybertrain/rate_limit.rb', line 83 def redirect_path @redirect_path end |
#unless_method ⇒ Symbol? (readonly)
Returns the controller method that, answering true,
lifts the limit (unless:); nil when there is none.
111 112 113 |
# File 'cybertrain/rate_limit.rb', line 111 def unless_method @unless_method end |
#with_method ⇒ Symbol? (readonly)
Returns the controller method that answers an
exhausted client (with:); nil for the 429 or the redirect.
101 102 103 |
# File 'cybertrain/rate_limit.rb', line 101 def with_method @with_method end |
Class Method Details
.all ⇒ Array<RateLimit>
Returns every declared limiter, in declaration order (to reach one from a test).
272 273 274 |
# File 'cybertrain/rate_limit.rb', line 272 def self.all ALL end |
.current_time ⇒ Integer
310 311 312 |
# File 'cybertrain/rate_limit.rb', line 310 def self.current_time Clock.now.to_i end |
.reset_all! ⇒ nil
Forgets every count of every limiter: the store: :memory tables,
and, when a limiter counts in the cache, the cache’s rate-limit rows.
cybertrain/test_help calls it before every test, so that a test
suite that signs in in every test never reaches the sign-in limit.
284 285 286 287 288 289 290 291 292 293 294 295 |
# File 'cybertrain/rate_limit.rb', line 284 def self.reset_all! shared = false i = 0 while i < ALL.length limit = ALL[i] limit.reset! shared = true unless limit.memory_store? i += 1 end clear_shared_counts if shared nil end |
Instance Method Details
#by_remote_addr? ⇒ Boolean
Returns true for by: :remote_addr, false for the default
by: :client_ip.
147 148 149 |
# File 'cybertrain/rate_limit.rb', line 147 def by_remote_addr? @by_remote_addr end |
#hit(key, now) ⇒ Integer
Counts one request for key at now (epoch seconds) and answers 0
when it is allowed, or else the seconds until the key’s window closes
(at least 1: the Retry-After value).
174 175 176 177 178 179 180 |
# File 'cybertrain/rate_limit.rb', line 174 def hit(key, now) wait = 0 @lock.synchronize do wait = count_hit(key, now) end wait end |
#memory_store? ⇒ Boolean
Returns true for store: :memory (this object counts),
false for the default store: :cache.
154 155 156 |
# File 'cybertrain/rate_limit.rb', line 154 def memory_store? @memory_store end |
#reset! ⇒ nil
Forgets every count.
202 203 204 205 206 207 208 |
# File 'cybertrain/rate_limit.rb', line 202 def reset! @lock.synchronize do @starts.clear @counts.clear end nil end |
#tracked?(key) ⇒ Boolean
Returns whether the table holds key.
193 194 195 196 197 |
# File 'cybertrain/rate_limit.rb', line 193 def tracked?(key) held = false @lock.synchronize { held = @starts.key?(key) } held end |
#tracked_keys ⇒ Integer
Returns how many keys the table holds now.
184 185 186 187 188 |
# File 'cybertrain/rate_limit.rb', line 184 def tracked_keys held = 0 @lock.synchronize { held = @starts.length } held end |