hanikamu-rate-limit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: af12b9492738472c4e8bd8431a20b053bde92ec6af556dcd6db9af75c9529e70
+  data.tar.gz: '0187f0d7f9d9edde19f5b095368b19feb90c73a51d25301e356161930392ccaf'
+SHA512:
+  metadata.gz: b77fb01c48f98d938bdbd4954672be5a3f2fbbed522d4c662349d4b3e6c98327893d7849bc8b8c4936cf33e13af7e5487805f4da6b7451ff4274471d0e42363b
+  data.tar.gz: 2bbe7515db8c173aab88c2ee198d0b9a4fb1015091d74706bb0045a31c37166cb1073a29806937db4057e279183c51fe5fd0e7e804a258d4463e29d2fca0ba04

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-02-04
+
+- Initial release of Hanikamu::RateLimit.

data/Dockerfile

@@ -0,0 +1,14 @@
+# Base image
+FROM ruby:4.0
+
+WORKDIR "/app"
+
+# Add our Gemfile and install gems
+ADD Gemfile* ./
+ADD hanikamu-rate-limit.gemspec ./
+ADD lib ./lib
+
+RUN bundle install
+
+# Copy the rest of the application
+ADD . .

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hanikamu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Makefile

@@ -0,0 +1,25 @@
+.PHONY: shell
+shell: ## access to the system console
+	 docker-compose run --rm app bash
+
+.PHONY: build
+build: ## build the image
+	docker-compose build
+
+.PHONY: bundle
+bundle: ## install gems and rebuild image
+	- docker-compose run --rm app bundle install
+	- ${MAKE} build
+
+.PHONY: console
+console: ## build the image
+		docker-compose run --rm app bash -c "bin/console"
+
+.PHONY: rspec
+rspec: ## build the image
+	docker-compose run --rm app bash -c "bundle exec rspec"
+
+
+.PHONY: cops
+cops: ## build the image
+	docker-compose run --rm app sh -c "bundle exec rubocop -A"

data/README.md

