hanikamu-rate-limit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af12b9492738472c4e8bd8431a20b053bde92ec6af556dcd6db9af75c9529e70
-  data.tar.gz: '0187f0d7f9d9edde19f5b095368b19feb90c73a51d25301e356161930392ccaf'
+  metadata.gz: 9eb792d3f4dc535c9a07eee7d06e701265ac45494f2b809afb8701404c64f347
+  data.tar.gz: 505b42072d9a2ece067dd670c97abf03a4dc131fae7d3a73d105f2df8352007c
 SHA512:
-  metadata.gz: b77fb01c48f98d938bdbd4954672be5a3f2fbbed522d4c662349d4b3e6c98327893d7849bc8b8c4936cf33e13af7e5487805f4da6b7451ff4274471d0e42363b
-  data.tar.gz: 2bbe7515db8c173aab88c2ee198d0b9a4fb1015091d74706bb0045a31c37166cb1073a29806937db4057e279183c51fe5fd0e7e804a258d4463e29d2fca0ba04
+  metadata.gz: 8dce476cdc58a439d23b3015581b17869fe964c5a49344a63c38cb34f817c29140adc6035c461776654e2a0c10dd95625a490afaf1e755d6a1f0e61e8ce607fa
+  data.tar.gz: c929411ce3f465454813d5a496fa9fdc3bdf4339ab0ac789b431b53e95515484531bc092507f8242b643a410c723215b3af8ee7b7c6fd442aa87e39ca5af9b3c

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.2.0 - 2026-02-11
+
+### Breaking Changes
+
+- Removed `limit_with`. Use `limit_method` with the `registry:` option instead.
+  - Before: `limit_with :execute, registry: :external_api`
+  - After: `limit_method :execute, registry: :external_api`
+- `limit_method` now raises `ArgumentError` when called without `registry:` or `rate:`.
+- `limit_method` raises `ArgumentError` when `registry:` is combined with any other option (`rate:`, `interval:`, `check_interval:`, or `max_wait_time:`).
+- Removed `key_prefix` from `limit_method`. Registry-based limits derive their key automatically.
+- Removed `key_prefix` from `register_limit`. Registry keys are now always derived internally from the registry name.
+
+### Added
+
+- `register_temporary_limit(name, remaining:, reset:)` — dynamically override a registered limit with a fixed-window counter and TTL, based on API response headers.
+- Override-exhausted requests raise `RateLimitError` immediately when the remaining TTL exceeds `max_wait_time`, instead of polling.
+- Input validation for `register_temporary_limit` — returns `false` for nil, negative, zero, or non-numeric values.
+
 ## 0.1.0 - 2026-02-04
 
 - Initial release of Hanikamu::RateLimit.

data/README.md

@@ -32,7 +32,7 @@ Requires Ruby 4.0 or later.
 
 ```ruby
 # Gemfile
-gem "hanikamu-rate-limit", "~> 0.1.0"
+gem "hanikamu-rate-limit", "~> 0.2.0"
 ```
 
 ```bash
@@ -84,7 +84,8 @@ Registered limit options:
 
 - `rate` and `interval` (required).
 - `check_interval`, `max_wait_time` (optional).
-- `key_prefix` (optional) to force a shared Redis key; defaults to a registry-based prefix.
+
+`key_prefix` is no longer configurable for registered limits; registry keys are derived from the registry name.
 
 ## Usage
 
@@ -94,13 +95,21 @@ Optional per-method overrides:
 limit_method :execute, rate: 5, interval: 1.0, check_interval: 0.1, max_wait_time: 3.0
 ```
 
+Optional block called each time the limiter sleeps:
+
+```ruby
+limit_method :execute, rate: 5, interval: 1.0 do |sleep_time|
+  Rails.logger.info("Rate limited, sleeping #{sleep_time}s")
+end
+```
+
 Use a registered limit shared across classes:
 
 ```ruby
 class ExternalApiClient
   extend Hanikamu::RateLimit::Mixin
 
-  limit_with :execute, registry: :external_api
+  limit_method :execute, registry: :external_api
 
   def execute
     # work
@@ -108,11 +117,13 @@ class ExternalApiClient
 end
 ```
 
+You must provide either `registry:` or `rate:` — combining them raises `ArgumentError`.
+When `registry:` is used, it must be the only limit-related option (no `rate:`, `interval:`, `check_interval:`, or `max_wait_time:` overrides).
+
 Registry precedence (highest to lowest):
 
-1. Per-method overrides passed to `limit_with`.
-2. Registered limit options.
-3. Global defaults from `Hanikamu::RateLimit.configure`.
+1. Registered limit options.
+2. Global defaults from `Hanikamu::RateLimit.configure`.
 
 Reset method is generated automatically:
 
