resteze 0.4.0 → 1.0.0

data/lib/resteze/middleware/raise_error.rb

@@ -1,16 +1,48 @@
 module Resteze
   module Middleware
+    # Maps Faraday's errors onto the API module's namespaced hierarchy so a
+    # consumer can `rescue MyApi::Error` and catch everything the client
+    # raises. Every error is a subclass of MyApi::Error; the Faraday error
+    # is kept as `cause`.
     class RaiseError < Faraday::Response::RaiseError
       include Resteze::ApiModule
 
+      CONNECTION_ERRORS = [Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError].freeze
+
+      # Faraday error class => namespaced error type. Order matters: the first
+      # entry the error is_a? wins, so specific classes come before ClientError.
+      STATUS_ERRORS = [
+        [Faraday::ResourceNotFound,    :ResourceNotFound],
+        [Faraday::ConflictError,       :ConflictError],
+        [Faraday::UnprocessableEntityError, :UnprocessableEntityError],
+        [Faraday::UnauthorizedError,   :AuthenticationError],
+        [Faraday::ForbiddenError,      :AuthenticationError],
+        [Faraday::TooManyRequestsError, :RateLimitError],
+        [Faraday::BadRequestError,     :InvalidRequestError],
+        [Faraday::ClientError,         :ApiError],
+        [Faraday::ServerError,         :ApiError]
+      ].freeze
+
+      # Adapter-level failures never reach on_complete, so catch them here.
+      def call(env)
+        super
+      rescue *CONNECTION_ERRORS => e
+        raise api_module::ApiConnectionError.from_faraday(e)
+      end
+
       def on_complete(env)
         super
-      rescue Faraday::ConflictError => e
-        raise api_module::ConflictError, e
-      rescue Faraday::UnprocessableEntityError => e
-        raise api_module::UnprocessableEntityError, e
-      rescue Faraday::ResourceNotFound => e
-        raise api_module::ResourceNotFound, e
+      rescue Faraday::Error => e
+        raise mapped_error(e)
+      end
+
+      private
+
+      def mapped_error(error)
+        _, type = STATUS_ERRORS.find { |faraday_class, _| error.is_a?(faraday_class) }
+        return error unless type
+
+        api_module.const_get(type).from_faraday(error)
       end
     end
   end

data/lib/resteze/rate_limit.rb

@@ -0,0 +1,44 @@
+module Resteze
+  # The value RateLimiter#rate_limit returns: a quota, the calls remaining
+  # and the reset. Strategies build it in `describe`; `from_headers` reads
+  # the common three-header shape, which FixedWindow uses with
+  # `headers: true` and a custom strategy or limiter may use directly.
+  class RateLimit
+    DEFAULT_HEADERS = {
+      limit: "X-RateLimit-Limit",
+      remaining: "X-RateLimit-Remaining",
+      reset: "X-RateLimit-Reset"
+    }.freeze
+
+    attr_reader :limit, :remaining, :reset
+
+    # Returns nil when none of the named headers are present. Values that are
+    # not integers are left nil; `reset` is kept as the API sent it (an epoch
+    # or a number of seconds, depending on the API).
+    def self.from_headers(headers, names = nil)
+      names  = DEFAULT_HEADERS.merge(names || {})
+      values = names.transform_values { |name| header_value(headers, name) }
+      return if values.values.all?(&:nil?)
+
+      new(**values.transform_values { |value| Integer(value.to_s, exception: false) })
+    end
+
+    def self.header_value(headers, name)
+      (headers || {}).find { |key, _| key.to_s.casecmp?(name) }&.last
+    end
+
+    def initialize(limit: nil, remaining: nil, reset: nil)
+      @limit     = limit
+      @remaining = remaining
+      @reset     = reset
+    end
+
+    def exhausted?
+      !remaining.nil? && remaining.zero?
+    end
+
+    def to_h
+      { limit:, remaining:, reset: }
+    end
+  end
+end

data/lib/resteze/rate_limiter/fixed_window.rb