@@ -0,0 +1,141 @@
+# Hanikamu::RateLimit
+
+[![ci](https://github.com/Hanikamu/hanikamu-rate-limit/actions/workflows/ci.yml/badge.svg)](https://github.com/Hanikamu/hanikamu-rate-limit/actions/workflows/ci.yml)
+
+Distributed, Redis-backed rate limiting with a sliding window algorithm. Works across processes and threads by coordinating through Redis.
+
+## Table of Contents
+
+1. [Why Hanikamu::RateLimit?](#why-hanikamurate-limit)
+2. [Quick Start](#quick-start)
+3. [Configuration](#configuration)
+4. [Usage](#usage)
+5. [Error Handling](#error-handling)
+6. [Testing](#testing)
+7. [Development](#development)
+8. [License](#license)
+
+## Why Hanikamu::RateLimit?
+
+- **Use case**: You run 40 Sidekiq workers that all hit the same external marketing API capped at 20 requests per second. Without coordination, they’ll burst and trigger throttling. With a shared limit, every worker routes through the same Redis-backed window so aggregate throughput stays at 20 req/s across the whole fleet.
+- **Distributed by design**: Limits are enforced through Redis so multiple app instances share a single limit.
+- **Sliding window**: Limits are based on the most recent interval window, not fixed buckets.
+- **Backoff with polling**: When a limit is hit, the limiter sleeps in short intervals until a slot opens.
+- **Bounded waiting**: Callers can set a max wait time to avoid waiting indefinitely.
+- **Minimal surface area**: A single mixin and a compact queue implementation.
+
+## Quick Start
+
+**1. Install the gem**
+
+Requires Ruby 4.0 or later.
+
+```ruby
+# Gemfile
+gem "hanikamu-rate-limit", "~> 0.1.0"
+```
+
+```bash
+bundle install
+```
+
+**2. Configure Redis**
+
+```ruby
+Hanikamu::RateLimit.configure do |config|
+  config.redis_url = ENV.fetch("REDIS_URL")
+  config.check_interval = 0.25
+  config.max_wait_time = 1.5
+
+  config.register_limit(:external_api, rate: 5, interval: 0.5, check_interval: 0.5, max_wait_time: 5)
+end
+```
+
+**3. Limit a method**
+
+```ruby
+class MyService
+  extend Hanikamu::RateLimit::Mixin
+
+  limit_method :execute, rate: 5, interval: 1.0
+
+  def execute
+    # work
+  end
+end
+```
+
+**4. Call it**
+
+```ruby
+MyService.new.execute
+```
+
+## Configuration
+
+Available settings:
+
+- `redis_url`: Redis connection URL (required).
+- `check_interval`: default sleep interval between retries (default: 0.5 seconds).
+- `max_wait_time`: max time to wait before raising (default: 2.0 seconds).
+- `register_limit`: define a named limit shared across classes.
+
+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.
+
+## Usage
+
+Optional per-method overrides:
+
+```ruby
+limit_method :execute, rate: 5, interval: 1.0, check_interval: 0.1, max_wait_time: 3.0
+```
+
+Use a registered limit shared across classes:
+
+```ruby
+class ExternalApiClient
+  extend Hanikamu::RateLimit::Mixin
+
+  limit_with :execute, registry: :external_api
+
+  def execute
+    # work
+  end
+end
+```
+
+Registry precedence (highest to lowest):
+
+1. Per-method overrides passed to `limit_with`.
+2. Registered limit options.
+3. Global defaults from `Hanikamu::RateLimit.configure`.
+
+Reset method is generated automatically:
+
+```ruby
+MyService.reset_execute_limit!
+```
+
+## Error Handling
+
+If Redis is unavailable, `RateQueue#shift` logs a warning and returns `nil`.
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+## Development
+
+```bash
+bundle exec rake
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docker-compose.yml

@@ -0,0 +1,22 @@
+version: "3"
+networks:
+  docker-compose-example-tier:
+    driver: bridge
+services:
+  redis:
+    image: redis:7-alpine
+    networks:
+      - docker-compose-example-tier
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      HISTFILE: /app/tmp/ash_history
+      REDIS_URL: redis://redis:6379/15
+    volumes:
+      - .:/app
+    networks:
+      - docker-compose-example-tier
+    depends_on:
+      - redis

data/lib/hanikamu/rate_limit/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hanikamu
+  module RateLimit
+    class RateLimitError < StandardError; end
+  end
+end

data/lib/hanikamu/rate_limit/mixin.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+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_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, &)
+        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),
+          &
+        )
+      end
+
+      def install_rate_limited_method(method, queue)
+        mixin = Module.new do
+          rate_queue = queue
+
+          define_method(method) do |*args, **options, &blk|
+            rate_queue.shift
+            options.empty? ? super(*args, &blk) : super(*args, **options, &blk)
+          end
+        end
+
+        define_singleton_method("reset_#{method}_limit!") { queue.reset }
+        prepend(mixin)
+      end
+    end
+  end
+end

data/lib/hanikamu/rate_limit/rate_queue.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "redis"
+
+module Hanikamu
+  module RateLimit
+    class RateQueue
+      KEY_PREFIX = "hanikamu:rate_limit:rate_queue"
+      LUA_SCRIPT = <<~LUA
+        local key = KEYS[1]
+        local now = tonumber(ARGV[1])
+        local interval = tonumber(ARGV[2])
+        local rate = tonumber(ARGV[3])
+        local member = ARGV[4]
+
+        redis.call("ZREMRANGEBYSCORE", key, 0, now - interval)
+        local count = redis.call("ZCARD", key)
+
+        if count < rate then
+          redis.call("ZADD", key, now, member)
+          redis.call("EXPIRE", key, math.ceil(interval) + 1)
+          return {1, 0}
+        end
+
+        local oldest = redis.call("ZRANGE", key, 0, 0, "WITHSCORES")
+        if oldest and oldest[2] then
+          local sleep_for = tonumber(oldest[2]) + interval - now
+          if sleep_for < 0 then sleep_for = 0 end
+          return {0, sleep_for}
+        end
+
+        return {0, interval}
+      LUA
+
+      def initialize(rate, klass_name:, method:, interval: 60, **options, &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)
+        @block = block
+      end
+
+      def shift
+        start_time = current_time
+
+        loop do
+          allowed, sleep_time = attempt_shift(start_time)
+
+          return if allowed == 1
+
+          handle_sleep(sleep_time)
+        end
+      rescue Redis::BaseError => e
+        warn "[Hanikamu::RateLimit] Redis error: #{e.class} - #{e.message}"
+        nil
+      end
+
+      def reset
+        redis.del(redis_key)
+      end
+
+      private
+
+      def redis_key
+        @redis_key ||= begin
+          prefix = @key_prefix || "#{KEY_PREFIX}:#{@klass_name}:#{@method}"
+          "#{prefix}:#{@rate}:#{@interval}"
+        end
+      end
+
+      def attempt_shift(start_time)
+        now = current_time
+        elapsed = now - start_time
+        if @max_wait_time && elapsed > @max_wait_time
+          raise Hanikamu::RateLimit::RateLimitError, "Max wait time exceeded"
+        end
+
+        member = "#{now}-#{SecureRandom.uuid}"
+        eval_script(now, member)
+      end
+
+      def eval_script(now, member)
+        redis.evalsha(
+          lua_sha,
+          keys: [redis_key],
+          argv: [now, @interval, @rate, member]
+        )
+      rescue Redis::CommandError => e
+        return reload_script_and_retry(now, member) if e.message.include?("NOSCRIPT")
+
+        raise
+      end
+
+      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]
+        )
+      end
+
+      def handle_sleep(sleep_time)
+        @block&.call(sleep_time)
+        actual_sleep = @check_interval ? [@check_interval, sleep_time].min : sleep_time
+        sleep(actual_sleep) if actual_sleep.to_f.positive?
+      end
+
+      def redis
+        @redis ||= Redis.new(url: Hanikamu::RateLimit.config.redis_url)
+      end
+
+      def lua_sha
+        @lua_sha ||= redis.script(:load, LUA_SCRIPT)
+      end
+
+      def current_time
+        Time.now.to_f
+      end
+    end
+  end
+end

data/lib/hanikamu/rate_limit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hanikamu
+  module RateLimit
+    VERSION = "0.1.0"
+  end
+end

data/lib/hanikamu/rate_limit.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "dry/container"
+require "hanikamu/rate_limit/errors"
+require "hanikamu/rate_limit/mixin"
+require "hanikamu/rate_limit/rate_queue"
+require "hanikamu/rate_limit/version"
+
+module Hanikamu
+  module RateLimit
+    extend Dry::Configurable
+
+    setting :redis_url
+    setting :max_wait_time, default: 2.0
+    setting :check_interval, default: 0.5
+
+    class << self
+      def configure(&block)
+        super do |config|
+          config.define_singleton_method(:register_limit) do |name, **options|
+            Hanikamu::RateLimit.register_limit(name, **options)
+          end
+          block&.call(config)
+        end
+      end
+
+      def register_limit(name, **options)
+        registry.register(normalize_name(name), normalize_registry_options(name, options))
+      end
+
+      def fetch_limit(name)
+        registry.resolve(normalize_name(name))
+      rescue Dry::Container::Error
+        raise ArgumentError, "Unknown registered limit: #{name}"
+      end
+
+      def reset_registry!
+        @registry = Dry::Container.new
+      end
+
+      def registry
+        @registry ||= Dry::Container.new
+      end
+
+      private
+
+      def normalize_name(name)
+        name.to_sym
+      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}"
+        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
+      end
+    end
+  end
+end

data/lib/hanikamu-rate-limit.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "hanikamu/rate_limit"

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: hanikamu-rate-limit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolai Seerup
+- Alejandro Jimenez
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: dry-container
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  Ruby gem for distributed rate limiting backed by Redis. Provides a sliding-window limiter
+  with configurable polling and maximum wait time, suitable for multi-process and multi-thread
+  workloads.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".DS_Store"
+- CHANGELOG.md
+- Dockerfile
+- LICENSE
+- Makefile
+- README.md
+- Rakefile
+- docker-compose.yml
+- lib/hanikamu-rate-limit.rb
+- lib/hanikamu/rate_limit.rb
+- lib/hanikamu/rate_limit/errors.rb
+- lib/hanikamu/rate_limit/mixin.rb
+- lib/hanikamu/rate_limit/rate_queue.rb
+- lib/hanikamu/rate_limit/version.rb
+homepage: https://github.com/Hanikamu/hanikamu-rate-limit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Hanikamu/hanikamu-rate-limit
+  source_code_uri: https://github.com/Hanikamu/hanikamu-rate-limit
+  changelog_uri: https://github.com/Hanikamu/hanikamu-rate-limit/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Distributed Redis-backed rate limiting
+test_files: []