@@ -120,6 +131,88 @@ Reset method is generated automatically:
 MyService.reset_execute_limit!
 ```
 
+### Dynamic overrides
+
+Dynamic overrides only apply to **registry-based limits** (methods using `limit_method` with `registry:`). Methods limited with inline `rate:` / `interval:` options are not affected.
+
+When an external API returns rate-limit headers (e.g. `X-RateLimit-Remaining`, `X-RateLimit-Reset`), you can temporarily override a registered limit to match the real window:
+
+```ruby
+Hanikamu::RateLimit.register_temporary_limit(:external_api, remaining: 175, reset: 60)
+```
+
+This stores a Redis counter with `remaining` requests allowed and a TTL of `reset` seconds. While the override is active, the fixed-window counter is used instead of the sliding window. When the TTL expires, the original registered limit resumes automatically.
+
+Behavior when the override is exhausted (`remaining` reaches 0):
+
+- If the remaining TTL exceeds `max_wait_time`, a `RateLimitError` is raised **immediately** — no polling occurs because the fixed-window quota won't reset until the TTL expires.
+- If the remaining TTL is within `max_wait_time`, the limiter polls until the override expires and falls back to the sliding window.
+
+This differs from the sliding window, which always polls in short intervals since entries continuously slide out of the window.
+
+Typical usage in an API client:
+
+```ruby
+class ExternalApiClient
+  extend Hanikamu::RateLimit::Mixin
+
+  limit_method :call, registry: :external_api
+
+  def call
+    response = http_client.get("/endpoint")
+
+    if response.headers["X-RateLimit-Remaining"]
+      Hanikamu::RateLimit.register_temporary_limit(
+        :external_api,
+        remaining: response.headers["X-RateLimit-Remaining"],
+        reset: response.headers["X-RateLimit-Reset"]
+      )
+    end
+
+    response
+  end
+end
+```
+
+### Class methods
+
+To rate limit class methods, apply the mixin to the singleton class:
+
+```ruby
+class MyService
+  class << self
+    extend Hanikamu::RateLimit::Mixin
+
+    limit_method :call, rate: 5, interval: 1.0
+
+    def call
+      # work
+    end
+  end
+end
+```
+
+You can also use registered limits:
+
+```ruby
+Hanikamu::RateLimit.configure do |config|
+  config.register_limit(:external_api, rate: 5, interval: 1.0)
+end
+
+class MyService
+  class << self
+    extend Hanikamu::RateLimit::Mixin
+
+    limit_method :call, registry: :external_api
+
+    def call
+      # work
+    end
+  end
+end
+
+```
+
 ## Error Handling
 
 If Redis is unavailable, `RateQueue#shift` logs a warning and returns `nil`.
@@ -127,13 +220,13 @@ If Redis is unavailable, `RateQueue#shift` logs a warning and returns `nil`.
 ## Testing
 
 ```bash
-bundle exec rspec
+make rspec
 ```
 
 ## Development
 
 ```bash
-bundle exec rake
+make shell
 ```
 
 ## License

data/lib/hanikamu/rate_limit/mixin.rb

@@ -3,36 +3,87 @@
 module Hanikamu
   module RateLimit
     module Mixin
-      def limit_method(method, rate:, interval: 60, **options, &)
-        queue = build_queue(rate, interval, method, options, &)
-        install_rate_limited_method(method, queue)
-      end
+      def limit_method(
+        method,
+        registry: nil,
+        rate: nil,
+        interval: nil,
+        check_interval: nil,
+        max_wait_time: nil,
+        &
+      )
+        if registry
+          validate_registry_only!(rate, interval, check_interval, max_wait_time)
+          queue = build_queue_from_registry(method, registry, &)
+        else
+          validate_inline_options!(rate, interval)
+          interval ||= 60
+          queue = build_queue(
+            rate,
+            interval,
+            method,
+            check_interval: check_interval,
+            max_wait_time: max_wait_time,
+            &
+          )
+        end
 
-      def limit_with(method, registry:, **overrides, &)
-        registry_config = Hanikamu::RateLimit.fetch_limit(registry)
-        merged = registry_config.merge(overrides.compact)
-        rate = merged.fetch(:rate)
-        interval = merged.fetch(:interval)
-        options = merged.slice(:check_interval, :max_wait_time, :key_prefix)
-        queue = build_queue(rate, interval, method, options, &)
         install_rate_limited_method(method, queue)
       end
 
       private
 
