gitlab-labkit 1.12.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99cf18b21d9da22b488d0dd0031fc9030aeded745239b4e72e8d3f7c1c36555
-  data.tar.gz: 664ba45d3535d3310431eece7890c58ddfa9cd8a9dfa3c235b66fd20b2b5480e
+  metadata.gz: b563d434908c8c7473aeebf5be13bf8f1f6d4f9634cbbdb389581bb5c4b14953
+  data.tar.gz: 0b004077e12eb342c449856c7eadfcae558ea78b024eca86f4686cb7b06ef0b1
 SHA512:
-  metadata.gz: f7959c2eb8f54ee928a7841c2b8de8011c1e2a481c3c6aaf8e94b53a7ca186e8c28ad192a641c4c8ffac5bd8fd39a2c7c6afad324dfae77531b00e3089de3dc0
-  data.tar.gz: 05d07f6b1dffe39907c372ca0cb1c638cbc3898f39faf33f82ef5e042c9ea916a94d297963706e0010bc30dc14df2ebf2a1d89a342866630753af233f52934d1
+  metadata.gz: 03cd36c29407a01003104a8893d4afefdf452875e286b7535590ddae7febabf8fede9193de3946ac25008b11a3210b7a4454fd85638c654270039b94383cfb01
+  data.tar.gz: c9679d0fcb0aa67389801afeabc0fe1e625193f77eab5d41911451df82145a26e020761132ae0a1646b3e3720fbc7f7743d420f7ad1745c5d8f88443151ee777

data/.copier-answers.yml

@@ -3,7 +3,7 @@
 # See the project for instructions on how to update the project
 #
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v1.45.0
+_commit: v1.46.0
 _src_path: https://gitlab.com/gitlab-com/gl-infra/common-template-copier.git
 ee_licensed: false
 golang: false

data/CODEOWNERS

@@ -1,4 +1,4 @@
 # CODEOWNERS is used to lookup assignees for
 # Renovate Bot dependency change Merge Requests.
 # https://docs.renovatebot.com/configuration-options/#assigneesfromcodeowners
-* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @e_forbes @M_Alvarez
+* @reprazent @andrewn @mkaeppler @ayufan @hmerscher @d.barrett @splattael @e_forbes @M_Alvarez @mwoolf

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"
@@ -18,6 +24,7 @@ module Labkit
   autoload :Metrics, "labkit/metrics"
   autoload :Middleware, "labkit/middleware"
   autoload :Fields, "labkit/fields"
+  autoload :RateLimit, "labkit/rate_limit"
 
   # Publishers to publish notifications whenever a HTTP reqeust is made.
   # A broadcasted notification's payload in topic "request.external_http" includes:

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Labkit
+  module RateLimit
+    # 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
+      REDIS_KEY_PREFIX = "labkit:rl"
+      CHAR_VALUE_MAX_LENGTH = 200
+      MISSING_VALUE_SENTINEL = "_unknown_"
+
+      def initialize(name:, rules:, redis:, logger:)
+        @name   = name
+        @rules  = rules
+        @redis  = redis
+        @logger = logger
+      end
+
+      def check(identifier)
+        check_rules(identifier)
+      rescue StandardError => e
+        # Intentionally broad: fail-open applies to any unexpected error (network,
+        # timeout, OOM) not only Redis protocol errors.
+        log_error(e, identifier)
+        Result.new(matched: false, error: true)
+      end
+
+      private
+
+      def check_rules(identifier)
+        @rules.each do |rule|
+          next unless rule_matches?(rule, identifier)
+
+          return evaluate_rule(rule, identifier)
+        end
+
+        Result.new(matched: false)
+      end
+
+      def rule_matches?(rule, identifier)
+        rule.match.all? { |key, value| identifier[key] == value }
+      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))
+
+        count = incr_with_ttl(redis_key, resolved_period)
+        exceeded = count > resolved_limit
+
+        Result.new(matched: true, exceeded: exceeded, action: rule.action, rule: rule)
+      end
+
+      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]
+        return MISSING_VALUE_SENTINEL if value.nil? || value.to_s.empty?
+
+        value.to_s
+      end
+
+      def resolve_value(val)
+        val.respond_to?(:call) ? val.call : val
+      end
+
+      def encode_char_value(value)
+        if value.length > CHAR_VALUE_MAX_LENGTH
+          OpenSSL::Digest::SHA256.hexdigest(value)
+        else
+          value
+        end
+      end
+
+      def incr_with_ttl(redis_key, period)
+        count = @redis.incr(redis_key)
+        # Set expiry only on first write to avoid resetting TTL on each call
+        @redis.expire(redis_key, period) if count == 1
+        count
+      end
+
+      def log_error(error, identifier)
+        @logger.warn(
+          message: "rate_limit_error",
+          name: @name,
+          error: error.class.to_s,
+          identifier: identifier&.to_h
+        )
+      end
+    end
+  end
+end

data/lib/labkit/rate_limit/identifier.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+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)
+        return value unless value.is_a?(String)
+
+        value.split("?", 2).first
+      end
+
+      attr_reader :attributes
+
+      def initialize(attributes = {})
+        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.
+      def [](key)
+        @attributes[key.to_sym]
+      end
+
+      # Serialize to a plain Hash suitable for JSON logging.
+      def to_h
+        @attributes.transform_keys(&:to_s)
+      end
+
+      def ==(other)
+        other.is_a?(Identifier) && other.attributes == @attributes
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Labkit
+  module RateLimit
+    # Rule is a value object describing a single rate limit rule.
+    # 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,
+          action: action.to_sym,
+          characteristics: Array(characteristics).map(&:to_sym).freeze
+        )
+      end
+    end
+  end
+end

data/lib/labkit/rate_limit.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Labkit
+  # 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
+
+      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.12.0
+  version: 1.14.0
 platform: ruby
 authors:
 - Andrew Newdigate
@@ -598,6 +598,13 @@ files:
 - lib/labkit/middleware/sidekiq/user_experience_sli/client.rb
 - 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
 - lib/labkit/rspec/matchers/user_experience_matchers.rb