async-limiter 1.5.4 → 2.0.0

data/lib/async/limiter/timing/leaky_bucket.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/clock"
+
+module Async
+	module Limiter
+		module Timing
+			# Leaky bucket timing strategy that smooths traffic flow.
+			#
+			# This strategy maintains a "bucket" that gradually "leaks" capacity over time,
+			# enforcing a steady output rate regardless of input bursts.
+			class LeakyBucket
+				# @attribute [Numeric] Leak rate in units per second.
+				attr_reader :rate
+				
+				# @attribute [Numeric] Maximum bucket capacity.
+				attr_reader :capacity
+				
+				# Initialize a leaky bucket timing strategy.
+				# @parameter rate [Numeric] Leak rate in units per second.
+				# @parameter capacity [Numeric] Maximum bucket capacity.
+				# @parameter initial_level [Numeric] Starting bucket level (0 = leaky bucket, capacity = token bucket).
+				def initialize(rate, capacity, initial_level: 0)
+					raise ArgumentError, "rate must be non-negative" unless rate >= 0
+					raise ArgumentError, "capacity must be positive" unless capacity.positive?
+					
+					@rate = rate
+					@capacity = capacity
+					@level = initial_level.to_f
+					@last_leak = Clock.now
+				end
+				
+				# Maximum cost this timing strategy can support.
+				# @returns [Numeric] The maximum cost (equal to capacity).
+				def maximum_cost
+					@capacity
+				end
+				
+				# Check if a task can be acquired with the given cost.
+				# @parameter cost [Numeric] The cost/weight of the operation.
+				# @parameter current_time [Numeric] Current time for leak calculations.
+				# @returns [Boolean] True if bucket has capacity for this cost.
+				def can_acquire?(cost = 1, current_time = Clock.now)
+					leak_bucket(current_time)
+					@level + cost <= @capacity
+				end
+				
+				# Record that a task was acquired (adds cost to bucket level).
+				# @parameter cost [Numeric] The cost/weight of the operation.
+				def acquire(cost = 1)
+					leak_bucket
+					@level += cost
+				end
+				
+				# Wait for bucket to have capacity.
+				# @parameter mutex [Mutex] Mutex to release during sleep.
+				# @parameter deadline [Deadline, nil] Deadline for timeout (nil = wait forever).
+				# @parameter cost [Numeric] Cost of the operation (default: 1).
+				# @returns [Boolean] True if capacity is available, false if timeout exceeded.
+				def wait(mutex, deadline = nil, cost = 1)
+					# Loop until we can acquire or deadline expires:
+					until can_acquire?(cost, Clock.now)
+						# Check deadline before each wait:
+						return false if deadline&.expired?
+						
+						# Calculate how long to wait for bucket to leak enough for this cost:
+						needed_capacity = (@level + cost) - @capacity
+						wait_time = needed_capacity / @rate.to_f
+						
+						# Should be able to acquire now:
+						return true if wait_time <= 0
+						
+						# Check if wait would exceed deadline:
+						remaining = deadline&.remaining
+						if remaining && wait_time > remaining
+							# Would exceed deadline:
+							return false
+						end
+						
+						# Wait for the required time (or remaining time if deadline specified):
+						actual_wait = remaining ? [wait_time, remaining].min : wait_time
+						
+						# Release mutex during sleep:
+						mutex.sleep(actual_wait)
+					end
+					
+					return true
+				end
+				
+				# Get current bucket level (for debugging/monitoring).
+				# @returns [Numeric] Current bucket level.
+				def level
+					leak_bucket
+					@level
+				end
+				
+				# Set bucket level (for testing purposes).
+				# @parameter new_level [Numeric] New bucket level.
+				def level=(new_level)
+					@level = new_level.to_f
+					@last_leak = Clock.now
+				end
+				
+				# Simulate time advancement for testing purposes.
+				# @parameter seconds [Numeric] Number of seconds to advance.
+				def advance_time(seconds)
+					@last_leak -= seconds
+					leak_bucket
+				end
+				
+				# Get current timing strategy statistics.
+				# @returns [Hash] Statistics hash with current state.
+				def statistics
+					leak_bucket
+					
+					{
+						name: "LeakyBucket",
+						current_level: @level,
+						maximum_capacity: @capacity,
+						leak_rate: @rate,
+						available_capacity: @capacity - @level,
+						utilization_percentage: (@level / @capacity) * 100
+					}
+				end
+				
+				private
+				
+				# Leak the bucket based on elapsed time.
+				# @parameter current_time [Numeric] Current time.
+				def leak_bucket(current_time = Clock.now)
+					return if @level <= 0  # Don't leak if already empty or negative
+					
+					elapsed = current_time - @last_leak
+					leaked = elapsed * @rate
+					
+					@level = [@level - leaked, 0.0].max
+					@last_leak = current_time
+				end
+			end
+		end
+	end
+end

