contractful 0.1.0

data/lib/contractful/notifications.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Contractful
+  # Lightweight in-process event notifications.
+  #
+  # The request pipeline posts lifecycle events to this hub so callers can
+  # build metrics, tracing and alerting without touching the transport:
+  #
+  #   Contractful::Notifications.subscribe do |event|
+  #     statsd.increment("http.#{event[:name]}", tags: event[:payload].slice(:method, :url))
+  #   end
+  #
+  # Events posted by the core:
+  #
+  # * <tt>request</tt> — method, url, attempt (1-based)
+  # * <tt>response</tt> — method, url, status, duration_ms (one per attempt
+  #   that produced a response, including suppressed error responses)
+  # * <tt>retry</tt> — method, url, attempt, delay (seconds, post-jitter),
+  #   cause (exception class name or HTTP status Integer)
+  #
+  # Resilience features post their own events on top of these (circuit
+  # breaker state changes, rate-limit sleeps, token refreshes).
+  #
+  # Subscribers must never raise: a failing subscriber is logged via
+  # {Contractful.log} (when set) and skipped, so observability can never
+  # break the request it observes. This module is thread-safe; the
+  # subscriber list is guarded by a mutex and posted payloads are frozen.
+  #
+  # A bridge for ActiveSupport::Notifications ships separately —
+  # <tt>require 'contractful/notifications/active_support'</tt> re-posts
+  # every event as <tt>contractual.<name></tt> ... see that file.
+  module Notifications
+    @mutex = Mutex.new
+    @subscribers = []
+
+    # Cap for #deep_freeze to deny a cycle-driven DoS by stack overflow.
+    # The default of 100 is generous for legitimate notification payloads.
+    DEEP_FREEZE_MAX_DEPTH = 100
+
+    class << self
+      # Subscribe to every event. Returns an unsubscribe Proc; call it to
+      # detach the subscriber.
+      #
+      # @yield [event] every posted event
+      # @yieldparam event [Hash] <tt>{name:, payload:, at:}</tt> where +at+
+      #   is a monotonic timestamp in seconds
+      # @return [Proc] unsubscribe handle
+      def subscribe(&block)
+        raise ArgumentError, 'a block is required' unless block
+
+        @mutex.synchronize { @subscribers << block }
+        -> { unsubscribe(&block) }
+      end
+
+      # Remove a specific subscriber block.
+      def unsubscribe(&block)
+        @mutex.synchronize { @subscribers.delete(block) }
+      end
+
+      # Fan an event out to all subscribers. Internal — the request pipeline
+      # calls this; application code only subscribes. Never raises.
+      #
+      # @param name [String, Symbol] event name
+      # @param payload [Hash] event attributes (deep-frozen so subscribers
+      #   in the same process cannot mutate each other's view of the event)
+      # @return [void]
+      def post(name, **payload)
+        # Deep-freeze the payload: the previous call only froze the
+        # outer Hash, leaving nested String values mutable. A subscriber
+        # could call `event[:payload][:url] << "?evil"` and corrupt the
+        # URL for every other subscriber in the same process. Deep-freeze
+        # via recursion (capped at DEEP_FREEZE_MAX_DEPTH to deny a
+        # DoS-by-cycle) so all String/Array/Hash values are immutable.
+        frozen_payload = deep_freeze(payload.dup)
+        event = { name: name.to_s, payload: frozen_payload,
+                  at: Process.clock_gettime(Process::CLOCK_MONOTONIC) }.freeze
+        listeners = @mutex.synchronize { @subscribers.dup }
+        listeners.each { |listener| notify(listener, event) }
+        nil
+      end
+
+      # Number of attached subscribers (mainly for tests and diagnostics).
+      def subscriber_count
+        @mutex.synchronize { @subscribers.size }
+      end
+
+      # Detach every subscriber (test isolation hook).
+      def clear!
+        @mutex.synchronize { @subscribers.clear }
+        nil
+      end
+
+      private
+
+      # Recursively freeze Hash, Array and String values. Numeric and
+      # Symbol are already frozen by the runtime; Proc and other mutable
+      # objects are left untouched (a Proc that closes over mutable
+      # state stays callable — and freezing it would not stop the closure
+      # from mutating its enclosing scope).
+      def deep_freeze(obj, depth = 0)
+        return obj if obj.frozen?
+
+        guard_deep_freeze_depth(depth)
+        deep_freeze_children(obj, depth)
+        obj.freeze
+      end
+
+      def guard_deep_freeze_depth(depth)
+        return unless depth > DEEP_FREEZE_MAX_DEPTH
+
+        raise ArgumentError,
+              'notification payload nested deeper than ' \
+              "#{DEEP_FREEZE_MAX_DEPTH} levels — refusing to deep-freeze " \
+              '(possible cycle)'
+      end
+
+      def deep_freeze_children(obj, depth)
+        case obj
+        when Hash
+          obj.each_value { |v| deep_freeze(v, depth + 1) }
+        when Array
+          obj.each { |v| deep_freeze(v, depth + 1) }
+        end
+      end
+
+      # Deliver one event to one listener; a raising listener is logged (when
+      # logging is configured) and skipped so observability can never break
+      # the request it observes.
+      def notify(listener, event)
+        listener.call(event)
+      rescue StandardError => e
+        Contractful.log&.<<(
+          "contractful: notification subscriber raised #{e.class}: #{e.message}\n"
+        )
+      end
+    end
+  end
+end

