rapidity 0.0.6.312500 → 0.0.7.362805

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83491abd2c9916dd51edd18efc2ab36a923bed3e2590c4829185357e493d7aae
-  data.tar.gz: 5c08ce388c147fffea5e2b0e9ea1908c029744fb45034b050c80297acf0d565f
+  metadata.gz: ec1c0e662f963921cf709fa7769897774ab2814b9c1c6b5017dc38379e25614a
+  data.tar.gz: 978b48d1149569859268054e0cbd8eeff7577c9b2fc5cceec2040a1361b974e1
 SHA512:
-  metadata.gz: 435fa92c078fe8811ea8d7e9c9675d684581ef2cb6e52157bb30e4e09d321d0db7e250ccc11268d5a6bcb18878f0bd56dfd0580df5dcdd098e1aba4371ad58eb
-  data.tar.gz: fb804c7094efe6b431b856fac07635f4c4c14315d4d1b9bc5f18ada5d1c2df0310f213c5627c3b1dee7c0f5a97c013b1c610542559ccb3f9edb8f466191c9cbe
+  metadata.gz: ca19db773ea028961e6dd593faf29d27a0039b809e22b4be258cbbd1a237b5b14d306ef57928d53a5ffd7578e113e4701d933416bd1ed49ad86a29e65f9edd7b
+  data.tar.gz: 5d43836d52cda325188b2628e92037e54e44d58972c36ea2eefc024e64aa011191c16971326c01ad86b2eb7db84af6b8a8dc68e8a17374f5b901227202fec437

data/Gemfile.lock

@@ -1,19 +1,17 @@
 PATH
   remote: .
   specs:
-    rapidity (0.0.6.312500)
+    rapidity (0.0.7.362805)
       activesupport
       connection_pool
+      ostruct
       redis
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 1.6, < 2)
-      minitest (>= 5.1)
-      tzinfo (~> 2.0)
+    activesupport (3.1.12)
+      multi_json (~> 1.0)
     addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     ansi (1.5.0)
@@ -27,7 +25,6 @@ GEM
     byebug (11.1.3)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.1.10)
     connection_pool (2.2.5)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
@@ -44,13 +41,12 @@ GEM
       path_expander (~> 1.0)
       ruby_parser (~> 3.1, > 3.1.0)
       sexp_processor (~> 4.8)
-    i18n (1.10.0)
-      concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
     kwalify (0.7.2)
     launchy (2.5.0)
       addressable (~> 2.7)
-    minitest (5.16.1)
+    multi_json (1.19.1)
+    ostruct (0.6.3)
     parser (3.1.2.0)
       ast (~> 2.4.1)
     path_expander (1.1.0)
@@ -64,6 +60,7 @@ GEM
       kwalify (~> 0.7.0)
       parser (~> 3.1.0)
       rainbow (>= 2.0, < 4.0)
+    rexml (3.4.4)
     rspec (3.11.0)
       rspec-core (~> 3.11.0)
       rspec-expectations (~> 3.11.0)
@@ -95,12 +92,15 @@ GEM
       tty-which (~> 0.4.0)
       virtus (~> 1.0)
     sexp_processor (4.16.1)
-    shoulda-matchers (5.1.0)
-      activesupport (>= 5.2.0)
+    shoulda-matchers (2.8.0)
+      activesupport (>= 3.0.0)
     simplecov (0.21.2)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
+    simplecov-cobertura (3.1.0)
+      rexml
+      simplecov (~> 0.19)
     simplecov-console (0.9.1)
       ansi
       simplecov
@@ -112,8 +112,6 @@ GEM
     thread_safe (0.3.6)
     timeouter (0.1.3.38794)
     tty-which (0.4.2)
-    tzinfo (2.0.4)
-      concurrent-ruby (~> 1.0)
     unicode-display_width (2.2.0)
     virtus (1.0.5)
       axiom-types (~> 0.1)
@@ -128,15 +126,16 @@ PLATFORMS
 DEPENDENCIES
   awesome_print
   bump
-  bundler (~> 2.0)
+  bundler
   byebug
   rapidity!
-  rspec (~> 3.0)
+  rspec
   rspec-collection_matchers
   rspec_junit_formatter
   rubycritic
   shoulda-matchers
   simplecov
+  simplecov-cobertura
   simplecov-console
   timeouter
 

data/README.md