@@ -0,0 +1,107 @@
+module Resteze
+  class RateLimiter
+    # At most `limit` requests per `window` seconds, counted in consecutive
+    # windows aligned to the first request. When a window is spent, the next
+    # request waits for the next window.
+    #
+    # With `headers: true` the budget and window follow the API's own
+    # X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers
+    # as responses come back, so the local view matches the server's even
+    # across processes sharing one key. Pass a Hash to name other headers.
+    # `reset: :epoch` (the default) reads the reset header as a time;
+    # `reset: :seconds` reads it as a countdown. `limit:` may be omitted when
+    # the API sends it, or even when it sends only the remaining count.
+    #
+    # Syncing is conservative: within a window the local remaining count and
+    # the server's are both honoured by taking the lower, since requests
+    # admitted locally after the server answered are not in its number yet.
+    # A reset later than the local window's end starts a fresh window.
+    class FixedWindow < Strategy
+      attr_reader :limit, :window, :headers, :reset_format
+
+      def initialize(window:, limit: nil, headers: false, reset: :epoch)
+        super()
+        @limit        = limit && Strategy.integer!(:limit, limit)
+        @window       = Strategy.number!(:window, window)
+        @headers      = headers == true ? {} : headers
+        @reset_format = reset
+        raise ArgumentError, "limit: is required unless headers: syncs it from the API" if @limit.nil? && !@headers
+        raise ArgumentError, "reset: must be :epoch or :seconds" unless %i[epoch seconds].include?(reset)
+      end
+
+      def acquire(state, now)
+        roll_window(state, now)
+        remaining = state[:remaining]
+        return 0 if remaining.nil? # no budget known yet
+        return state[:window_started] + window - now if remaining <= 0
+
+        state[:remaining] = remaining - 1
+        0
+      end
+
+      def observe(state, response, now)
+        return unless headers
+
+        reported = RateLimit.from_headers(response.http_headers, headers)
+        return unless reported
+
+        roll_window(state, now)
+        state[:limit] = reported.limit || state[:limit] || limit
+        sync_window(state, reported, now)
+        sync_remaining(state, reported)
+      end
+
+      def describe(state, now)
+        roll_window(state, now)
+        remaining = state[:remaining] && [state[:remaining], 0].max
+        RateLimit.new(limit: state[:limit], remaining:, reset: state[:window_started] + window)
+      end
+
+      private
+
+      # Starts the first window at `now`; afterwards advances by whole
+      # windows so they stay aligned to that first request.
+      def roll_window(state, now)
+        started = state[:window_started]
+        return if started && now < started + window
+
+        state[:window_started] = started ? aligned_start(started, now) : now
+        state[:limit]        ||= limit
+        state[:remaining]      = state[:limit]
+      end
+
+      def aligned_start(started, now)
+        started + (((now - started) / window).floor * window)
+      end
+
+      # Aligns the local window to the server's reset. A reset beyond the
+      # current window means the server has moved on: start fresh.
+      def sync_window(state, reported, now)
+        reset_at = trusted_reset(reported.reset, now)
+        return unless reset_at
+
+        fresh = reset_at > state[:window_started] + window + 1e-6
+        state[:window_started] = reset_at - window
+        state[:remaining]      = state[:limit] if fresh
+      end
+
+      # Resets that are non-finite or further than one window away are not
+      # trusted; the latter is clamped to one window from now.
+      def trusted_reset(reset, now)
+        return unless reset
+
+        reset_at = reset_format == :seconds ? now + reset : reset.to_f
+        return unless reset_at.finite?
+
+        [reset_at, now + window].min
+      end
+
+      def sync_remaining(state, reported)
+        return unless reported.remaining
+
+        local = state[:remaining]
+        state[:remaining] = local.nil? ? reported.remaining : [local, reported.remaining].min
+      end
+    end
+  end
+end

data/lib/resteze/rate_limiter/leaky_bucket.rb

