throttle_machines 0.2.4-x86_64-linux

data/lib/throttle_machines.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'timeout'
+require 'zeitwerk'
+require 'active_support/core_ext/class/attribute'
+
+# Ecosystem dependencies
+require 'chrono_machines'
+require 'breaker_machines'
+
+# Set up Zeitwerk loader
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/throttle_machines/engine.rb") unless defined?(Rails::Engine)
+loader.setup
+
+module ThrottleMachines
+  class Configuration
+    attr_accessor :default_limit, :default_period, :default_storage, :clock,
+                  :default_algorithm, :instrumentation_enabled, :instrumentation_backend,
+                  :_storage_instance
+
+    def initialize
+      @default_limit = 100
+      @default_period = 60 # 1 minute
+      @default_storage = :memory
+      @default_algorithm = :fixed_window
+      @clock = nil
+      @instrumentation_enabled = true
+      @instrumentation_backend = nil
+      @fiber_safe = false
+      @_storage_instance = nil
+    end
+
+    def fiber_safe
+      @fiber_safe
+    end
+
+    def fiber_safe=(value)
+      @fiber_safe = !!value
+      ThrottleMachines.load_async_runtime! if @fiber_safe && ThrottleMachines.respond_to?(:load_async_runtime!)
+    end
+
+    alias async_enabled fiber_safe
+    alias async_enabled= fiber_safe=
+  end
+
+  @config = Configuration.new
+
+  class << self
+    # Delegate monotonic time to BreakerMachines for consistency
+    delegate :monotonic_time, to: :BreakerMachines
+
+    def config
+      @config
+    end
+
+    def configure
+      yield(config) if block_given?
+
+      # Apply instrumentation settings
+      Instrumentation.enabled = config.instrumentation_enabled
+      Instrumentation.backend = config.instrumentation_backend if config.instrumentation_backend
+      load_async_runtime! if config.fiber_safe
+    end
+
+    def storage
+      config._storage_instance ||= create_storage(config.default_storage)
+    end
+
+    def storage=(value)
+      config._storage_instance = create_storage(value)
+    end
+
+    def reset!(key = nil)
+      if key
+        storage.clear("#{key}*")
+      else
+        storage.clear
+        # Reset storage instance to force recreation with defaults
+        config._storage_instance = nil
+        # Re-apply instrumentation settings from the configuration
+        Instrumentation.enabled = config.instrumentation_enabled
+        Instrumentation.backend = config.instrumentation_backend
+      end
+    end
+
+    def control(key, &block)
+      control = Control.new(key)
+      control.instance_eval(&block) if block
+      control
+    end
+
+    def limit(key, limit:, period:, algorithm: nil, &block)
+      limiter = limiter(key, limit: limit, period: period, algorithm: algorithm)
+      limiter.throttle!(&block)
+    end
+
+    def break_circuit(key, failures:, timeout:, &block)
+      # Delegate to BreakerMachines; use reset_timeout for open duration
+      breaker = BreakerMachines::Circuit.new(
+        key,
+        failure_threshold: failures,
+        reset_timeout: timeout
+      )
+      breaker.call(&block)
+    end
+
+    def retry_with(max_attempts: 3, backoff: :exponential, &block)
+      # Delegate to chrono_machines
+      policy_options = {
+        max_attempts: max_attempts,
+        jitter_factor: backoff == :exponential ? 1.0 : 0.0
+      }
+      ChronoMachines.retry(policy_options, &block)
+    end
+
+    def limiter(key, limit:, period:, algorithm: nil)
+      Limiter.new(
+        key,
+        limit: limit,
+        period: period,
+        algorithm: algorithm || config.default_algorithm,
+        storage: storage
+      )
+    end
+
+    def async_breaker(...)
+      ThrottleMachines::AsyncBreaker.new(...)
+    end
+
+    def load_async_runtime!
+      require 'async'
+      require 'async/task'
+      true
+    rescue LoadError => e
+      raise unless e.message.include?('async')
+
+      raise LoadError, "The 'async' gem is required for fiber_safe mode. Add `gem 'async'` to your Gemfile."
+    end
+
+    private
+
+    def create_storage(storage)
+      case storage
+      when Symbol
+        create_storage_from_symbol(storage)
+      when Class
+        storage.new
+      when Storage::Base
+        storage
+      else
+        raise ArgumentError, "Invalid storage: #{storage.inspect}"
+      end
+    end
+
+    def create_storage_from_symbol(symbol)
+      case symbol
+      when :memory
+        Storage::Memory.new
+      when :redis
+        raise ArgumentError, 'Redis storage requires redis gem' unless defined?(Redis)
+
+        raise ArgumentError, 'Redis storage requires a Redis client instance. ' \
+                             'Configure with: config.storage = Storage::Redis.new(redis: Redis.new)'
+
+      when :null
+        Storage::Null.new
+      else
+        raise ArgumentError, "Unknown storage type: #{symbol}"
+      end
+    end
+  end
+
+  # Auto-configure with defaults
+  configure
+
+  CircuitOpenError = BreakerMachines::CircuitOpenError
+  RetryExhaustedError = ChronoMachines::MaxRetriesExceededError
+
+  # Back-compat wrapper: use BreakerMachines as the circuit implementation
+  Breaker = BreakerMachines::Circuit
+end
+
+# Optional speedups (order matters: most specific first)
+# These are loaded after Zeitwerk setup to allow graceful fallback.
+
+# Native Rust extension for performance-critical algorithms
+begin
+  require_relative "throttle_machines/native_speedup"
+rescue LoadError
+  # Native extension not available, pure Ruby will be used
+end
+
+# Async/Fiber support when Async gem is loaded
+begin
+  require_relative "throttle_machines/async_support"
+rescue LoadError
+  # Async gem not available
+end

