Commit 963e542a authored by Sam Wiskow's avatar Sam Wiskow
Browse files

feat(rate_limit): Limiter API redesign per reprazent review (Spec 8) 

Address all 10 unresolved threads from MR !270 review and Bob Van Landuyt's
spec update (2026-04-28). Key changes:

- Add Limiter class (single Evaluator per call-site, no per-request allocation)
- Add Configuration class with configure/config block pattern
- Add Result object (matched?, exceeded?, action, rule, error?)
- Compound multi-characteristic Redis key (one incr per rule, not N)
- First-match-wins evaluation — stops on first matching rule
- Add name: field to Rule (used in Redis key, replaces positional index)
- Sentinel _unknown_ for missing/nil/empty characteristics
- Callable limit/period resolved at check-time
- Remove KNOWN_CHARACTERISTICS — any identifier key is valid
- Normalize endpoint in Identifier#initialize (not in Evaluator)
- Rename call_site → name throughout

Closes #28792

Co-Authored-By: default avatarClaude Sonnet 4.6 <noreply@anthropic.com>
parent 514c4ee5

lib/labkit/rate_limit.rb

+36 −20
Original line number Diff line number Diff line 
# frozen_string_literal: true



module Labkit

  # RateLimit provides a simple rules-based rate limiting API backed by Redis counters.

  # RateLimit provides a rules-based rate limiting API backed by Redis counters.

  # Primary usage: instantiate a Limiter once per call site and reuse it.

  #

  # @example Configuration (e.g. in a Rails initializer)

  #   Labkit::RateLimit.configure do |c|

  #     c.redis  = Redis.current

  #     c.logger = Labkit::Logging::JsonLogger.new($stdout)

  #   end

  #

  # @example Per-call-site setup

  #   RACK_LIMITER = Labkit::RateLimit::Limiter.new(

  #     name: "rack_request",

  #     rules: [...]

  #   )

  #   result = RACK_LIMITER.check(identifier)

  module RateLimit

    autoload :Configuration, "labkit/rate_limit/configuration"

    autoload :Identifier, "labkit/rate_limit/identifier"

    autoload :Result, "labkit/rate_limit/result"

    autoload :Rule, "labkit/rate_limit/rule"

    autoload :Evaluator, "labkit/rate_limit/evaluator"

    autoload :Limiter, "labkit/rate_limit/limiter"



    class << self

      def configure

        yield config

      end



    # Defined independently to avoid forcing eager load of Evaluator at module load time.

    # Must stay in sync with Evaluator::KNOWN_CHARACTERISTICS.

    KNOWN_CHARACTERISTICS = [:user, :ip, :namespace, :plan, :endpoint].freeze

      def config

        @config ||= Configuration.new

      end



    # Check whether the given call_site + identifier combination is within the

    # configured rules.

      # Convenience wrapper — creates a throw-away Limiter.

      # Prefer Limiter for call sites that can cache the object.

      #

    # @param call_site [String] machine-readable name of the call site

      # @param name [String] call site name

      # @param identifier [Identifier, Hash] caller attributes

    # @param rules [Array<Rule>] ordered list of rate limit rules

    # @param redis [Object] Redis client (must respond to #incr and #expire)

    # @param logger [Logger, nil] optional logger override

    # @return [:allow, :block]

    def self.check(call_site:, identifier:, rules:, redis:, logger: nil)

      id = identifier.is_a?(Identifier) ? identifier : Identifier.new(identifier)

      Evaluator.new(

        call_site: call_site,

        identifier: id,

        rules: rules,

        redis: redis,

        logger: logger

      ).evaluate

      # @param rules [Array<Rule>] ordered list of rules (first match wins)

      # @param redis [Object, nil] Redis client; falls back to config.redis

      # @param logger [Logger, nil] logger; falls back to config.logger

      # @return [Result]

      def check(name:, identifier:, rules:, redis: nil, logger: nil)

        Limiter.new(name: name, rules: rules, redis: redis, logger: logger).check(identifier)

      end

    end

  end

end

lib/labkit/rate_limit/configuration.rb

0 → 100644
+9 −0
Original line number Diff line number Diff line 
# frozen_string_literal: true



module Labkit

  module RateLimit

    class Configuration

      attr_accessor :redis, :logger

    end

  end

end

lib/labkit/rate_limit/evaluator.rb

+56 −112
Original line number Diff line number Diff line
@@ -5,119 +5,78 @@ require "labkit/logging/json_logger" 