-      def build_queue(rate, interval, method, options, &)
+      def build_queue(
+        rate,
+        interval,
+        method,
+        key_prefix: nil,
+        check_interval: nil,
+        max_wait_time: nil,
+        override_key: nil,
+        &
+      )
         Hanikamu::RateLimit::RateQueue.new(
           rate,
           interval: interval,
           klass_name: name,
           method: method,
-          key_prefix: options[:key_prefix],
-          check_interval: options.fetch(:check_interval, Hanikamu::RateLimit.config.check_interval),
-          max_wait_time: options.fetch(:max_wait_time, Hanikamu::RateLimit.config.max_wait_time),
+          key_prefix: key_prefix,
+          override_key: override_key,
+          check_interval: check_interval.nil? ? Hanikamu::RateLimit.config.check_interval : check_interval,
+          max_wait_time: max_wait_time.nil? ? Hanikamu::RateLimit.config.max_wait_time : max_wait_time,
+          &
+        )
+      end
+
+      def build_queue_from_registry(method, registry, &)
+        registry_config = Hanikamu::RateLimit.fetch_limit(registry)
+        rate = registry_config.fetch(:rate)
+        interval = registry_config.fetch(:interval)
+        build_queue(
+          rate,
+          interval,
+          method,
+          key_prefix: registry_config[:key_prefix],
+          check_interval: registry_config[:check_interval],
+          max_wait_time: registry_config[:max_wait_time],
+          override_key: Hanikamu::RateLimit.override_key_for(registry),
           &
         )
       end
 
+      def validate_registry_only!(rate, interval, check_interval, max_wait_time)
+        return unless rate || interval || !check_interval.nil? || !max_wait_time.nil?
+
+        raise ArgumentError, "registry: must be used alone"
+      end
+
+      def validate_inline_options!(rate, _interval)
+        return if rate
+
+        raise ArgumentError, "Either registry: or rate: must be provided"
+      end
+
       def install_rate_limited_method(method, queue)
         mixin = Module.new do
           rate_queue = queue

data/lib/hanikamu/rate_limit/rate_queue.rb

@@ -9,11 +9,30 @@ module Hanikamu
       KEY_PREFIX = "hanikamu:rate_limit:rate_queue"
       LUA_SCRIPT = <<~LUA
         local key = KEYS[1]
+        local override_key = KEYS[2]
         local now = tonumber(ARGV[1])
         local interval = tonumber(ARGV[2])
         local rate = tonumber(ARGV[3])
         local member = ARGV[4]
 
+        if override_key and override_key ~= "" then
+          local override_val = redis.call("GET", override_key)
+          if override_val then
+            local remaining = tonumber(override_val)
+            if remaining then
+              local ttl = redis.call("TTL", override_key)
+              if ttl > 0 then
+                if remaining > 0 then
+                  redis.call("DECR", override_key)
+                  return {1, 0, 0}
+                else
+                  return {0, ttl, 1}
+                end
+              end
+            end
+          end
+        end
+
         redis.call("ZREMRANGEBYSCORE", key, 0, now - interval)
         local count = redis.call("ZCARD", key)
 
@@ -33,25 +52,39 @@ module Hanikamu
         return {0, interval}
       LUA
 
-      def initialize(rate, klass_name:, method:, interval: 60, **options, &block)
+      def initialize(
+        rate,
+        klass_name:,
+        method:,
+        interval: 60,
+        key_prefix: nil,
+        override_key: nil,
+        check_interval: nil,
+        max_wait_time: nil,
+        &block
+      )
         @rate = rate
         @interval = interval.to_f
         @klass_name = klass_name
         @method = method
-        @key_prefix = options[:key_prefix]
-        @check_interval = options.fetch(:check_interval, Hanikamu::RateLimit.config.check_interval)
-        @max_wait_time = options.fetch(:max_wait_time, Hanikamu::RateLimit.config.max_wait_time)
+        @key_prefix = key_prefix
+        @override_key = override_key&.to_s
+        @check_interval = check_interval.nil? ? Hanikamu::RateLimit.config.check_interval : check_interval
+        @max_wait_time = max_wait_time.nil? ? Hanikamu::RateLimit.config.max_wait_time : max_wait_time
         @block = block
       end
 
       def shift
         start_time = current_time
-
         loop do
-          allowed, sleep_time = attempt_shift(start_time)
+          allowed, sleep_time, is_override = attempt_shift(start_time)
 
           return if allowed == 1
 
+          if is_override == 1 && @max_wait_time && sleep_time.to_f > @max_wait_time
+            raise Hanikamu::RateLimit::RateLimitError, "Max wait time exceeded"
+          end
+
           handle_sleep(sleep_time)
         end
       rescue Redis::BaseError => e
@@ -72,6 +105,12 @@ module Hanikamu
         end
       end
 
