gitlab-labkit 1.13.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8db8c324d6fe60ad1b16ab51dd87207d4a5d08e1d83ad99a3ae900392bd0739c
-  data.tar.gz: 4487ae2ff2bacac400f753c92012cd7b118525f0bed143794ca4fd12c14cca53
+  metadata.gz: b563d434908c8c7473aeebf5be13bf8f1f6d4f9634cbbdb389581bb5c4b14953
+  data.tar.gz: 0b004077e12eb342c449856c7eadfcae558ea78b024eca86f4686cb7b06ef0b1
 SHA512:
-  metadata.gz: 7292067a1a5d8e231776b65b381ba161a2123c6363df5ebd4269ae65b596871ebddb5bd610e5ab33da0939cdeab4639a51bcb2636046cfd8cb941ac6f6baa9bb
-  data.tar.gz: 771b7fded81f969ee414ef737b74fa9c22d620762f0e56c669e89de9c4ebf6c022fdbf91513fe630a580acfc8408d20a0eb55e3f05e0c97c412ab6ab818a75bf
+  metadata.gz: 03cd36c29407a01003104a8893d4afefdf452875e286b7535590ddae7febabf8fede9193de3946ac25008b11a3210b7a4454fd85638c654270039b94383cfb01
+  data.tar.gz: c9679d0fcb0aa67389801afeabc0fe1e625193f77eab5d41911451df82145a26e020761132ae0a1646b3e3720fbc7f7743d420f7ad1745c5d8f88443151ee777

data/lib/gitlab-labkit.rb

@@ -5,6 +5,12 @@
 # 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"

data/lib/labkit/rate_limit/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Labkit
+  module RateLimit
+    class Configuration
+      attr_accessor :redis, :logger
+    end
+  end
+end

data/lib/labkit/rate_limit/evaluator.rb

@@ -1,123 +1,78 @@
 # 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/
-
-      def initialize(call_site:, identifier:, rules:, redis:, logger: nil)
-        @call_site = call_site
-        @identifier = identifier
-        @rules = rules
-        @redis = redis
-        @logger = logger || build_default_logger
+      MISSING_VALUE_SENTINEL = "_unknown_"
+
+      def initialize(name:, rules:, redis:, logger:)
+        @name   = name
+        @rules  = rules
+        @redis  = redis
+        @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
-
-        @rules.each_with_index do |rule, index|
-          next unless rule_matches?(rule, @identifier)
+      def check_rules(identifier)
+        @rules.each do |rule|
+          next unless rule_matches?(rule, identifier)
 
-          result = evaluate_rule(rule, index)
-          aggregate = :block if result == :block
+          return evaluate_rule(rule, identifier)
         end
 
-        aggregate
-      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
-
-        rule.characteristics.each do |char|
-          char_value = resolve_characteristic(char, @identifier)
-
-          if char_value.nil?
-            log_skipped_characteristic(rule, index, char)
-            next
-          end
+      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))
 
-          redis_key = build_redis_key(@call_site, index, char, char_value)
-
-          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)
-        end
+        count = incr_with_ttl(redis_key, resolved_period)
+        exceeded = count > resolved_limit
 
-        exceeded && rule.action == :block ? :block : :allow
+        Result.new(matched: true, exceeded: exceeded, action: rule.action, rule: rule)
       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
+      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
+        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)
@@ -135,57 +90,14 @@ module Labkit
         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

data/lib/labkit/rate_limit/identifier.rb

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

data/lib/labkit/rate_limit/limiter.rb

@@ -0,0 +1,55 @@
+# 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)
+        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)
+        raise ArgumentError, "name must be a non-empty String" unless name.is_a?(String) && !name.empty?
+        return name if NAME_PATTERN.match?(name)
+
+        raise ArgumentError, "Invalid name: #{name.inspect}. Must match /\\A[a-z0-9_]+\\z/" if Labkit.dev_or_test?
+
+        sanitized = name.gsub(/[^a-z0-9_]/, "_")
+        logger.warn(message: "rate_limit_invalid_name", name: name, sanitized: sanitized)
+        sanitized
+      end
+    end
+  end
+end

data/lib/labkit/rate_limit/result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Labkit
+  module RateLimit
+    # Result is the return value of Limiter#check.
+    # matched?  - true if a rule's match conditions were satisfied
+    # exceeded? - true if the matched rule's counter exceeded its limit
+    # action    - :block or :log (nil when matched? is false)
+    # rule      - the matched Rule object (nil when matched? is false)
+    # error?    - true if Redis was unavailable; result fails open (exceeded? is false)
+    Result = Data.define(:matched, :exceeded, :action, :rule, :error) do
+      def initialize(matched:, exceeded: false, action: nil, rule: nil, error: false)
+        super
+      end
+
+      def matched?
+        matched
+      end
+
+      def exceeded?
+        exceeded
+      end
+
+      def error?
+        error
+      end
+    end
+  end
+end

data/lib/labkit/rate_limit/rule.rb

@@ -3,9 +3,17 @@
 module Labkit
   module RateLimit
     # Rule is a value object describing a single rate limit rule.
-    Rule = Data.define(:match, :limit, :period, :action, :characteristics) do
-      def initialize(limit:, period:, characteristics:, match: {}, action: :block)
+    # name            - stable identifier used in Redis keys and log entries
+    # match           - hash of identifier key/value pairs that must all match for
+    #                   the rule to apply; empty hash matches any identifier
+    # limit           - request threshold; may be a callable (resolved per check)
+    # period          - window in seconds; may be a callable (resolved per check)
+    # action          - :block (enforce) or :log (count and log, but do not block)
+    # characteristics - identifier keys used to build the compound Redis counter key
+    Rule = Data.define(:name, :match, :limit, :period, :action, :characteristics) do
+      def initialize(name:, limit:, period:, characteristics:, match: {}, action: :block)
         super(
+          name: name.to_s.tr(":", "_"),
           match: match.transform_keys(&:to_sym).freeze,
           limit: limit,
           period: period,

data/lib/labkit/rate_limit.rb

@@ -1,34 +1,50 @@
 # 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"
 
-    # 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
+    class << self
+      def configure
+        yield config
+      end
 
-    # Check whether the given call_site + identifier combination is within the
-    # configured rules.
-    #
-    # @param call_site [String] machine-readable name of the call site
-    # @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
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Convenience wrapper - creates a throw-away Limiter.
+      # Prefer Limiter for call sites that can cache the object.
+      #
+      # @param name [String] call site name
+      # @param identifier [Identifier, Hash] caller attributes
+      # @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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-labkit
 version: !ruby/object:Gem::Version
-  version: 1.13.0
+  version: 1.14.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -599,8 +599,11 @@ files:
 - lib/labkit/middleware/sidekiq/user_experience_sli/server.rb
 - lib/labkit/net_http_publisher.rb
 - lib/labkit/rate_limit.rb
+- lib/labkit/rate_limit/configuration.rb
 - lib/labkit/rate_limit/evaluator.rb
 - lib/labkit/rate_limit/identifier.rb
+- lib/labkit/rate_limit/limiter.rb
+- lib/labkit/rate_limit/result.rb
 - lib/labkit/rate_limit/rule.rb
 - lib/labkit/rspec/README.md
 - lib/labkit/rspec/matchers.rb