metadata

@@ -0,0 +1,218 @@
+--- !ruby/object:Gem::Specification
+name: throttle_machines
+version: !ruby/object:Gem::Version
+  version: 0.2.4
+platform: x86_64-linux
+authors:
+- Abdelkader Boudih
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.4
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: breaker_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: chrono_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: ThrottleMachines provides ultra-thin, elegant rate limiting with temporal
+  precision for distributed systems.
+email:
+- terminale@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/throttle_machines.rb
+- lib/throttle_machines/async_breaker.rb
+- lib/throttle_machines/async_limiter.rb
+- lib/throttle_machines/async_support.rb
+- lib/throttle_machines/control.rb
+- lib/throttle_machines/controller_helpers.rb
+- lib/throttle_machines/dependency_error.rb
+- lib/throttle_machines/engine.rb
+- lib/throttle_machines/hedged_breaker.rb
+- lib/throttle_machines/hedged_request.rb
+- lib/throttle_machines/instrumentation.rb
+- lib/throttle_machines/limiter.rb
+- lib/throttle_machines/middleware.rb
+- lib/throttle_machines/native_speedup.rb
+- lib/throttle_machines/rack_middleware.rb
+- lib/throttle_machines/rack_middleware/allow2_ban.rb
+- lib/throttle_machines/rack_middleware/ban_filter.rb
+- lib/throttle_machines/rack_middleware/blocklist.rb
+- lib/throttle_machines/rack_middleware/configuration.rb
+- lib/throttle_machines/rack_middleware/fail2_ban.rb
+- lib/throttle_machines/rack_middleware/list_filter.rb
+- lib/throttle_machines/rack_middleware/request.rb
+- lib/throttle_machines/rack_middleware/safelist.rb
+- lib/throttle_machines/rack_middleware/throttle.rb
+- lib/throttle_machines/rack_middleware/track.rb
+- lib/throttle_machines/storage/base.rb
+- lib/throttle_machines/storage/memory.rb
+- lib/throttle_machines/storage/null.rb
+- lib/throttle_machines/storage/redis.rb
+- lib/throttle_machines/storage/redis/gcra.lua
+- lib/throttle_machines/storage/redis/increment_counter.lua
+- lib/throttle_machines/storage/redis/peek_gcra.lua
+- lib/throttle_machines/storage/redis/peek_token_bucket.lua
+- lib/throttle_machines/storage/redis/token_bucket.lua
+- lib/throttle_machines/throttled_error.rb
+- lib/throttle_machines/version.rb
+- lib/throttle_machines_native/throttle_machines_native.so
+homepage: https://github.com/seuros/throttle_machines
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/seuros/throttle_machines
+  source_code_uri: https://github.com/seuros/throttle_machines
+  changelog_uri: https://github.com/seuros/throttle_machines/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  cargo_crate_name: throttle_machines_native
+  cargo_manifest_path: ext/throttle_machines_native/ffi/Cargo.toml
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Advanced Rate limiting for Ruby applications
+test_files: []