data/lib/async/limiter/timing/none.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/clock"
+
+module Async
+	module Limiter
+		# @namespace
+		module Timing
+			# No timing constraints - tasks can execute immediately.
+			#
+			# This strategy provides no time-based limiting, suitable for
+			# pure concurrency control without rate limiting.
+			module None
+				# Maximum cost this timing strategy can support (unlimited for no constraints).
+				# @returns [Float] Infinity since there are no timing constraints.
+				def self.maximum_cost
+					Float::INFINITY
+				end
+				# Check if a task can be acquired (always true for no timing constraints).
+				# @parameter cost [Numeric] Cost of the operation (ignored for no timing constraints).
+				# @returns [Boolean] Always true.
+				def self.can_acquire?(cost = 1)
+					true
+				end
+				
+				# Record that a task was acquired (no-op for this strategy).
+				# @parameter cost [Numeric] Cost of the operation (ignored for no timing constraints).
+				def self.acquire(cost = 1)
+					# No state to update
+				end
+				
+				# Wait for timing constraints to be satisfied (no-op for this strategy).
+				# @parameter mutex [Mutex] Mutex to release during sleep (ignored for no timing constraints).
+				# @parameter deadline [Deadline, nil] Deadline for timeout (ignored for no timing constraints).
+				# @parameter cost [Numeric] Cost of the operation (ignored for no timing constraints).
+				# @returns [Boolean] Always true since there are no timing constraints.
+				def self.wait(mutex, deadline = nil, cost = 1)
+					# No waiting needed - return immediately
+					true
+				end
+				
+				# Get current timing strategy statistics.
+				# @returns [Hash] Statistics hash with current state.
+				def self.statistics
+					{
+						name: "None"
+					}
+				end
+			end
+		end
+	end
+end