@@ -0,0 +1,40 @@
+module Resteze
+  class RateLimiter
+    # A bucket that holds up to `capacity` requests and drains at `leak_rate`
+    # requests per second. Each request adds one unit; a full bucket waits
+    # for enough to drain. Unlike a token bucket it smooths bursts into a
+    # steady rate rather than allowing them.
+    class LeakyBucket < Strategy
+      attr_reader :capacity, :leak_rate
+
+      def initialize(capacity:, leak_rate:)
+        super()
+        @capacity  = Strategy.number!(:capacity, capacity)
+        @leak_rate = Strategy.number!(:leak_rate, leak_rate)
+      end
+
+      def acquire(state, now)
+        level = drain(state, now)
+        return (level + 1 - capacity) / leak_rate if level + 1 > capacity
+
+        state[:level] = level + 1
+        0
+      end
+
+      def describe(state, now)
+        level = drain(state, now)
+        RateLimit.new(limit: capacity.to_i, remaining: (capacity - level).floor,
+                      reset: level.positive? ? now + (level / leak_rate) : nil)
+      end
+
+      private
+
+      def drain(state, now)
+        last  = state[:leaked_at] || now
+        level = [0.0, state.fetch(:level, 0.0) - ((now - last) * leak_rate)].max
+        state[:leaked_at] = now
+        state[:level]     = level
+      end
+    end
+  end
+end

data/lib/resteze/rate_limiter/sliding_window.rb

@@ -0,0 +1,37 @@
+module Resteze
+  class RateLimiter
+    # At most `limit` requests in any trailing `window` seconds. Exact: it
+    # keeps the time of each admitted request until it ages out, so memory
+    # is bounded by `limit`.
+    class SlidingWindow < Strategy
+      attr_reader :limit, :window
+
+      def initialize(limit:, window:)
+        super()
+        @limit  = Strategy.integer!(:limit, limit)
+        @window = Strategy.number!(:window, window)
+      end
+
+      def acquire(state, now)
+        times = expire(state, now)
+        return times.first + window - now if times.size >= limit
+
+        times << now
+        0
+      end
+
+      def describe(state, now)
+        times = expire(state, now)
+        RateLimit.new(limit:, remaining: limit - times.size, reset: times.first && (times.first + window))
+      end
+
+      private
+
+      def expire(state, now)
+        times = (state[:times] ||= [])
+        times.shift while times.first && times.first <= now - window
+        times
+      end
+    end
+  end
+end

data/lib/resteze/rate_limiter/strategy.rb

@@ -0,0 +1,58 @@
+module Resteze
+  class RateLimiter
+    # A rate-limiting algorithm. Strategies are stateless objects: all
+    # bookkeeping goes in the `state` hash the limiter hands them, already
+    # under the limiter's lock. Times are Floats of seconds since the epoch.
+    #
+    # To add one, subclass this, implement `acquire`, and pass the class to
+    # `strategy` instead of a name.
+    class Strategy
+      BUILT_IN = {
+        fixed_window: "Resteze::RateLimiter::FixedWindow",
+        sliding_window: "Resteze::RateLimiter::SlidingWindow",
+        token_bucket: "Resteze::RateLimiter::TokenBucket",
+        leaky_bucket: "Resteze::RateLimiter::LeakyBucket"
+      }.freeze
+
+      def self.lookup(name)
+        class_name = BUILT_IN[name.to_sym] or
+          raise ArgumentError, "unknown rate-limit strategy #{name.inspect}; known: #{BUILT_IN.keys.join(', ')}"
+
+        class_name.constantize
+      end
+
+      # Coerces a count option to a positive Integer, so a String from the
+      # environment is caught at configuration time rather than on the first
+      # comparison.
+      def self.integer!(name, value)
+        positive!(name, Integer(value, exception: false), value)
+      end
+
+      # Coerces a rate, capacity or duration option to a positive Float.
+      def self.number!(name, value)
+        positive!(name, Float(value, exception: false), value)
+      end
+
+      def self.positive!(name, coerced, original = coerced)
+        return coerced if coerced&.positive? && (!coerced.is_a?(Float) || coerced.finite?)
+
+        raise ArgumentError, "#{name} must be a positive number, got #{original.inspect}"
+      end
+
+      # Admit one request now and return 0, or return the seconds until one
+      # could be admitted, having recorded nothing.
+      def acquire(_state, _now)
+        0
+      end
+
+      # Learn from a Response or Error the API sent back. Most algorithms
+      # have nothing to learn; FixedWindow syncs with the API's headers.
+      def observe(state, response, now); end
+
+      # The strategy's current view as a Resteze::RateLimit, for `rate_limit`.
+      def describe(_state, _now)
+        nil
+      end
+    end
+  end
+end