module Labkit

  module RateLimit

    # Evaluator contains the core rule-matching + Redis counter logic.

    # Evaluator holds the static parts of a rate limit check (name, rules, Redis,

    # logger) and exposes a per-request #check(identifier) method.

    # @api private

    class Evaluator

      KNOWN_CHARACTERISTICS = [:user, :ip, :namespace, :plan, :endpoint].freeze

      KNOWN_ACTIONS = [:block, :log].freeze

      REDIS_KEY_PREFIX = "labkit:rl"

      CHAR_VALUE_MAX_LENGTH = 200

      UNKNOWN_SENTINEL = "unknown_characteristic"

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

      MISSING_VALUE_SENTINEL = "_unknown_"



      def initialize(call_site:, identifier:, rules:, redis:, logger: nil)

        @call_site = call_site

        @identifier = identifier

      def initialize(name:, rules:, redis:, logger:)

        @name = name

        @rules = rules

        @redis = redis

        @logger = logger || build_default_logger

        @logger = logger

      end



      def evaluate

        validate_call_site!

        evaluate_rules

      rescue ArgumentError

        raise

      def check(identifier)

        check_rules(identifier)

      rescue StandardError => e

        # Intentionally broad: fail-open applies to any unexpected error (network,

        # timeout, OOM, etc.), not only Redis protocol errors.

        log_evaluate_error(e)

        :allow

        # timeout, OOM) not only Redis protocol errors.

        log_error(e, identifier)

        Result.new(matched: false, error: true)

      end



      private



      def evaluate_rules

        aggregate = :allow

      def check_rules(identifier)

        @rules.each do |rule|

          next unless rule_matches?(rule, identifier)



        @rules.each_with_index do |rule, index|

          next unless rule_matches?(rule, @identifier)



          result = evaluate_rule(rule, index)

          aggregate = :block if result == :block

        end



        aggregate

          return evaluate_rule(rule, identifier)

        end



      def validate_call_site!

        return if CALL_SITE_PATTERN.match?(@call_site)



        raise ArgumentError, "Invalid call_site: #{@call_site.inspect}. Must match /\\A[a-z0-9_]+\\z/" if dev_or_test?



        sanitized = @call_site.gsub(/[^a-z0-9_]/, "_")

        @logger.warn(

          message: "rate_limit_invalid_call_site",

          call_site: @call_site,

          sanitized: sanitized

        )

        @call_site = sanitized

        log_no_match(identifier)

        Result.new(matched: false)

      end



      def rule_matches?(rule, identifier)

        rule.match.all? do |key, value|

          identifier[key] == value

        rule.match.all? { |key, value| identifier[key] == value }

      end

      end



      def evaluate_rule(rule, index)

        exceeded = false



        rule.characteristics.each do |char|

          char_value = resolve_characteristic(char, @identifier)

      def evaluate_rule(rule, identifier)

        redis_key = build_redis_key(rule, identifier)

        resolved_limit = resolve_value(rule.limit)

        resolved_period = resolve_value(rule.period)



          if char_value.nil?

            log_skipped_characteristic(rule, index, char)

            next

          end

        count = incr_with_ttl(redis_key, resolved_period)

        exceeded = count > resolved_limit



          redis_key = build_redis_key(@call_site, index, char, char_value)

        log_match(rule, identifier, count, redis_key, resolved_limit, resolved_period, exceeded)



          count = incr_with_ttl(redis_key, rule.period)

          rule_exceeded = count > rule.limit



          exceeded = true if rule_exceeded



          log_rule(rule, index, count, redis_key, rule_exceeded)

        Result.new(matched: true, exceeded: exceeded, action: rule.action, rule: rule)

      end



        exceeded && rule.action == :block ? :block : :allow

      def build_redis_key(rule, identifier)

        key = "#{REDIS_KEY_PREFIX}:#{@name}:#{rule.name}"

        rule.characteristics.each do |char|

          value = resolve_char_value(char, identifier)

          key += ":#{char}:#{encode_char_value(value)}"

        end



      def resolve_characteristic(char, identifier)

        unless KNOWN_CHARACTERISTICS.include?(char)

          raise ArgumentError, "Unknown characteristic: #{char.inspect}. Known: #{KNOWN_CHARACTERISTICS.inspect}" if dev_or_test?



          @logger.warn(

            message: "rate_limit_unknown_characteristic",

            characteristic: char

          )

          return UNKNOWN_SENTINEL

        key

      end



      def resolve_char_value(char, identifier)

        value = identifier[char]



        # Normalize endpoint: strip query string

        value = Identifier.normalize_endpoint(value) if char == :endpoint



        # Treat nil and empty-string the same: anonymous traffic must not collide on a shared bucket.

        return nil if value.nil? || value.to_s.empty?

        return MISSING_VALUE_SENTINEL if value.nil? || value.to_s.empty?



        value.to_s

      end



      def build_redis_key(call_site, rule_index, char, char_value)

        safe_value = encode_char_value(char_value.to_s)

        "#{REDIS_KEY_PREFIX}:#{call_site}:#{rule_index}:#{char}:#{safe_value}"

      def resolve_value(v)

        v.respond_to?(:call) ? v.call : v

      end



      def encode_char_value(value)