data/lib/async/limiter/timing/ordered.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/condition"
+
+module Async
+	module Limiter
+		module Timing
+			# Ordered timing strategy wrapper that preserves FIFO ordering.
+			#
+			# This wrapper delegates to any timing strategy but ensures that tasks
+			# acquire capacity in the order they requested it, preventing starvation
+			# of high-cost operations by continuous low-cost operations.
+			class Ordered
+				# Initialize ordered timing wrapper.
+				# @parameter delegate [#acquire, #wait, #maximum_cost] The timing strategy to wrap.
+				def initialize(delegate)
+					@delegate = delegate
+					@mutex = Mutex.new
+				end
+				
+				# Get maximum cost from delegate strategy.
+				# @returns [Numeric] Maximum supported cost.
+				def maximum_cost
+					@delegate.maximum_cost
+				end
+				
+				# Record acquisition in delegate strategy.
+				# @parameter cost [Numeric] Cost of the operation.
+				def acquire(cost = 1)
+					@delegate.acquire(cost)
+				end
+				
+				# Wait with FIFO ordering preserved.
+				# @parameter mutex [Mutex] Mutex to release during sleep.
+				# @parameter deadline [Deadline, nil] Deadline for timeout.
+				# @parameter cost [Numeric] Cost of the operation.
+				# @returns [Boolean] True if acquired, false if timed out.
+				def wait(mutex, deadline = nil, cost = 1)
+					@mutex.synchronize do
+						@delegate.wait(mutex, deadline, cost)
+					end
+				end
+				
+				# Get current timing strategy statistics from delegate.
+				# @returns [Hash] Statistics hash with current state.
+				def statistics
+					@delegate.statistics.tap do |statistics|
+						statistics[:ordered] = true
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/limiter/timing/sliding_window.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "async/clock"
+require_relative "burst"
+
+module Async
+	module Limiter
+		module Timing
+			# Sliding window timing strategy with rolling time periods.
+			#
+			# This strategy enforces rate limiting with a rolling window that slides continuously,
+			# providing smoother rate limiting than fixed windows.
+			class SlidingWindow
+				# @attribute [Numeric] Maximum tasks allowed per window.
+				attr_reader :limit
+				
+				# @attribute [Numeric] Duration of the timing window in seconds.
+				attr_reader :duration
+				
+				# Initialize a window timing strategy.
+				# @parameter duration [Numeric] Duration of the window in seconds.
+				# @parameter burst [#can_acquire?] Controls bursting vs smooth behavior.
+				# @parameter limit [Integer] Maximum tasks per window.
+				def initialize(duration, burst, limit)
+					raise ArgumentError, "duration must be positive" unless duration.positive?
+					
+					@duration = duration
+					@burst = burst
+					@limit = limit
+					
+					@start_time = nil
+					@count = 0
+					@frame_start_time = nil
+				end
+				
+				# Maximum cost this timing strategy can support.
+				# @returns [Numeric] The maximum cost (equal to limit).
+				def maximum_cost
+					@limit
+				end
+				
+				# Check if a task can be acquired based on window constraints.
+				# @parameter cost [Numeric] The cost/weight of the operation.
+				# @parameter current_time [Numeric] Current time for window calculations.
+				# @returns [Boolean] True if window and frame constraints allow acquisition.
+				def can_acquire?(cost = 1, current_time = Clock.now)
+					# Update window if needed
+					if window_changed?(current_time, @start_time)
+						@start_time = window_start_time(current_time)
+						@count = 0
+					end
+					
+					frame_changed = frame_changed?(current_time)
+					
+					# Check both window and frame constraints with cost
+					@burst.can_acquire?(@count + cost - 1, @limit, frame_changed)
+				end
+				
+				# Record that a task was acquired.
+				# @parameter cost [Numeric] The cost/weight of the operation.
+				def acquire(cost = 1)
+					@count += cost
+					@frame_start_time = Clock.now
+				end
+				
+				# Wait for timing constraints to be satisfied.
+				# Sleeps until the next window or frame becomes available, or returns immediately if ready.
+				# @parameter mutex [Mutex] Mutex to release during sleep.
+				# @parameter deadline [Deadline, nil] Deadline for timeout (nil = wait forever).
+				# @parameter cost [Numeric] Cost of the operation (default: 1).
+				# @returns [Boolean] True if constraints are satisfied, false if timeout exceeded.
+				def wait(mutex, deadline = nil, cost = 1)
+					# Only wait if we can't acquire right now:
+					until can_acquire?(cost, Clock.now)
+						# Handle non-blocking case
+						if deadline&.expired? || (deadline && deadline.remaining == 0)
+							return false
+						end
+						
+						next_time = @burst.next_acquire_time(
+							@start_time,
+							@duration,
+							@frame_start_time,
+							@duration / @limit.to_f
+						)
+						
+						current_time = Clock.now
+						wait_time = next_time - current_time
+						
+						return true if wait_time <= 0
+						
+						# Check if wait would exceed deadline
+						remaining = deadline&.remaining
+						if remaining && wait_time > remaining
+							return false  # Would exceed deadline
+						end
+						
+						# Wait for the required time (or remaining time if deadline specified)
+						actual_wait = remaining ? [wait_time, remaining].min : wait_time
+						
+						mutex.sleep(actual_wait)  # Release mutex during sleep
+					end
+					
+					return true
+				end
+				
+				# Calculate the start time of the current window for the given time.
+				# Default implementation provides sliding window behavior.
+				# @parameter current_time [Numeric] The current time.
+				# @returns [Numeric] The window start time (current time for sliding).
+				def window_start_time(current_time)
+					current_time  # Sliding window: always starts now
+				end
+				
+				# Check if the window has changed since the last window start.
+				# @parameter current_time [Numeric] The current time.
+				# @parameter last_window_start [Numeric] The previous window start time.
+				# @returns [Boolean] True if a new window period has begun.
+				def window_changed?(current_time, last_window_start)
+					return true if last_window_start.nil?
+					last_window_start + @duration <= current_time
+				end
+				
+				# Get current timing strategy statistics.
+				# @returns [Hash] Statistics hash with current state.
+				def statistics
+					{
+						name: "SlidingWindow",
+						window_duration: @duration,
+						window_limit: @limit,
+						current_window_count: @count,
+						window_utilization_percentage: (@count.to_f / @limit) * 100,
+						burst: @burst.statistics,
+					}
+				end
+				
+				private
+				
+				def frame_changed?(current_time)
+					return true if @frame_start_time.nil?
+					
+					frame_duration = @duration / @limit.to_f
+					@frame_start_time + frame_duration <= current_time
+				end
+			end
+		end
+	end
+end