@@ -79,6 +79,56 @@ loop do
 end
 ```
 
+## Share module expansion
+If your message producer and message sender are independent services, and you want the sender to be agnostic of the business rules for rate limiting, use the classes in the Share module. The producer is responsible for initializing and configuring the rate limits (e.g., token bucket) with the correct business parameters in Redis. The sender then only consumes these pre-defined limits without knowing the underlying rules.
+
+```mermaid
+flowchart LR
+    G(producer)
+    B[Redis]
+    A(["message broker"])
+    T(sender)
+    E["external system with request limiting"]
+    G-- init limit -->B
+    B-- acquire limit -->T
+    G-- message [limit1, limit2] -->A
+    A--->T
+    T-- limited request -->E
+```
+
+### Base scenario
+
+`Producer` ONLY creates limits, and send messages to the `Sender`. `Sender` actually use limits to achieve overall Rate Limiting. 
+
+### Optinal **Feedback-Driven Flow Control** scenario
+
+Beyond basic rate limiting, the Share module offers **optional queue management capabilities** that enable sophisticated **Feedback-Driven Flow Control**. This feature allows systems to handle temporary load spikes more gracefully while maintaining communication between producers and consumers.
+
+In this scenario, `Producer` additionally checks the optional `max_queue` attribute in the limit to understand whether it makes sense to send requests to `Sender` or whether it is already loaded with previous requests. 
+`Producer` MUST obtain semaphore `max_queue` on limites, then `Sender` MUST release semaphore `max_queue` after actual send request.
+
+### Workflow with Code Examples
+1. Initializing Limits and Optional Queues (Producer Side)
+The message producer initializes rate limits with specific business rules. Queues can be added for handling traffic spikes.
+
+```ruby
+@pool = ConnectionPool.new(size: 5, timeout: 5) { Redis.new }
+@producer = Rapidity::Share::Producer.new(@pool)
+api_day_limit = Limit.new("day_limit", max_tokens: 1000, period: 86400, namespace: 'api_v2')
+api_hour_limit = Limit.new("hour_limit", max_tokens: 100, period: 3600, max_queue: 100, namespace: 'api_v2')
+@producer.init(api_day_limit)
+@producer.init(api_hour_limit)
+```
+2. Each message is tagged with the limits it should consume when processed.
+3. Messages flow through your message broker to the sender service.
+4. The message sender attempts to acquire tokens before sending. If unavailable, it waits according to the token bucket algorithm.
+```ruby
+@pool = ConnectionPool.new(size: 5, timeout: 5) { Redis.new }
+@sender = Rapidity::Share::Producer.new(@pool)
+@sender.acquire(message['api_v2:day_limit', 'api_v2:hour_limit'], tokens: 1)
+```
+5. For queue-backed limits, senders can release tokens back to the queue to signal max_queue availability.
+
 ## Installation
 
 It's a gem:

data/lib/rapidity/share/base.rb

@@ -0,0 +1,168 @@
+require 'ostruct'
+
+module Rapidity
+  module Share
+    class Base
+
+      LUA_SCRIPTS = []
+      BASE_SCRIPTS = [:list, :info, :reset, :delete]
+      DEFAULT_KEY_TTL = 6000
+
+      def initialize(pool, ttl: DEFAULT_KEY_TTL.to_i, logger: nil)
+        @pool = pool
+        @ttl = ttl
+        @logger = logger || Logger.new(STDOUT)
+        @logger.level = Logger::DEBUG
+        # load_redis_scripts
+      end
+
+      # Returns a list of limits matching the pattern
+      #
+      # @param match_pattern [String] pattern for key matching
+      # @param max_count [Integer] maximum number of records to return
+      # @return [Array<Limit>] array of Limit objects or empty array
+      def list(match_pattern, max_count: 1000)
+        response = wrap_executed_script do |r|
+          r.evalsha(@lua_list, argv: [match_pattern, max_count])
+        end
+
+        response = response.each_slice(2).to_h
+        if response["count"].to_i > 0
+          response["limits"].map do |data|
+            build_limit(data)
+          end
+        else
+          []
+        end
+      end
+
+      # Resets limit values
+      #
+      # @param limit_or_str [Limit, String] limit object or its name
+      # @param ttl [Integer] key TTL after reset
+      # @return [OpenStruct] operation result with success and limit fields
+      def reset(limit_or_str, ttl: @ttl)
+        response = wrap_executed_script do |r|
+          r.evalsha(@lua_reset, keys: [get_name(limit_or_str)], argv: [ttl])
+        end
+
+        handle_response(response, with_limit: true)
+      end
+
+      # Deletes a limit from Redis
+      #
+      # @param limit_or_str [Limit, String] limit object or its name
+      # @return [OpenStruct] operation result with success field
+      def delete(limit_or_str)
+        response = wrap_executed_script do |r|
+          r.evalsha(@lua_delete, keys: [get_name(limit_or_str)])
+        end
+
+        handle_response(response)
+      end
+
+      # Retrieves information about a limit
+      #
+      # @param limit_or_str [Limit, String] limit object or its name
+      # @param ttl [Integer] key TTL
+      # @return [OpenStruct] operation result with success and limit fields
+      def info(limit_or_str, ttl: @ttl)
+        response = wrap_executed_script do |r|
+          r.evalsha(@lua_info, keys: [get_name(limit_or_str)], argv: [ttl])
+        end
+
+        handle_response(response, with_limit: true)
+      end
+
+      # Processes Redis response and converts it to OpenStruct
+      #
+      # @param response [Array] raw Redis response
+      # @param with_limit [Boolean] whether to include limit object in result
+      # @return [OpenStruct] structured response
+      def handle_response(response, with_limit: false)
+        response = response.each_slice(2).to_h
+        success = response["result"] == "true"
+        result_data = { success: success, **response }
+        result_data[:limit] = build_limit(response["info"]) if success && with_limit
+        OpenStruct.new(result_data)
+      end
+
+      def get_name(limit_or_str)
+        limit_or_str.is_a?(Limit) ? limit_or_str.name : limit_or_str
+      end
+
+      def build_limit(redis_data)
+        name = redis_data[0]
+        params = redis_data[1].each_slice(2).to_h
+        Limit.from_hash(name, **params.symbolize_keys)
+      end
+
+      # Wrapper for Redis script execution with retry logic
+      #
+      # @param max_retries [Integer] maximum number of retry attempts
+      # @param delay [Float] delay between retries in seconds
+      # @param block [Proc] block containing Redis operations
+      # @return [Array] Redis response or error response
+      def wrap_executed_script(max_retries: 5, delay: 0.1, &block)
+        retries_count = 0
+        begin
+          @pool.with do |conn|
+            conn.with do |r|
+              yield r
+            end
+          end
+        rescue Redis::CannotConnectError, Redis::TimeoutError, Errno::ECONNREFUSED => e
+          retries_count += 1
+          if retries_count < max_retries
+            @logger.warn("Redis connection error: #{e.message}.")
+            sleep(delay)
+            retry
+          else
+            @logger.error("Redis is not available: #{e.message}")
+            raise e
+          end
+        rescue ::Redis::CommandError => e
+          if e.message.include?('NOSCRIPT')
+            retries_count += 1
+            if retries_count < max_retries
+              @logger.warn("Get not script error from redis: #{e.message}. Reload lua scripts")
+              # существует вероятность что сервер мог быть перезагружен
+              # и нужно заново загрузить скрипты
+              load_redis_scripts
+              retry
+            end
+          end
+          raise e
+        rescue TypeError => e
+          if e.message.include?('Unsupported command argument type: NilClass')
+            retries_count += 1
+            if retries_count < max_retries
+              @logger.info("First time load lua scripts")
+              # При первом запуске instance_variable с lua скриптами не инициализированы, при этом
+              # evalsha райзит эту ошибку. Загружаем скрипты в redis
+              load_redis_scripts
+              retry
+            end
+          end
+          raise e
+        end
+      end
+
+      private
+
+      # Loads Lua scripts into Redis
+      #
+      # @return [void]
+      def load_redis_scripts
+        @pool.with do |conn|
+          (BASE_SCRIPTS + self.class::LUA_SCRIPTS).each do |script|
+            instance_variable_set("@lua_#{script}".to_sym,
+              conn.with {|r| r.script(:load, File.read(File.join(__dir__, 'lua_scripts', "#{script.to_s}.lua"))) }
+            )
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/rapidity/share/limit.rb

@@ -0,0 +1,53 @@
+module Rapidity
+  module Share
+    class Limit
+
+      attr_reader :name, :max_tokens, :tokens, :interval, :max_queue, :semaphore, :last_used, :rate
+
+      def initialize(name, max_tokens, interval,
+                     namespace: nil, tokens: nil,
+                     last_used: nil, rate: nil,
+                     semaphore: nil, max_queue: nil, 
+                     validate: true, **kwargs)
+        @name = namespace.to_s.empty? ? name : [namespace, name].join(':')
+        @namespace = namespace.to_s
+        @max_tokens = max_tokens.to_i
+        @tokens = tokens.to_i
+        @interval = interval.to_i
+        @semaphore = semaphore.to_i
+        @max_queue = max_queue.to_i
+        @last_used = last_used.to_i
+        @rate = rate.to_i == 0 ? @max_tokens.to_f/@interval.to_f : rate
+
+        @kwargs = kwargs
+        validate_parameters! if validate
+      end
+
+      def self.from_hash(name, **kwargs)
+        max_tokens = kwargs.delete(:max_tokens)
+        interval = kwargs.delete(:interval)
+        self.new(name, max_tokens, interval, **kwargs)
+      end
+
+      def persisted?
+        @last_used > 0
+      end
+
+      def valid?
+        @max_tokens > 0 && @interval > 0
+      end
+
+      def base_params
+        [max_tokens, interval, max_queue]
+      end
+
+      private
+
+      def validate_parameters!
+        raise ArgumentError, "max_tokens must be greater than 0" unless @max_tokens > 0
+        raise ArgumentError, "interval must be greater than 0" unless @interval > 0
+      end
+
+    end
+  end
+end

data/lib/rapidity/share/lua_scripts/acquire.lua

@@ -0,0 +1,175 @@
+-------------------------------------------------------------------------------
+-- СПЕЦИФИКАЦИЯ ФАЙЛА
+-------------------------------------------------------------------------------
+-- Этот скрипт отвечает за реализацию алгоритма Token Bucket (маркерная корзина) для Rate Limiter'а,
+-- выполняемую прямо внутри Redis с помощью Lua.
+-- Выполнение внутри Redis гарантирует атомарность операций (никто не сможет изменить
+-- данные между чтением и записью) и высокую производительность.
+--
+-- Описание функционала файла acquire.lua
+-- 1. Атомарный захват по нескольким лимитам ("Всё или ничего"): 
+--   Скрипт принимает список ключей (лимитов) и запрошенное количество токенов.
+--   Он проверяет, есть ли нужное количество токенов во всех переданных лимитах одновременно.
+-- 2. Ленивое пополнение (Lazy Refill): Токены не пополняются каким-то фоновым процессом.
+--   Вместо этого при каждом обращении (в функции Limit:update) вычисляется разница во времени
+--   с момента последнего обращения (current_time - self.last_used) и добавляется количество токенов, пропорциональное скорости rate.
+-- 3. Проверка условий (Validation): 
+--    - Если запрашивается <= 0 токенов или передан пустой список ключей — сразу возвращается ошибка.
+--    - Если хотя бы одного ключа не существует в Redis, возвращается key_not_found.
+--    - Если хотя бы в одном лимите не хватает токенов, скрипт возвращает ошибку not_limits и ничего не списывает из других лимитов (откат транзакции).
+-- 4. Фиксация состояния: Только если проверены и удовлетворены все лимиты, происходит
+--   фактическое списание токенов (tokens - requested), сохранение новых значений
+--   в Redis (HMSET) и обновление времени жизни ключей (EXPIRE). Возвращается успешный результат.
+-------------------------------------------------------------------------------
+
+-- Указываем Redis реплицировать сами эффекты от скрипта (HMSET), а не сам скрипт.
+-- Это необходимо для использования команды TIME внутри скрипта в версиях Redis 3.2 - 5.0.
+redis.replicate_commands()
+
+-- Входящие аргументы
+-- KEYS: список ключей (имен лимитов)
+-- ARGV[1]: запрашиваемое количество токенов (requested) !ЧИСЛО!
+-- ARGV[2]: время жизни ключей в секундах (key_ttl)
+local limit_keys = KEYS
+local requested = tonumber(ARGV[1]) or 0
+local key_ttl = tonumber(ARGV[2]) or 0
+
+-- Получаем текущее время сервера (в секундах)
+local current_time = redis.call("TIME")[1]
+
+-------------------------------------------------------------------------------
+-- ООП обертка для работы с лимитом (Token Bucket)
+-------------------------------------------------------------------------------
+local Limit = {}
+Limit.__index = Limit
+
+-- Инициализация объекта Limit из Redis
+function Limit:new(limit_key)
+  local obj = { key = limit_key, exists = false }
+  setmetatable(obj, self)
+
+  -- Оптимизация: вместо EXISTS + HMGET делаем только HMGET. 
+  -- Если ключа нет, values[1] будет nil.
+  local values = redis.call("HMGET", limit_key,
+    "max_tokens",
+    "tokens",
+    "interval",
+    "last_used",
+    "rate"
+  )
+    
+  if not values[1] then
+    return obj -- Ключ не существует
+  end
+
+  obj.max_tokens = tonumber(values[1]) or 0
+  obj.tokens     = tonumber(values[2]) or 0
+  obj.interval   = tonumber(values[3]) or 0
+  obj.last_used  = tonumber(values[4]) or 0
+  obj.rate       = tonumber(values[5]) or 0
+
+  obj.exists = (obj.max_tokens > 0) and (obj.interval > 0)
+  
+  return obj
+end
+
+-- "Ленивое" пополнение корзины токенов на основе прошедшего времени
+function Limit:update(current_time)
+  if not self.exists then return self end  
+  
+  local time_passed = current_time - self.last_used
+  if time_passed <= 0 then return self end
+  
+  local tokens_to_add = math.floor(time_passed * self.rate)
+  self.tokens = math.min(self.tokens + tokens_to_add, self.max_tokens)
+  
+  if tokens_to_add > 0 then
+    local time_consumed = tokens_to_add / self.rate
+    self.last_used = math.min(self.last_used + time_consumed, current_time)
+  end
+
+  return self
+end
+
+-- Сохранение обновленного стейта лимита в Redis
+function Limit:save()
+  if not self.exists then return end
+  
+  redis.call("HMSET", self.key,
+      "tokens", self.tokens, 
+      "last_used", self.last_used
+  )
+end
+
+-- Проверка, достаточно ли токенов
+-- requested - это количество (ЧИСЛО) запрошенных токенов
+function Limit:can_acquire(requested)
+  return self.exists and self.tokens >= requested
+end
+
+-- Списание токенов из памяти объекта (без сохранения в БД)
+-- requested - это количество (ЧИСЛО) запрошенных токенов
+function Limit:acquire(requested)
+  if not self:can_acquire(requested) then return false end
+  self.tokens = self.tokens - requested
+  return true
+end
+
+-------------------------------------------------------------------------------
+-- Основная логика обработки всех лимитов
+-------------------------------------------------------------------------------
+-- requested - это количество (ЧИСЛО) запрошенных токенов
+local function process_all_limits(limit_keys, requested, current_time)
+  -- Базовые валидации
+  if requested <= 0 then
+    return { "result", "false", "retryable", "false", "error", "limits not requested" }
+  end
+
+  if #limit_keys == 0 then
+    return { "result", "false", "retryable", "false", "error", "no keys passed" }
+  end
+  
+  local limits = {}
+  
+  -- Фаза 1: Проверка всех лимитов (Read & Validate)
+  for i = 1, #limit_keys do
+    local key = limit_keys[i]
+    local limit = Limit:new(key)
+    
+    if not limit.exists then
+      return { "result", "false", "retryable", "false", "error", "key_not_found", "key", key }
+    end
+
+    -- Пересчитываем количество токенов на текущий момент
+    limit:update(current_time)
+
+    -- Если хотя бы в одном лимите не хватает токенов - прерываем операцию для всех
+    if not limit:can_acquire(requested) then
+      return {
+        "result", "false",
+        "retryable", "true",
+        "error", "not_limits",
+        "tokens_available", limit.tokens,
+        "key", key
+      }
+    end
+    
+    table.insert(limits, limit)
+  end
+  
+  -- Фаза 2: Применение изменений (Write)
+  -- Выполняется только если всем лимитам хватило токенов
+  for i = 1, #limits do
+    local limit = limits[i]
+    limit:acquire(requested)
+    limit:save()
+    
+    -- Продлеваем жизнь ключу, чтобы он не удалился, если к нему активно обращаются. 
+    -- "GT" обновляет TTL только если новый TTL больше текущего.
+    redis.call("EXPIRE", limit.key, key_ttl, "GT")
+  end
+  
+  return { "result", "true", "keys", limit_keys }
+end
+
+return process_all_limits(limit_keys, requested, current_time)