Merge branch 'rate-limit/stage-1a-limiter-redesign' into 'master'

# infrastructural concerns, partcularly related to

# observability.

module Labkit

  class << self

    def dev_or_test?

      %w[development test].include?(ENV.fetch("RAILS_ENV", nil))

    end

  end

  autoload :System, "labkit/system"

  autoload :Context, "labkit/context"

# 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

# frozen_string_literal: true

module Labkit

  module RateLimit

    class Configuration

      attr_accessor :redis, :logger

    end

  end

end

# frozen_string_literal: true

require "openssl"

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)

    # 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

        Result.new(matched: false)

      end

      def rule_matches?(rule, identifier)

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

          identifier[key] == value

        end

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

      end

      def evaluate_rule(rule, index)

        exceeded = false

      def evaluate_rule(rule, identifier)

        redis_key = build_redis_key(rule, identifier)

        resolved_limit = Integer(resolve_value(rule.limit))

        resolved_period = Integer(resolve_value(rule.period))

        rule.characteristics.each do |char|

          char_value = resolve_characteristic(char, @identifier)

          if char_value.nil?

            log_skipped_characteristic(rule, index, char)

            next

          end

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

        count = incr_with_ttl(redis_key, resolved_period)

        exceeded = count > resolved_limit

          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(val)

        val.respond_to?(:call) ? val.call : val

      end

      def encode_char_value(value)

        count

      end

      def log_rule(rule, index, count, redis_key, 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,

          matched: true,

          exceeded: exceeded,

          identifier: @identifier.to_h,

          redis_key: redis_key

        )

      end

      def log_skipped_characteristic(rule, index, char)

        @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

        )

      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

  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)

      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.