+      def redis_keys
+        return [redis_key] if @override_key.nil? || @override_key.empty?
+
+        [redis_key, @override_key]
+      end
+
       def attempt_shift(start_time)
         now = current_time
         elapsed = now - start_time
@@ -84,11 +123,7 @@ module Hanikamu
       end
 
       def eval_script(now, member)
-        redis.evalsha(
-          lua_sha,
-          keys: [redis_key],
-          argv: [now, @interval, @rate, member]
-        )
+        redis.evalsha(lua_sha, keys: redis_keys, argv: [now, @interval, @rate, member])
       rescue Redis::CommandError => e
         return reload_script_and_retry(now, member) if e.message.include?("NOSCRIPT")
 
@@ -97,11 +132,7 @@ module Hanikamu
 
       def reload_script_and_retry(now, member)
         @lua_sha = redis.script(:load, LUA_SCRIPT)
-        redis.evalsha(
-          lua_sha,
-          keys: [redis_key],
-          argv: [now, @interval, @rate, member]
-        )
+        redis.evalsha(lua_sha, keys: redis_keys, argv: [now, @interval, @rate, member])
       end
 
       def handle_sleep(sleep_time)

data/lib/hanikamu/rate_limit/version.rb

@@ -2,6 +2,6 @@
 
 module Hanikamu
   module RateLimit
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/hanikamu/rate_limit.rb

@@ -18,23 +18,61 @@ module Hanikamu
     class << self
       def configure(&block)
         super do |config|
-          config.define_singleton_method(:register_limit) do |name, **options|
-            Hanikamu::RateLimit.register_limit(name, **options)
+          config.define_singleton_method(:register_limit) do |
+            name,
+            rate:,
+            interval:,
+            check_interval: nil,
+            max_wait_time: nil
+          |
+            Hanikamu::RateLimit.register_limit(
+              name,
+              rate: rate,
+              interval: interval,
+              check_interval: check_interval,
+              max_wait_time: max_wait_time
+            )
           end
           block&.call(config)
         end
       end
 
-      def register_limit(name, **options)
-        registry.register(normalize_name(name), normalize_registry_options(name, options))
+      def register_limit(name, rate:, interval:, check_interval: nil, max_wait_time: nil)
+        registry.register(
+          normalize_name(name),
+          normalize_registry_options(
+            name,
+            rate: rate,
+            interval: interval,
+            check_interval: check_interval,
+            max_wait_time: max_wait_time
+          )
+        )
       end
 
       def fetch_limit(name)
         registry.resolve(normalize_name(name))
-      rescue Dry::Container::Error
+      rescue Dry::Container::Error, KeyError
         raise ArgumentError, "Unknown registered limit: #{name}"
       end
 
+      def register_temporary_limit(name, remaining:, reset:)
+        fetch_limit(name) # raise if not registered
+        remaining_value = Integer(remaining, exception: false)
+        reset_value = Integer(reset, exception: false)
+        return false if remaining_value.nil? || reset_value.nil?
+        return false if remaining_value.negative? || reset_value <= 0
+
+        key = override_key_for(name)
+        redis_client.set(key, remaining_value, ex: reset_value)
+        true
+      end
+
+      def override_key_for(name)
+        normalized = normalize_name(name)
+        "#{RateQueue::KEY_PREFIX}:registry:#{normalized}:override"
+      end
+
       def reset_registry!
         @registry = Dry::Container.new
       end
@@ -46,16 +84,20 @@ module Hanikamu
       private
 
       def normalize_name(name)
-        name.to_sym
+        normalized = name.to_s.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/^_+|_+$/, "")
+        normalized.to_sym
+      end
+
+      def redis_client
+        @redis_client ||= Redis.new(url: config.redis_url)
       end
 
-      def normalize_registry_options(name, options)
-        rate = options.fetch(:rate)
-        interval = options.fetch(:interval)
-        key_prefix = options[:key_prefix] || "#{RateQueue::KEY_PREFIX}:registry:#{name}"
+      def normalize_registry_options(name, rate:, interval:, check_interval:, max_wait_time:)
+        normalized = normalize_name(name)
+        key_prefix = "#{RateQueue::KEY_PREFIX}:registry:#{normalized}"
         registry_options = { rate: rate, interval: interval, key_prefix: key_prefix }
-        registry_options[:check_interval] = options[:check_interval] unless options[:check_interval].nil?
-        registry_options[:max_wait_time] = options[:max_wait_time] unless options[:max_wait_time].nil?
+        registry_options[:check_interval] = check_interval unless check_interval.nil?
+        registry_options[:max_wait_time] = max_wait_time unless max_wait_time.nil?
         registry_options
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hanikamu-rate-limit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nicolai Seerup