data/lib/resteze/rate_limiter/token_bucket.rb

@@ -0,0 +1,39 @@
+module Resteze
+  class RateLimiter
+    # A bucket of `capacity` tokens refilled at `refill_rate` tokens per
+    # second. Each request takes one token; an empty bucket waits for the
+    # next refill. Allows bursts up to `capacity` after a quiet period.
+    class TokenBucket < Strategy
+      attr_reader :capacity, :refill_rate
+
+      def initialize(capacity:, refill_rate:)
+        super()
+        @capacity    = Strategy.number!(:capacity, capacity)
+        @refill_rate = Strategy.number!(:refill_rate, refill_rate)
+      end
+
+      def acquire(state, now)
+        tokens = refill(state, now)
+        return (1 - tokens) / refill_rate if tokens < 1
+
+        state[:tokens] = tokens - 1
+        0
+      end
+
+      def describe(state, now)
+        tokens = refill(state, now)
+        RateLimit.new(limit: capacity.to_i, remaining: tokens.floor,
+                      reset: tokens < 1 ? now + ((1 - tokens) / refill_rate) : nil)
+      end
+
+      private
+
+      def refill(state, now)
+        last   = state[:refilled_at] || now
+        tokens = [capacity, state.fetch(:tokens, capacity) + ((now - last) * refill_rate)].min
+        state[:refilled_at] = now
+        state[:tokens]      = tokens
+      end
+    end
+  end
+end

data/lib/resteze/rate_limiter.rb

