rails_rate_limit 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e681ccbf67051878bd884a7a55db8650056d4107a78b6c5c8a40d5bd5576e50e
-  data.tar.gz: 3ce8f1ddde50ca6cf278f3431b1e263d147631c4081be305447a57d38d3f4bd4
+  metadata.gz: f84a9dd27c84c9d0519657dcdc6a03da54339a00951fba0e4dfe847e210bc416
+  data.tar.gz: 68ed631f37784ac86f12e261cd28e99caf879f4b604604f5c0717b9e9a071062
 SHA512:
-  metadata.gz: e77b8544870e4628b9103c017903ed151eb6aa9f501adae15fbdb13a60f5bf79fa62463a6bcdcd856868cd8721e56f7504ce6f9ad4c1dd1f2789343358d4c517
-  data.tar.gz: d9c0ead4ac6e247c0516e6a31872ec2094efde122226809c51db1761698fcc16b93aea8e5128cb1de06e5f6ace53442ef1f0689248ae42858f4818fb244c1c1b
+  metadata.gz: 0d5822c1423345099c7d42a21ca11951720de2f9be00e7858fdf9ffee69b3e970454ed878e57e36c75ee74e49c213a0de1a079f2a476c52c95cdaabefdc34138
+  data.tar.gz: 736ce16dddb1b5e238e88570cd67cbce3895f2bb51a61a10a5d635112d4fe3d3489a33bf01735ddc67ebf350a669f668c3ce1952324a8ba5145649c0806cc379

data/README.md