data/lib/contractful/pacer.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Contractful
+  # Raised when the pacing budget would force a wait longer than the
+  # configured `max_wait` — fail loudly instead of sleeping unboundedly.
+  # (Contractful::Exception is itself a RuntimeError; the cop's literal
+  # lint on '< Exception' does not see through the constant.)
+  class PacingTimeout < Exception # rubocop:disable Lint/InheritException
+    # The base Contractful::Exception#initialize takes a response object,
+    # not a message — take the message explicitly.
+    def initialize(message = nil)
+      super()
+      @message = message
+    end
+
+    def retryable?
+      false
+    end
+  end
+
+  # Proactive rate-limit enforcement: a process-wide, thread-safe sliding
+  # window that delays (or refuses) requests so a configured per-host quota
+  # is never exceeded in the first place — instead of eating 429s and
+  # retrying after the fact.
+  #
+  # Opt in per request with `pace: true` (defaults: 600 requests / 60s
+  # window, 30s max wait) or a config Hash:
+  #
+  #   Contractful::Request.execute(
+  #     method: :get, url: 'https://api.example.com/x',
+  #     pace: { limit: 100, window: 60, max_wait: 10 }
+  #   )
+  #
+  # Requests are paced per scheme/host/port across the whole process
+  # (threads included): each attempt — retries included — must acquire a
+  # slot before the request leaves. When the window is full, the request
+  # sleeps until the oldest slot expires (posting a `pace` notification
+  # with the delay); when that wait would exceed `max_wait`, it raises
+  # {PacingTimeout} instead of stalling silently. A sleep in the request
+  # path is exactly what pacing means — callers who cannot tolerate it
+  # should set a small `max_wait`.
+  class Pacer
+    DEFAULT_LIMIT = 600
+    DEFAULT_WINDOW = 60.0
+    DEFAULT_MAX_WAIT = 30.0
+
+    CLOCK = Process::CLOCK_MONOTONIC
+
+    attr_reader :key, :limit, :window, :max_wait
+
+    def initialize(key, limit: DEFAULT_LIMIT, window: DEFAULT_WINDOW, max_wait: DEFAULT_MAX_WAIT)
+      raise ArgumentError, 'limit must be a positive Integer' unless limit.is_a?(Integer) && limit.positive?
+      raise ArgumentError, 'window must be a positive Numeric' unless window.is_a?(Numeric) && window.positive?
+      raise ArgumentError, 'max_wait must be a non-negative Numeric' unless max_wait.is_a?(Numeric) && max_wait >= 0
+
+      @key = key
+      @limit = limit
+      @window = window
+      @max_wait = max_wait
+      @stamps = []
+      @mutex = Mutex.new
+    end
+
+    # Acquire a slot, sleeping (outside the lock) until one frees up. Every
+    # actual wait posts a `pace` notification with the delay.
+    def acquire
+      loop do
+        wait = reserve_slot_or_wait
+        return if wait <= 0
+
+        enforce_max_wait!(wait)
+        Notifications.post('pace', key: @key, delay: wait.round(3),
+                                   limit: @limit, window: @window)
+        sleep(wait)
+      end
+    end
+
+    # Requests recorded inside the current window (diagnostics/tests).
+    def pending
+      @mutex.synchronize do
+        now = Process.clock_gettime(CLOCK)
+        @stamps.reject! { |t| now - t >= @window }
+        @stamps.size
+      end
+    end
+
+    private
+
+    # Under the lock: expire old slots, take one if the budget allows,
+    # otherwise report the wait until the oldest slot expires.
+    def reserve_slot_or_wait
+      @mutex.synchronize do
+        now = Process.clock_gettime(CLOCK)
+        @stamps.reject! { |t| now - t >= @window }
+        if @stamps.size < @limit
+          @stamps << now
+          0.0
+        else
+          @stamps.first + @window - now
+        end
+      end
+    end
+
+    def enforce_max_wait!(wait)
+      return if wait <= @max_wait
+
+      raise PacingTimeout,
+            "pace limit #{@limit}/#{@window}s for #{@key} would wait " \
+            "#{wait.round(1)}s (max_wait #{@max_wait}s)"
+    end
+
+    # Process-wide registry; pacer_for lazily creates one pacer per
+    # scheme/host/port key.
+    #
+    # The previous `||=` form was not atomic: two threads racing on
+    # first use both observed @registry as nil and each built a fresh
+    # Registry — one was discarded, losing track of the pacers it
+    # had created (so the per-origin rate limit diverged per-thread).
+    # Use a Mutex constant to serialize the lazy init. A constant is
+    # used because methods defined inside `class << self` execute with
+    # self = the class, but instance variables assigned inside the
+    # `class << self` block live on the singleton class — the two
+    # scopes do not match.
+    REGISTRY_MUTEX = Mutex.new
+
+    class << self
+      def registry
+        REGISTRY_MUTEX.synchronize { @registry ||= Registry.new }
+      end
+
+      def reset_registry
+        REGISTRY_MUTEX.synchronize { @registry = nil }
+      end
+    end
+
+    # Lazily-materializing pacer store. The first configuration for an
+    # origin wins: later calls for the same scheme/host/port reuse the
+    # existing pacer and ignore their limit/window/max_wait options.
+    class Registry
+      def initialize
+        @pacers = {}
+        @mutex = Mutex.new
+      end
+
+      def pacer_for(uri, limit: DEFAULT_LIMIT, window: DEFAULT_WINDOW, max_wait: DEFAULT_MAX_WAIT)
+        key = "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        @mutex.synchronize do
+          @pacers[key] ||= Pacer.new(key, limit: limit, window: window, max_wait: max_wait)
+        end
+      end
+
+      def clear!
+        @mutex.synchronize { @pacers.clear }
+      end
+
+      def size
+        @mutex.synchronize { @pacers.size }
+      end
+    end
+  end
+end

