Class: Cybertrain::RateLimit

Inherits:
Object
  • Object
show all
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

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#alert_message ⇒ String (readonly)

Returns the flash alert set before that redirect ("": none).

Returns:

  • (String) —

    the flash alert set before that redirect ("": none)



87
88
89
# File 'cybertrain/rate_limit.rb', line 87

def alert_message
  @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.

Returns:

  • (Symbol, nil) —

    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.

Returns:

  • (Symbol, nil) —

    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:).

Returns:

  • (Integer) —

    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.

Returns:

  • (String) —

    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.

Returns:

  • (Integer) —

    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:).

Returns:

  • (Integer) —

    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).

Returns:

  • (String) —

    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.

Returns:

  • (Symbol, nil) —

    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.

Returns:

  • (Symbol, nil) —

    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).

Returns:

  • (Array<RateLimit>) —

    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

The time the store: :memory limiters count with, in epoch seconds: Clock.now, so a test moves a window with travel_to / travel. The cache store counts with Cache.now, which reads the same clock.

Returns:



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.

Returns:

  • (nil)

Raises:

  • (Cybertrain::DB::Error) —

    when a limiter counts in the cache and the database is not reachable



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.

Returns:

  • (Boolean) —

    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).

Parameters:

Returns:



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.

Returns:

  • (Boolean) —

    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.

Returns:

  • (nil)


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.

Parameters:

  • key (String)

Returns:

  • (Boolean) —

    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.

Returns:

  • (Integer) —

    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