@@ -1,14 +1,13 @@
-# Rails Rate Limit
+# **Rails Rate Limit**
 
 [![Gem Version](https://badge.fury.io/rb/rails_rate_limit.svg)](https://badge.fury.io/rb/rails_rate_limit)
 [![Build Status](https://github.com/kasvit/rails_rate_limit/workflows/Ruby/badge.svg)](https://github.com/kasvit/rails_rate_limit/actions)
 
-A flexible and robust rate limiting solution for Ruby on Rails applications. The gem implements a sliding window log algorithm, which means it tracks the exact timestamp of each request and calculates the count within a sliding time window. This provides more accurate rate limiting compared to fixed window approaches.
+A flexible and robust rate limiting solution for Ruby on Rails applications. The gem implements a **sliding window log** algorithm, which means it tracks the exact timestamp of each request and calculates the count within a sliding time window. This provides more accurate rate limiting compared to fixed window approaches.
 
 For example, if you set a limit of 100 requests per hour, and a user makes 100 requests at 2:30 PM, they won't be able to make another request until some of those requests "expire" after 2:30 PM the next hour. This prevents the common issue with fixed windows where users could potentially make 200 requests around the window boundary.
 
-Supports rate limiting for both HTTP requests and method calls, with multiple storage backends (Redis, Memcached, Memory).
-Inspired by https://github.com/rails/rails/blob/8-0-sec/actionpack/lib/action_controller/metal/rate_limiting.rb.
+The gem supports rate limiting for both HTTP requests (in controllers) and instance method calls (in any Ruby class), with multiple storage backends (Redis, Memcached, Memory).
 
 ## Installation
 
@@ -30,7 +29,7 @@ Create an initializer `config/initializers/rails_rate_limit.rb`:
 
 ```ruby
 RailsRateLimit.configure do |config|
-  # Required: Choose your default storage backend
+  # Optional: Choose your storage backend (default: :memory)
   config.default_store = :redis # Available options: :redis, :memcached, :memory
   
   # Optional: Configure Redis connection (required if using Redis store)
@@ -47,10 +46,12 @@ RailsRateLimit.configure do |config|
   )
   
   # Optional: Configure logging
+  # set `nil` to disable logging
   config.logger = Rails.logger
   
   # Optional: Configure default handler for controllers (HTTP requests)
-  config.default_on_controller_exceeded = -> {
+  config.handle_controller_exceeded = -> {
+    # Default handler returns a JSON response with a 429 status code
     render json: {
       error: "Too many requests",
       retry_after: response.headers["Retry-After"]
@@ -58,10 +59,9 @@ RailsRateLimit.configure do |config|
   }
   
   # Optional: Configure default handler for methods
-  config.default_on_method_exceeded = -> {
-    # Your default logic for methods
-    # For example: log the event, notify admins, etc.
-    Rails.logger.warn("Rate limit exceeded for #{self.class.name}")
+  # By default, it raises RailsRateLimit::RateLimitExceeded
+  config.handle_klass_exceeded = -> {
+    raise RailsRateLimit::RateLimitExceeded, "Rate limit exceeded"
   }
 end
 ```
@@ -99,33 +99,65 @@ end
 
 ### Rate Limiting Methods
 
-You can limit any method calls in your classes:
+You can limit both instance and class methods in your classes:
 
 ```ruby
 class ApiClient
-  include RailsRateLimit::Klass # include this module
+  include RailsRateLimit::Klass
 
+  # Instance method
   def make_request
     # Your API call logic here
   end
 
-  # IMPORTANT: set_rate_limit must be called AFTER method definition 
-  # Basic usage
+  # Class method
+  def self.bulk_request
+    # Your API call logic here
+  end
+
+  # Rate limit for instance method
   set_rate_limit :make_request,
                 limit: 100,
                 period: 1.minute
 
-  # Advanced usage with all options
+  # Rate limit for class method
+  set_rate_limit :bulk_request,
+                limit: 10,
+                period: 1.hour
+
+  # Advanced usage with all options (instance method)
   set_rate_limit :another_method,
                 limit: 10,                       # Maximum calls allowed
                 period: 1.hour,                  # Time window for the limit
                 by: -> { "client:#{id}" },       # Method call identifier
                 store: :memcached,               # Override default store
                 on_exceeded: -> {                # Custom error handler
+                  # You can handle the error here and return any value (including nil)
                   notify_admin
                   log_exceeded_event
-                  enqueue_retry_job
+                  nil # Method will return nil
+                }
+
+  # Advanced usage with all options (class method)
+  set_rate_limit :another_class_method,
+                limit: 5,                        # Maximum calls allowed
+                period: 1.day,                   # Time window for the limit
+                by: -> { "global:#{name}" },     # Method call identifier
+                store: :redis,                   # Override default store
+                on_exceeded: -> {                # Custom error handler
+                  log_exceeded_event
+                  "Rate limit exceeded"          # Return custom message
                 }
+
+  # Direct rate limit setting
+  # You can also set rate limits directly if you have both instance and class methods with the same name
+  set_instance_rate_limit :process,             # For instance method
+                         limit: 10,
+                         period: 1.hour
+
+  set_class_rate_limit :process,                # For class method
+                      limit: 5,
+                      period: 1.hour
 end
 ```
 
@@ -135,8 +167,9 @@ For both controllers and methods:
 - `limit`: (Required) Maximum number of requests/calls allowed
 - `period`: (Required) Time period for the limit (in seconds or ActiveSupport::Duration)
 - `by`: (Optional) Lambda/Proc to generate unique identifier
-  - Default for controllers: `request.remote_ip`
-  - Default for methods: `"#{class_name}:#{id || object_id}"`
+  - Default for controllers: `"#{controller.class.name}:#{controller.request.remote_ip}"`
+  - Default for instance methods: `"#{self.class.name}##{method_name}:#{respond_to?(:id) ? 'id='+id.to_s : 'object_id='+object_id.to_s}"`
+  - Default for class methods: `"#{class.name}.#{method_name}"`
 - `store`: (Optional) Override default storage backend (`:redis`, `:memcached`, `:memory`)
 - `on_exceeded`: (Optional) Custom handler for rate limit exceeded
 
@@ -149,16 +182,34 @@ Additional options for controllers:
 The gem provides different default behaviors for controllers and methods:
 
 1. For controllers (HTTP requests):
-   - The `on_exceeded` handler (or `default_on_controller_exceeded` if not specified) is called
+   - The `on_exceeded` handler (or default handler) is called
    - By default, returns HTTP 429 with a JSON error message
    - Headers are automatically added with limit information
    - The handler's return value is used (usually render/redirect)
 
 2. For methods:
-   - The `on_exceeded` handler (or `default_on_method_exceeded` if not specified) is called
+   - The `on_exceeded` handler (if provided) is called first
+   - Then `RailsRateLimit::RateLimitExceeded` exception is raised
    - The event is logged if a logger is configured
-   - Returns `nil` after handler execution to indicate no result
-   - No exception is raised, making it easier to handle in your code
+   - You should catch the exception to handle the error
+
+### Default error messages
+
+By default, the gem logs the error message to the logger together with your custom `on_exceeded` message.
+```ruby
+@logger.warn(
+  "Rate limit exceeded for #{key}. " \
+  "Limit: #{limit} requests per #{period} seconds"
+)
+# where key for klass is `by` or default unique identifier
+# Rate limit exceeded for ReportGenerator#generate:object_id=218520. Limit: 2 requests per 10 seconds
+# Rate limit exceeded for Notification#deliver:id=1. Limit: 3 requests per 60 seconds
+
+# where key for controller is `by` or default unique identifier
+# Rate limit exceeded for HomeController:127.0.0.1. Limit: 100 requests per 1 minute
+```
+
+You can remove it by setting `config.logger = nil` or specify `by` options.
 
 ### HTTP Headers
 
@@ -183,7 +234,7 @@ For controller rate limiting, the following headers are automatically added:
 - Works well in distributed environments
 - Good option if you're already using Memcached
 
-### Memory
+### Memory (Default)
 - No additional dependencies
 - Perfect for development or single-server setups
 - Data is lost on server restart

data/lib/rails_rate_limit/configuration.rb

@@ -4,39 +4,40 @@
 module RailsRateLimit
   class Configuration
     attr_accessor :default_store, :redis_connection, :memcached_connection, :logger
-    attr_reader :default_on_controller_exceeded, :default_on_method_exceeded
+    attr_reader :handle_controller_exceeded, :handle_klass_exceeded
 
     def initialize
-      @default_store = :redis
+      @default_store = :memory
       @redis_connection = nil
       @memcached_connection = nil
       @logger = nil
       set_default_handlers
     end
 
-    def default_on_controller_exceeded=(handler)
-      raise ArgumentError, "default_on_controller_exceeded must be a Proc" unless handler.is_a?(Proc)
+    def handle_controller_exceeded=(handler)
+      raise ArgumentError, "handle_controller_exceeded must be a Proc" unless handler.is_a?(Proc)
 
-      @default_on_controller_exceeded = handler
+      @handle_controller_exceeded = handler
     end
 
-    def default_on_method_exceeded=(handler)
-      raise ArgumentError, "default_on_method_exceeded must be a Proc" unless handler.is_a?(Proc)
+    def handle_klass_exceeded=(handler)
+      raise ArgumentError, "handle_klass_exceeded must be a Proc" unless handler.is_a?(Proc)
 
-      @default_on_method_exceeded = handler
+      @handle_klass_exceeded = handler
     end
 
     private
 
     def set_default_handlers
-      @default_on_controller_exceeded = lambda {
+      @handle_controller_exceeded = lambda {
         render json: {
-          error: "Too many requests",
-          retry_after: response.headers["Retry-After"]
+          error: "Too many requests"
         }, status: :too_many_requests
       }
 
-      @default_on_method_exceeded = -> { nil }
+      @handle_klass_exceeded = lambda {
+        raise RailsRateLimit::RateLimitExceeded, "Rate limit exceeded"
+      }
     end
   end
 end

data/lib/rails_rate_limit/controller.rb

@@ -13,7 +13,7 @@ module RailsRateLimit
         before_action(options) do |controller|
           limiter = RateLimiter.new(
             context: controller,
-            by: by,
+            by: by || "#{controller.class.name}:#{controller.request.remote_ip}",
             limit: limit,
             period: period.to_i,
             store: store
@@ -22,7 +22,7 @@ module RailsRateLimit
           begin
             limiter.perform!
           rescue RailsRateLimit::RateLimitExceeded
-            handler = on_exceeded.nil? ? RailsRateLimit.configuration.default_on_controller_exceeded : on_exceeded
+            handler = on_exceeded.nil? ? RailsRateLimit.configuration.handle_controller_exceeded : on_exceeded
             controller.instance_exec(&handler)
           end
         end

data/lib/rails_rate_limit/klass.rb

@@ -8,12 +8,50 @@ module RailsRateLimit
       def set_rate_limit(method_name, limit:, period:, by: nil, store: nil, on_exceeded: nil)
         Validations.validate_options!(limit: limit, period: period, by: by, store: store)
 
+        if method_defined?(method_name) || private_method_defined?(method_name)
+          set_instance_rate_limit(method_name, limit: limit, period: period, by: by, store: store,
+                                               on_exceeded: on_exceeded)
+        elsif singleton_class.method_defined?(method_name) || singleton_class.private_method_defined?(method_name)
+          set_class_rate_limit(method_name, limit: limit, period: period, by: by, store: store,
+                                            on_exceeded: on_exceeded)
+        else
+          raise ArgumentError, "Method #{method_name} is not defined"
+        end
+      end
+
+      def set_instance_rate_limit(method_name, limit:, period:, by:, store:, on_exceeded:)
         original_method = instance_method(method_name)
 
         define_method(method_name) do |*args, &block|
           limiter = RateLimiter.new(
             context: self,
-            by: by || -> { "#{self.class.name}:#{respond_to?(:id) ? id : object_id}" },
+            by: by || lambda {
+              "#{self.class.name}##{method_name}:#{respond_to?(:id) ? "id=#{id}" : "object_id=#{object_id}"}"
+            },
+            limit: limit,
+            period: period.to_i,
+            store: store
+          )
+
+          begin
+            limiter.perform!
+            original_method.bind(self).call(*args, &block)
+          rescue RailsRateLimit::RateLimitExceeded
+            handler = on_exceeded.nil? ? RailsRateLimit.configuration.handle_klass_exceeded : on_exceeded
+            instance_exec(&handler)
+          end
+        end
+      end
+
+      def set_class_rate_limit(method_name, limit:, period:, by:, store:, on_exceeded:)
+        original_method = singleton_class.instance_method(method_name)
+
+        singleton_class.define_method(method_name) do |*args, &block|
+          limiter = RateLimiter.new(
+            context: self,
+            by: by || lambda {
+              "#{name}.#{method_name}"
+            },
             limit: limit,
             period: period.to_i,
             store: store
@@ -23,9 +61,8 @@ module RailsRateLimit
             limiter.perform!
             original_method.bind(self).call(*args, &block)
           rescue RailsRateLimit::RateLimitExceeded
-            handler = on_exceeded.nil? ? RailsRateLimit.configuration.default_on_method_exceeded : on_exceeded
+            handler = on_exceeded.nil? ? RailsRateLimit.configuration.handle_klass_exceeded : on_exceeded
             instance_exec(&handler)
-            nil
           end
         end
       end

data/lib/rails_rate_limit/rate_limiter.rb

@@ -48,8 +48,6 @@ module RailsRateLimit
     end
 
     def resolve_key
-      return context.request.remote_ip if by.nil?
-
       by.is_a?(Proc) ? context.instance_exec(&by) : by
     end
 

data/lib/rails_rate_limit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsRateLimit
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_rate_limit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kasvit
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-01-16 00:00:00.000000000 Z
+date: 2025-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dalli
@@ -169,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
 summary: Flexible rate limiting for Rails applications