@@ -0,0 +1,229 @@
+require "resteze/synchronized_state"
+
+module Resteze
+  # The interface through which a client describes, and responds to, its
+  # API's rate limiting. Resteze assumes nothing about the mechanics: every
+  # method here is a no-op until a strategy is chosen or a method overridden,
+  # and `include Resteze` gives each API module its own MyApi::RateLimiter
+  # subclass to fill in. One instance per module, shared by every thread, is
+  # reached as MyApi.rate_limiter.
+  #
+  # The client calls, for every request:
+  #
+  #   before_request(method, path, params:, headers:)
+  #     Before sending. With a strategy, waits until the request fits the
+  #     budget. Override to throttle differently, or raise to refuse.
+  #   track(response_or_error)
+  #     After every Response and every MyApi::Error. With a strategy, lets
+  #     it learn from what the API reported.
+  #   retry?(error, attempt)
+  #     After a MyApi::RateLimitError. Return true to retry; `attempt`
+  #     counts failed attempts so far, starting at 1. Default false.
+  #   retry_after(error)
+  #     Seconds to wait before that retry. Default: the error's Retry-After.
+  #
+  # and whenever something reads `rate_limit` on a Response or an Error:
+  #
+  #   rate_limit(response_or_error)
+  #     Whatever describes the limit. With a strategy, a Resteze::RateLimit
+  #     of the strategy's current view; otherwise nil.
+  #
+  # Both a Response and a MyApi::Error answer http_status, http_headers and
+  # http_body; a Response has the parsed body in `data`, an Error in `json_body`.
+  #
+  # The four common algorithms are built in and chosen with `strategy`:
+  #
+  #   module MyApi
+  #     class RateLimiter
+  #       strategy :fixed_window, limit: 250_000, window: 3600, headers: true
+  #     end
+  #   end
+  #
+  #   strategy :fixed_window,   limit: 100, window: 60            # N per clock window
+  #   strategy :sliding_window, limit: 100, window: 60            # N per trailing window
+  #   strategy :token_bucket,   capacity: 100, refill_rate: 10    # bursts, refilled per second
+  #   strategy :leaky_bucket,   capacity: 100, leak_rate: 10      # smoothed, drained per second
+  #
+  # `headers: true` on a fixed window syncs the local budget and window with
+  # the API's X-RateLimit-* headers (or `headers: { remaining: "...", ... }`
+  # for other names). Two further options apply to any strategy:
+  #
+  #   on_wait:  :sleep (default) waits in the calling thread; :raise raises
+  #             MyApi::RateLimitError with the wait in retry_after instead,
+  #             for callers such as background jobs that reschedule.
+  #   max_wait: the longest wait honoured, in seconds (default 3600). Any
+  #             longer, non-finite or absurd wait, such as one computed from
+  #             a bad header, is clamped to it.
+  #
+  # Every wait, whether from a strategy or before a retry, goes through
+  # `wait`, so both options and the injectable sleeper apply everywhere.
+  #
+  # State lives in a mutex-guarded hash so a subclass need not think about
+  # threads: read a deep-copied snapshot with `state`, change it with
+  # `update_state`, or work on the live hash inside `synchronize` for
+  # read-modify-write sequences. Avoid instance variables. Waiting always
+  # happens outside the lock, so one thread's wait never blocks another
+  # thread's bookkeeping.
+  class RateLimiter
+    include Resteze::ApiModule
+    include Resteze::SynchronizedState
+
+    ON_WAIT          = %i[sleep raise].freeze
+    DEFAULT_MAX_WAIT = 3600
+
+    class << self
+      # Chooses the built-in strategy (by name) or a custom Strategy class
+      # that instances of this limiter use, with `on_wait:` and `max_wait:`
+      # for the limiter itself and any other options for the strategy.
+      # Without arguments, returns the [class, options] pair in effect for
+      # this class, inherited from a superclass when it declares none.
+      def strategy(name = nil, **options)
+        return strategy_spec if name.nil? && options.empty?
+        raise ArgumentError, "strategy needs a name or class before its options" if name.nil?
+
+        configure(**options.extract!(:on_wait, :max_wait))
+        @strategy = [name.is_a?(Class) ? name : Strategy.lookup(name), options]
+        nil
+      end
+
+      def configure(on_wait: nil, max_wait: nil)
+        @on_wait  = validate_on_wait(on_wait) if on_wait
+        @max_wait = validate_max_wait(max_wait) if max_wait
+      end
+
+      def strategy_spec
+        @strategy || (superclass.respond_to?(:strategy_spec) ? superclass.strategy_spec : nil)
+      end
+
+      def strategy_instance
+        spec = strategy_spec
+        spec && spec[0].new(**spec[1])
+      end
+
+      def on_wait
+        @on_wait || (superclass.respond_to?(:on_wait) ? superclass.on_wait : :sleep)
+      end
+
+      def max_wait
+        @max_wait || (superclass.respond_to?(:max_wait) ? superclass.max_wait : DEFAULT_MAX_WAIT)
+      end
+
+      def validate_on_wait(value)
+        return value if ON_WAIT.include?(value)
+
+        raise ArgumentError, "on_wait: must be one of #{ON_WAIT.map(&:inspect).join(', ')}, got #{value.inspect}"
+      end
+
+      def validate_max_wait(value)
+        Strategy.number!(:max_wait, value)
+      end
+    end
+
+    attr_reader :strategy, :on_wait, :max_wait
+    attr_writer :api_module
+
+    def initialize(strategy: self.class.strategy_instance, on_wait: self.class.on_wait,
+                   max_wait: self.class.max_wait, clock: nil, sleeper: nil)
+      initialize_state
+      @strategy = strategy
+      @on_wait  = self.class.validate_on_wait(on_wait)
+      @max_wait = self.class.validate_max_wait(max_wait)
+      @clock    = clock   || -> { Time.now.to_f }
+      @sleeper  = sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    # The module this limiter serves. Set by MyApi.rate_limiter= so that a
+    # replacement limiter of any class still raises MyApi's errors.
+    def api_module
+      @api_module || self.class.api_module
+    end
+
+    # Receives (method, path, params:, headers:); the default needs none.
+    def before_request(*, **)
+      throttle if strategy
+    end
+
+    def track(response)
+      return unless strategy
+
+      synchronize { |state| strategy.observe(state, response, now) }
+    end
+
+    def rate_limit(_response)
+      return unless strategy
+
+      synchronize { |state| strategy.describe(state, now) }
+    end
+
+    def retry?(_error, _attempt)
+      false
+    end
+
+    def retry_after(error)
+      error.retry_after
+    end
+
+    # Waits, outside the lock, until the strategy admits one request, and
+    # records it. Returns the total seconds waited.
+    def throttle
+      waited = 0.0
+      loop do
+        seconds = synchronize { |state| strategy.acquire(state, now) }
+        break if seconds <= 0
+
+        waited += wait(seconds, reason: :throttle)
+      end
+      waited
+    end
+
+    # Honours on_wait and max_wait for a wait of `seconds`: sleeps through
+    # the injectable sleeper and returns the seconds slept, or raises
+    # `error` (default: a fresh MyApi::RateLimitError carrying the wait in
+    # retry_after) under on_wait: :raise. Either way it fires a
+    # `rate_limit.wait.<key>` notification whose duration is the time spent
+    # waiting and whose payload says why (`reason`: :throttle or :retry,
+    # `attempt` for a retry, `seconds`, `on_wait`); a raised wait carries the
+    # exception keys ActiveSupport adds.
+    def wait(seconds, error: nil, reason: :throttle, attempt: nil)
+      seconds = clamp(seconds)
+      payload = { api_module: api_module.name, seconds:, reason:, attempt:, on_wait: }.compact
+
+      ActiveSupport::Notifications.instrument("rate_limit.wait.#{instrumentation_key}", payload) do
+        raise(error || wait_error(seconds)) if on_wait == :raise
+
+        @sleeper.call(seconds) if seconds.positive?
+        seconds
+      end
+    end
+
+    private
+
+    def now
+      @clock.call
+    end
+
+    def clamp(seconds)
+      seconds = seconds.to_f
+      return max_wait.to_f unless seconds.finite?
+
+      seconds.clamp(0.0, max_wait.to_f)
+    end
+
+    # The module's INSTRUMENTATION_KEY, or its underscored name for a bare
+    # Resteze::RateLimiter that serves no module.
+    def instrumentation_key
+      mod = api_module
+      mod.const_defined?(:INSTRUMENTATION_KEY, false) ? mod::INSTRUMENTATION_KEY : mod.name.underscore.tr("/", "_")
+    end
+
+    def wait_error(seconds)
+      api_module::RateLimitError.new("rate limit reached; retry in #{seconds.ceil} seconds", retry_after: seconds.ceil)
+    end
+  end
+end
+
+require "resteze/rate_limiter/strategy"
+require "resteze/rate_limiter/fixed_window"
+require "resteze/rate_limiter/sliding_window"
+require "resteze/rate_limiter/token_bucket"
+require "resteze/rate_limiter/leaky_bucket"

data/lib/resteze/rate_limiting.rb

@@ -0,0 +1,30 @@
+module Resteze
+  # Drives the API module's RateLimiter through the request lifecycle (see
+  # Resteze::RateLimiter). Prepended outermost on Client so that each attempt
+  # of a retried request is instrumented and logged on its own. Passes every
+  # keyword through untouched, so a client that accepts more than
+  # `headers:` and `params:` still works.
+  module RateLimiting
+    def execute_request(method, path, **)
+      limiter = api_module.rate_limiter
+      attempt = 0
+      sent    = false
+      begin
+        limiter.before_request(method, path, **)
+        sent = true
+        super.tap { |response| limiter.track(response) }
+      rescue api_module::Error => e
+        # A refusal from before_request never went out, so there is nothing
+        # to track and nothing to retry.
+        raise unless sent
+
+        limiter.track(e)
+        raise unless e.is_a?(api_module::RateLimitError) && limiter.retry?(e, attempt += 1)
+
+        sent = false
+        limiter.wait(limiter.retry_after(e), error: e, reason: :retry, attempt:) # :raise raises the 429 itself
+        retry
+      end
+    end
+  end
+end