data/lib/async/limiter/token.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Francisco Mejia.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Limiter
+		# Token that represents an acquired resource and can be used to release or re-acquire.
+		#
+		# Tokens provide advanced resource management by encapsulating both the acquired
+		# resource and the acquisition options (timeout, cost, priority, etc.). This enables
+		# re-acquisition with modified parameters while maintaining the original context.
+		#
+		# The token automatically tracks release state using the resource itself as the
+		# state indicator (nil = released, non-nil = acquired).
+		class Token
+			# Acquire a token from a limiter.
+			#
+			# This class method provides a clean way to acquire tokens without
+			# adding token-specific methods to limiter classes.
+			#
+			# @parameter limiter [Generic] The limiter to acquire from.
+			# @parameter options [Hash] Acquisition options (timeout, cost, priority, etc.).
+			# @yields {|token| ...} Optional block executed with automatic token release.
+			#   @parameter token [Token] The acquired token object.
+			# @returns [Token, nil] A token object, or nil if acquisition failed.
+			# @raises [ArgumentError] If cost exceeds the timing strategy's maximum supported cost.
+			# @asynchronous
+			def self.acquire(limiter, **options, &block)
+				resource = limiter.acquire(**options)
+				return nil unless resource
+				
+				token = new(limiter, resource)
+				
+				return token unless block_given?
+				
+				begin
+					yield(token)
+				ensure
+					token.release
+				end
+			end
+			# Initialize a new token.
+			# @parameter limiter [Generic] The limiter that issued this token.
+			# @parameter resource [Object] The acquired resource.
+			def initialize(limiter, resource = nil)
+				@limiter = limiter
+				@resource = resource
+			end
+			
+			# @attribute [Object] The acquired resource (nil if released).
+			attr_reader :resource
+			
+			# Release the token back to the limiter.
+			def release
+				if resource = @resource
+					@resource = nil
+					@limiter.release(resource)
+				end
+			end
+			
+			# Re-acquire the resource with modified options.
+			#
+			# This allows changing acquisition parameters (timeout, cost, priority, etc.)
+			# while maintaining the token context. The current resource is released
+			# and a new one is acquired with the merged options.
+			#
+			# @parameter new_options [Hash] New acquisition options (timeout, cost, priority, etc.).
+			#   These are merged with the original options, with new options taking precedence.
+			# @returns [Token] A new token for the re-acquired resource.
+			# @raises [ArgumentError] If the new cost exceeds timing strategy capacity.
+			# @asynchronous
+			def acquire(**options, &block)
+				raise "Token already acquired!" if @resource
+				
+				@resource = @limiter.acquire(reacquire: true, **options)
+				
+				return @resource unless block_given?
+				
+				begin
+					return yield(@resource)
+				ensure
+					self.release
+				end
+			end
+			
+			# Check if the token has been acquired.
+			# @returns [Boolean] True if the token has been acquired.
+			def acquired?
+				!!@resource
+			end
+			
+			# Check if the token has been released.
+			# @returns [Boolean] True if the token has been released.
+			def released?
+				!@resource
+			end
+		end
+	end
+end

data/lib/async/limiter/version.rb

@@ -1,5 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2021, by Bruno Sutic.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
 module Async
-  module Limiter
-    VERSION = "1.5.4"
-  end
+	module Limiter
+		VERSION = "2.0.0"
+	end
 end

data/lib/async/limiter.rb

@@ -1,10 +1,24 @@
-require_relative "limiter/concurrent"
-require_relative "limiter/unlimited"
-require_relative "limiter/window/continuous"
-require_relative "limiter/window/fixed"
-require_relative "limiter/window/sliding"
+# frozen_string_literal: true
 
+# Released under the MIT License.
+# Copyright, 2020, by Bruno Sutic.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "limiter/timing/none"
+require_relative "limiter/timing/sliding_window"
+require_relative "limiter/timing/fixed_window"
+require_relative "limiter/timing/leaky_bucket"
+require_relative "limiter/timing/burst"
+require_relative "limiter/timing/ordered"
+require_relative "limiter/generic"
+require_relative "limiter/limited"
+require_relative "limiter/token"
+require_relative "limiter/queued"
+
+# @namespace
 module Async