data/lib/contractful/params_array.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Contractful
+  # The ParamsArray class is used to represent an ordered list of [key, value]
+  # pairs. Use this when you need to include a key multiple times or want
+  # explicit control over parameter ordering.
+  #
+  # Most of the request payload & parameter functions normally accept a Hash of
+  # keys => values, which does not allow for duplicated keys.
+  #
+  # @see Contractful::Utils.encode_query_string
+  # @see Contractful::Utils.flatten_params
+  #
+  class ParamsArray
+    include Enumerable
+
+    # @param array [Array<Array>] An array of parameter key,value pairs. These
+    #   pairs may be 2 element arrays [key, value] or single element hashes
+    #   {key => value}. They may also be single element arrays to represent a
+    #   key with no value.
+    #
+    # @example
+    #   >> ParamsArray.new([[:foo, 123], [:foo, 456], [:bar, 789]])
+    #   This will be encoded as "foo=123&foo=456&bar=789"
+    #
+    # @example
+    #   >> ParamsArray.new({foo: 123, bar: 456})
+    #   This is valid, but there's no reason not to just use the Hash directly
+    #   instead of a ParamsArray.
+    #
+    #
+    def initialize(array)
+      @array = process_input(array)
+    end
+
+    def each(...)
+      @array.each(...)
+    end
+
+    def empty?
+      @array.empty?
+    end
+
+    private
+
+    def process_input(array)
+      array.map { |v| process_pair(v) }
+    end
+
+    # A pair may be:
+    # - A single element hash, e.g. {foo: 'bar'}
+    # - A two element array, e.g. ['foo', 'bar']
+    # - A one element array, e.g. ['foo']
+    #
+    # The recursive `pair.to_a` branch previously could infinite-loop on
+    # an object whose `to_a` returns itself (or another non-Hash/Array),
+    # and crashed on `nil.to_a` (which returns []) because the recursive
+    # call would then raise IndexError on `pair.fetch(0)`. Reject those
+    # inputs up front with a clear error message.
+    def process_pair(pair)
+      case pair
+      when Hash
+        raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}") if pair.length != 1
+
+        pair.to_a.fetch(0)
+      when Array
+        raise ArgumentError.new("Bad # of fields for pair: #{pair.inspect}") if pair.length > 2
+
+        [pair.fetch(0), pair[1]]
+      else
+        # recurse, converting any non-array to an array — but only if
+        # to_a actually returns an Array (to_a on a custom Object can
+        # legitimately return something else, e.g. an Enumerator).
+        coerced = pair.to_a
+        unless coerced.is_a?(Array)
+          raise ArgumentError,
+                'ParamsArray pair must be a Hash, Array, or respond to ' \
+                "to_a with an Array, got #{pair.class}: #{pair.inspect}"
+        end
+
+        process_pair(coerced)
+      end
+    end
+  end
+end