@@ -135,57 +94,42 @@ module Labkit 
        count

      end



      def log_rule(rule, index, count, redis_key, exceeded)

      def log_match(rule, identifier, count, redis_key, limit, period, exceeded)

        @logger.info(

          message: "rate_limit_check",

          call_site: @call_site,

          rule_index: index,

          action: rule.action.to_s,

          limit: rule.limit,

          period: rule.period,

          count: count,

          name: @name,

          matched: true,

          rule_name: rule.name,

          characteristics: rule.characteristics,

          counter_key: redis_key,

          current_count: count,

          limit: limit,

          period: period,

          action: rule.action.to_s,

          exceeded: exceeded,

          identifier: @identifier.to_h,

          redis_key: redis_key

          identifier: identifier.to_h,

          remaining: [limit - count, 0].max

        )

      end



      def log_skipped_characteristic(rule, index, char)

      def log_no_match(identifier)

        @logger.info(

          message: "rate_limit_check",

          call_site: @call_site,

          rule_index: index,

          action: rule.action.to_s,

          limit: rule.limit,

          period: rule.period,

          characteristic: char,

          matched: true,

          skipped: true,

          identifier: @identifier.to_h

          name: @name,

          matched: false,

          identifier: identifier.to_h

        )

      end



      def log_evaluate_error(error)

      def log_error(error, identifier)

        @logger.warn(

          message: "rate_limit_redis_error",

          call_site: @call_site,

          message: "rate_limit_error",

          name: @name,

          error: error.class.to_s,

          result: "allow"

          identifier: identifier&.to_h

        )

      end



      def dev_or_test?

        # Memoized: ENV access is not free under concurrency.

        return @dev_or_test unless @dev_or_test.nil?



        env = ENV.fetch("LABKIT_ENV", nil)

        @dev_or_test = env == "test" || env == "development"

      end



      def build_default_logger

        Labkit::Logging::JsonLogger.new($stdout)

      end

    end

  end

end

lib/labkit/rate_limit/identifier.rb

+4 −1
Original line number Diff line number Diff line
@@ -4,6 +4,7 @@ module Labkit 
  module RateLimit

    # Identifier is a value object wrapping a hash of key-value pairs that

    # describe the caller (e.g. user, ip, endpoint).

    # Endpoint values are normalised at construction time (query string stripped).

    class Identifier

      # Normalize an endpoint value: strip query string.

      def self.normalize_endpoint(value)
@@ -15,7 +16,9 @@ module Labkit 
      attr_reader :attributes



      def initialize(attributes = {})

        @attributes = attributes.transform_keys(&:to_sym).freeze

        normalised = attributes.transform_keys(&:to_sym)

        normalised[:endpoint] = self.class.normalize_endpoint(normalised[:endpoint]) if normalised.key?(:endpoint)

        @attributes = normalised.freeze

      end



      # Return the value for a characteristic key.

lib/labkit/rate_limit/limiter.rb

0 → 100644
+63 −0
Original line number Diff line number Diff line 
# frozen_string_literal: true



require "labkit/logging/json_logger"



module Labkit

  module RateLimit

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

    #

    # @example

    #   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.exceeded? && result.action == :block

    class Limiter

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



      def initialize(name:, rules:, redis: nil, logger: nil)

        raise ArgumentError, "name must be a non-empty String" unless name.is_a?(String) && !name.empty?



        resolved_logger = logger || RateLimit.config.logger || Labkit::Logging::JsonLogger.new($stdout)

        validated_name = validate_name!(name, resolved_logger)



        @evaluator = Evaluator.new(

          name: validated_name,

          rules: rules,

          redis: redis || RateLimit.config.redis,

          logger: resolved_logger

        )

      end



      # @param identifier [Identifier, Hash] caller attributes for this request

      # @return [Result]

      def check(identifier)

        id = identifier.is_a?(Identifier) ? identifier : Identifier.new(identifier)

        @evaluator.check(id)

      end



      private



      def validate_name!(name, logger)

        return name if NAME_PATTERN.match?(name)



        if dev_or_test?

          raise ArgumentError, "Invalid name: #{name.inspect}. Must match /\\A[a-z0-9_]+\\z/"

        end



        sanitized = name.gsub(/[^a-z0-9_]/, "_")

        logger.warn(message: "rate_limit_invalid_name", name: name, sanitized: sanitized)

        sanitized

      end



      def dev_or_test?

        env = ENV.fetch("LABKIT_ENV", nil)

        env == "test" || env == "development"

      end

    end

  end

end