-  module Limiter
-  end
+	# @namespace
+	module Limiter
+	end
 end

data/lib/metrics/provider/async/limiter/generic.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "metrics/provider"
+require "async/clock"
+require_relative "../../../../async/limiter/generic"
+
+# Metrics provider for Async::Limiter::Generic instrumentation.
+# This monkey patches the Generic limiter class to add metrics around
+# acquire and release operations for observability.
+Metrics::Provider(Async::Limiter::Generic) do
+	ACQUIRE_COUNTER = Metrics.metric("async.limiter.acquire", :counter, description: "Number of limiter acquire operations.")
+	ACQUIRE_DURATION = Metrics.metric("async.limiter.acquire.duration", :histogram, description: "Duration of limiter acquire operations.")
+	ACQUIRE_ATTEMPTS = Metrics.metric("async.limiter.acquire.attempts", :counter, description: "Total number of limiter acquire attempts.")
+	RELEASE_COUNTER = Metrics.metric("async.limiter.release", :counter, description: "Number of limiter release operations.")
+	
+	def acquire_synchronized(timeout, cost, **options)
+		# Build base tags and extend with instance tags if present
+		is_reacquire = options[:reacquire] || false
+		tags = ["limiter:#{self.class.name}", "cost:#{cost}", "reacquire:#{is_reacquire}"]
+		tags = Metrics::Tags.normalize(@tags, tags)
+		
+		clock = Async::Clock.start
+		ACQUIRE_ATTEMPTS.emit(1, tags: tags)
+		
+		begin
+			if result = super
+				# Emit success metrics
+				success_tags = Metrics::Tags.normalize(["result:success"], tags)
+				ACQUIRE_COUNTER.emit(1, tags: success_tags)
+				ACQUIRE_DURATION.emit(clock.total, tags: success_tags)
+			else
+				# Emit failure metrics (timeout/contention)
+				failure_tags = Metrics::Tags.normalize(["result:timeout"], tags)
+				ACQUIRE_COUNTER.emit(1, tags: failure_tags)
+				ACQUIRE_DURATION.emit(clock.total, tags: failure_tags)
+			end
+			
+			return result
+		rescue => error
+			# Emit error metrics
+			error_tags = Metrics::Tags.normalize(["result:error", "error:#{error.class.name}"], tags)
+			ACQUIRE_COUNTER.emit(1, tags: error_tags)
+			ACQUIRE_DURATION.emit(clock.total, tags: error_tags)
+			
+			raise
+		end
+	end
+	
+	def release(resource = true)
+		# Build base tags and extend with instance tags if present
+		tags = ["limiter:#{self.class.name}"]
+		tags = Metrics::Tags.normalize(@tags, tags)
+		
+		begin
+			result = super
+			
+			# Emit success metrics
+			success_tags = Metrics::Tags.normalize(["result:success"], tags)
+			RELEASE_COUNTER.emit(1, tags: success_tags)
+			
+			result
+		rescue => error
+			# Emit failure metrics
+			error_tags = Metrics::Tags.normalize(["result:error", "error:#{error.class.name}"], tags)
+			RELEASE_COUNTER.emit(1, tags: error_tags)
+			
+			raise
+		end
+	end
+end

data/lib/metrics/provider/async/limiter.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "limiter/generic"

data/lib/traces/provider/async/limiter/generic.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "traces/provider"
+require_relative "../../../../async/limiter/generic"
+
+# Traces provider for Async::Limiter::Generic instrumentation.
+# This monkey patches the Generic limiter class to add tracing around
+# acquire and release operations for observability.
+Traces::Provider(Async::Limiter::Generic) do
+	def acquire_synchronized(timeout, cost, **options)
+		attributes = {
+			"limiter" => self.class.name,
+			"cost" => cost,
+			"timeout" => timeout,
+			"priority" => options[:priority],
+			"reacquire" => options[:reacquire] || false,
+		}
+		
+		attributes.merge!(@tags) if @tags
+		
+		Traces.trace("async.limiter.acquire", attributes: attributes) do
+			super
+		end
+	end
+	
+	def release(resource = true)
+		attributes = {
+			"limiter.class" => self.class.name,
+		}
+		
+		attributes.merge!(@tags) if @tags
+		
+		Traces.trace("async.limiter.release", attributes: attributes) do
+			super
+		end
+	end
+end

data/lib/traces/provider/async/limiter.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "limiter/generic"