Class: Labkit::RateLimit::Limiter

Inherits:
Object
  • Object
show all
Defined in:
lib/labkit/rate_limit/limiter.rb

Overview

Limiter is the primary public API for rate limiting. Instantiate once per call site (e.g. at application boot), then call #check(identifier) on every request. The internal Evaluator is reused across calls, avoiding per-request object allocation.

Examples:

limiter = Labkit::RateLimit::Limiter.new(
  name: "rack_request",
  rules: [Labkit::RateLimit::Rule.new(name: "api_user", limit: 100, period: 60, characteristics: [:user])]
)
result = limiter.check({ user: 42, ip: "1.2.3.4" })
render_429 if result.action == :block

Constant Summary collapse

NAME_PATTERN = 
/\A[a-z0-9_]+\z/

Instance Method Summary collapse

Constructor Details

#initialize(name:, rules:, redis: nil, logger: nil) ⇒ Limiter

Returns a new instance of Limiter.



22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/labkit/rate_limit/limiter.rb', line 22

def initialize(name:, rules:, redis: nil, logger: nil)
  @logger = logger || RateLimit.config.logger || Labkit::Logging::JsonLogger.new($stdout)
  @name = validate_name!(name)

  @evaluator = Evaluator.new(
    name: @name,
    rules: prepare_rules(rules),
    redis: redis || RateLimit.config.redis,
    logger: @logger
  )
end

Instance Method Details

#check(identifier, cost: 1, rule_context: nil) ⇒ Result

Parameters:

  • identifier (Identifier, Hash) —

    caller attributes for this request

  • cost (Numeric) (defaults to: 1) —

    amount to add to the counter. Defaults to 1 (count-mode). Pass a non-1 Numeric for cost-mode counters such as resource-usage limits; passing 0 reads the counter without writing.

  • rule_context (Hash, nil) (defaults to: nil) —

    optional per-request context passed to one-arity callables on +limit+/+period+. Lets rules resolve dynamic configuration (e.g. per-namespace settings) without rebuilding the Rule or doing out-of-band DB queries. Zero-arity callables ignore it. The key contract is owned by the rule's callable, not validated here: if the rule reads ctx and the caller passes ctx, the callable's fallback branch fires silently. Keep the rule definition and the call site colocated.

Returns:



47
48
49
50
 
# File 'lib/labkit/rate_limit/limiter.rb', line 47

def check(identifier, cost: 1, rule_context: nil)
  id = to_identifier(identifier)
  @evaluator.check(id, cost: cost, rule_context: rule_context)
end

#clear(identifier) ⇒ Integer

Discards this limiter's state for one identifier: every rule's counter, and any ban written by a rule carrying ban_for.

For call sites where a later success should wipe earlier failures, such as an authentication ban cleared by a valid login. Counters otherwise only expire with their window; this is the only way to end one early.

Scoped to this limiter and identifier, not to a single rule: a caller clearing after a success knows who succeeded, not which rules matched.

Parameters:

  • identifier (Identifier, Hash) —

    caller attributes

Returns:

  • (Integer) —

    number of Redis keys removed; on a Redis error, those removed before it failed



85
86
87
 
# File 'lib/labkit/rate_limit/limiter.rb', line 85

def clear(identifier)
  @evaluator.clear(to_identifier(identifier))
end

#peek(identifier, rule_context: nil) ⇒ Result

Read the current rate-limit state without incrementing the counter. Mirrors #check except the underlying counter is not mutated and the TTL is not extended. Useful for "have we already throttled this caller?" checks where the caller has another path that does the actual increment (typical pattern: peek to gate a side-effect, then call #check on the path that should count).

When the underlying Redis key does not exist yet, the result reports count=0, exceeded=false, and remaining=resolved_limit; matched? is still true because the rule applied. On Redis error the result fails open identically to #check.

Parameters:

  • identifier (Identifier, Hash) —

    caller attributes for this request

  • rule_context (Hash, nil) (defaults to: nil) —

    see #check

Returns:



67
68
69
70
 
# File 'lib/labkit/rate_limit/limiter.rb', line 67

def peek(identifier, rule_context: nil)
  id = to_identifier(identifier)
  @evaluator.peek(id, rule_context: rule_context)
end