attio 0.3.0 → 0.5.0

data/lib/attio/circuit_breaker.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module Attio
+  # Circuit breaker pattern for fault tolerance
+  #
+  # @example Basic usage
+  #   breaker = CircuitBreaker.new(
+  #     threshold: 5,
+  #     timeout: 60,
+  #     half_open_requests: 3
+  #   )
+  #
+  #   breaker.call do
+  #     # API call that might fail
+  #     client.records.list
+  #   end
+  class CircuitBreaker
+    class OpenCircuitError < StandardError; end
+
+    # Circuit states
+    CLOSED = :closed
+    OPEN = :open
+    HALF_OPEN = :half_open
+
+    attr_reader :state, :failure_count, :success_count, :last_failure_time
+    attr_accessor :on_state_change
+
+    # Initialize circuit breaker
+    #
+    # @param threshold [Integer] Number of failures before opening circuit
+    # @param timeout [Integer] Seconds before attempting to close circuit
+    # @param half_open_requests [Integer] Successful requests needed to close circuit
+    # @param exceptions [Array<Class>] Exception classes to catch
+    def initialize(
+      threshold: 5,
+      timeout: 60,
+      half_open_requests: 3,
+      exceptions: [StandardError]
+    )
+      @threshold = threshold
+      @timeout = timeout
+      @half_open_requests = half_open_requests
+      @exceptions = exceptions
+
+      @state = CLOSED
+      @failure_count = 0
+      @success_count = 0
+      @last_failure_time = nil
+      @half_open_successes = 0
+
+      @mutex = Mutex.new
+      @on_state_change = nil
+
+      # Statistics
+      @stats = {
+        requests: 0,
+        failures: 0,
+        successes: 0,
+        rejections: 0,
+        state_changes: 0,
+      }
+    end
+
+    # Execute a block with circuit breaker protection
+    #
+    # @yield Block to execute
+    # @return Result of the block
+    # @raise [OpenCircuitError] if circuit is open
+    def call
+      @mutex.synchronize do
+        @stats[:requests] += 1
+
+        case @state
+        when OPEN
+          if can_attempt_reset?
+            transition_to(HALF_OPEN)
+          else
+            @stats[:rejections] += 1
+            raise OpenCircuitError, "Circuit breaker is open (#{time_until_retry}s until retry)"
+          end
+        when HALF_OPEN
+          # Allow limited requests through
+          if @half_open_successes >= @half_open_requests
+            # Already proven stable, close the circuit
+            transition_to(CLOSED)
+          end
+        end
+      end
+
+      # Execute the block outside the mutex
+      begin
+        result = yield
+        record_success
+        result
+      rescue *@exceptions => e
+        record_failure
+        raise e
+      end
+    end
+
+    # Manually trip the circuit breaker
+    def trip!
+      @mutex.synchronize do
+        transition_to(OPEN)
+      end
+    end
+
+    # Manually reset the circuit breaker
+    def reset!
+      @mutex.synchronize do
+        @failure_count = 0
+        @success_count = 0
+        @half_open_successes = 0
+        @last_failure_time = nil
+        transition_to(CLOSED)
+      end
+    end
+
+    # Check if circuit allows requests
+    #
+    # @return [Boolean] True if requests are allowed
+    def allow_request?
+      @state != OPEN || can_attempt_reset?
+    end
+
+    # Get circuit breaker statistics
+    #
+    # @return [Hash] Statistics
+    def stats
+      @mutex.synchronize do
+        @stats.merge(
+          state: @state,
+          failure_count: @failure_count,
+          success_count: @success_count,
+          threshold: @threshold,
+          time_until_retry: @state == OPEN ? time_until_retry : nil
+        )
+      end
+    end
+
+    # Time remaining until circuit can attempt reset
+    #
+    # @return [Integer] Seconds until retry, 0 if ready
+    def time_until_retry
+      return 0 unless @state == OPEN
+      return 0 unless @last_failure_time
+
+      elapsed = Time.now - @last_failure_time
+      remaining = @timeout - elapsed
+      remaining > 0 ? remaining.to_i : 0
+    end
+
+    private def record_success
+      @mutex.synchronize do
+        @stats[:successes] += 1
+        @success_count += 1
+
+        case @state
+        when HALF_OPEN
+          @half_open_successes += 1
+          if @half_open_successes >= @half_open_requests
+            # Circuit has proven stable
+            transition_to(CLOSED)
+          end
+        when CLOSED
+          # Reset failure count on success
+          @failure_count = 0
+        end
+      end
+    end
+
+    private def record_failure
+      @mutex.synchronize do
+        @stats[:failures] += 1
+        @failure_count += 1
+        @last_failure_time = Time.now
+
+        case @state
+        when CLOSED
+          transition_to(OPEN) if @failure_count >= @threshold
+        when HALF_OPEN
+          # Single failure in half-open state reopens circuit
+          transition_to(OPEN)
+        end
+      end
+    end
+
+    private def can_attempt_reset?
+      return false unless @last_failure_time
+
+      Time.now - @last_failure_time >= @timeout
+    end
+
+    private def transition_to(new_state)
+      return if @state == new_state
+
+      old_state = @state
+      @state = new_state
+      @stats[:state_changes] += 1
+
+      # Reset counters for new state
+      case new_state
+      when CLOSED
+        @failure_count = 0
+        @half_open_successes = 0
+      when HALF_OPEN
+        @half_open_successes = 0
+      end
+
+      # Notify state change
+      @on_state_change&.call(old_state, new_state)
+    end
+  end
+
+  # Wrapper for circuit breaker protected HTTP client
+  class CircuitBreakerClient
+    def initialize(client, circuit_breaker)
+      @client = client
+      @circuit_breaker = circuit_breaker
+    end
+
+    def get(path, params = nil)
+      @circuit_breaker.call { @client.get(path, params) }
+    end
+
+    def post(path, body = {})
+      @circuit_breaker.call { @client.post(path, body) }
+    end
+
+    def patch(path, body = {})
+      @circuit_breaker.call { @client.patch(path, body) }
+    end
+
+    def put(path, body = {})
+      @circuit_breaker.call { @client.put(path, body) }
+    end
+
+    def delete(path, body = nil)
+      @circuit_breaker.call { @client.delete(path, body) }
+    end
+  end
+
+  # Composite circuit breaker for multiple endpoints
+  class CompositeCircuitBreaker
+    def initialize(default_config = {})
+      @breakers = {}
+      @default_config = {
+        threshold: 5,
+        timeout: 60,
+        half_open_requests: 3,
+      }.merge(default_config)
+      @mutex = Mutex.new
+    end
+
+    # Get or create circuit breaker for endpoint
+    #
+    # @param key [String] Endpoint key
+    # @param config [Hash] Optional config overrides
+    # @return [CircuitBreaker] Circuit breaker for endpoint
+    def for_endpoint(key, config = {})
+      @mutex.synchronize do
+        @breakers[key] ||= CircuitBreaker.new(**@default_config, **config)
+      end
+    end
+
+    # Execute with circuit breaker for endpoint
+    #
+    # @param key [String] Endpoint key
+    # @yield Block to execute
+    def call(key, &block)
+      for_endpoint(key).call(&block)
+    end
+
+    # Get all circuit breaker states
+    #
+    # @return [Hash] States by endpoint
+    def states
+      @mutex.synchronize do
+        @breakers.transform_values(&:state)
+      end
+    end
+
+    # Get aggregated statistics
+    #
+    # @return [Hash] Combined statistics
+    def stats
+      @mutex.synchronize do
+        @breakers.transform_values(&:stats)
+      end
+    end
+
+    # Reset all circuit breakers
+    def reset_all!
+      @mutex.synchronize do
+        @breakers.each_value(&:reset!)
+      end
+    end
+  end
+end

data/lib/attio/client.rb

@@ -59,10 +59,20 @@ module Attio
           "Content-Type" => "application/json",
           "User-Agent" => "Attio Ruby Client/#{VERSION}",
         },
-        timeout: timeout
+        timeout: timeout,
+        rate_limiter: rate_limiter
       )
     end
 
+    # Access to the Meta API resource.
+    #
+    # @return [Resources::Meta] Meta resource instance
+    # @example
+    #   info = client.meta.identify
+    def meta
+      @meta ||= Resources::Meta.new(self)
+    end
+
     # Access to the Records API resource.
     #
     # @return [Resources::Records] Records resource instance
@@ -171,15 +181,6 @@ module Attio
       @deals ||= Resources::Deals.new(self)
     end
 
-    # Access to the Meta API resource.
-    #
-    # @return [Resources::Meta] Meta resource instance
-    # @example
-    #   info = client.meta.identify
-    def meta
-      @meta ||= Resources::Meta.new(self)
-    end
-
     # Access to the Bulk Operations API resource.
     #
     # @return [Resources::Bulk] Bulk operations resource instance

data/lib/attio/connection_pool.rb

@@ -1,36 +1,61 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 module Attio
-  # Thread-safe connection pool for managing HTTP connections
-  #
-  # This class provides a pool of connections that can be shared
-  # across threads for improved performance and resource management.
+  # Thread-safe connection pool for high-throughput operations
   #
-  # @example Creating a connection pool
-  #   pool = ConnectionPool.new(size: 10) { HttpClient.new }
+  # @example Basic usage
+  #   pool = ConnectionPool.new(size: 5) do
+  #     Attio::HttpClient.new(base_url: API_URL, headers: headers)
+  #   end
   #
-  # @example Using a connection from the pool
-  #   pool.with_connection do |conn|
-  #     conn.get("/endpoint")
+  #   pool.with do |connection|
+  #     connection.get("records")
   #   end
   class ConnectionPool
-    DEFAULT_POOL_SIZE = 5
-    DEFAULT_TIMEOUT = 5 # seconds to wait for connection
+    class TimeoutError < StandardError; end
+    class PoolShuttingDownError < StandardError; end
+
+    DEFAULT_SIZE = 5
+    DEFAULT_TIMEOUT = 5
+
+    attr_reader :size, :timeout, :available, :allocated
 
-    attr_reader :size, :timeout
+    # Initialize a new connection pool
+    #
+    # @param size [Integer] Maximum number of connections
+    # @param timeout [Integer] Seconds to wait for available connection
+    # @yield Block that creates a new connection
+    def initialize(size: DEFAULT_SIZE, timeout: DEFAULT_TIMEOUT, &block)
+      raise ArgumentError, "Block required to create connections" unless block_given?
 
-    def initialize(size: DEFAULT_POOL_SIZE, timeout: DEFAULT_TIMEOUT, &block)
       @size = size
       @timeout = timeout
-      @available = Queue.new
-      @key = :"#{object_id}_connection"
-      @block = block
+      @create_block = block
+      @available = []
+      @allocated = {}
       @mutex = Mutex.new
+      @resource = ConditionVariable.new
+      @shutting_down = false
+      @created = 0
 
-      size.times { @available << create_connection }
+      # Stats tracking
+      @stats = {
+        requests: 0,
+        timeouts: 0,
+        wait_time: 0,
+        active: 0,
+        created: 0,
+        destroyed: 0,
+      }
     end
 
-    def with_connection
+    # Execute a block with a connection from the pool
+    #
+    # @yield [connection] Block to execute with connection
+    # @return Result of the block
+    def with
       connection = checkout
       begin
         yield connection
@@ -39,43 +64,173 @@ module Attio
       end
     end
 
+    # Check out a connection from the pool
+    #
+    # @return [Object] A connection from the pool
+    # @raise [TimeoutError] if no connection available within timeout
     def checkout
-      deadline = Time.now + timeout
+      start_time = Time.now
+      deadline = start_time + @timeout
 
-      loop do
-        return @available.pop(true) if @available.size.positive?
+      @mutex.synchronize do
+        raise PoolShuttingDownError, "Pool is shutting down" if @shutting_down
+
+        @stats[:requests] += 1
+
+        loop do
+          # Return available connection
+          if (connection = @available.pop)
+            @allocated[Thread.current] = connection
+            @stats[:active] += 1
+            @stats[:wait_time] += (Time.now - start_time)
+            return connection
+          end
 
-        raise TimeoutError, "Couldn't acquire connection within #{timeout} seconds" if Time.now >= deadline
+          # Create new connection if under limit
+          if @created < @size
+            connection = create_connection
+            @allocated[Thread.current] = connection
+            @stats[:active] += 1
+            @stats[:wait_time] += (Time.now - start_time)
+            return connection
+          end
 
-        sleep(0.01)
+          # Wait for available connection
+          remaining = deadline - Time.now
+          if remaining <= 0
+            @stats[:timeouts] += 1
+            raise TimeoutError, "Timed out waiting for connection after #{@timeout}s"
+          end
+
+          @resource.wait(@mutex, remaining)
+        end
       end
-    rescue ThreadError
-      raise TimeoutError, "No connections available"
     end
 
+    # Return a connection to the pool
+    #
+    # @param connection [Object] Connection to return
     def checkin(connection)
       @mutex.synchronize do
-        @available << connection if connection
+        if @allocated[Thread.current] == connection
+          @allocated.delete(Thread.current)
+          @stats[:active] -= 1
+
+          if @shutting_down
+            destroy_connection(connection)
+          else
+            @available.push(connection)
+            @resource.signal
+          end
+        end
       end
     end
 
+    # Shutdown the pool and close all connections
     def shutdown
       @mutex.synchronize do
-        @available.close
-        while (connection = begin
-          @available.pop(true)
-        rescue StandardError
-          nil
-        end)
-          connection.close if connection.respond_to?(:close)
+        @shutting_down = true
+
+        # Close available connections
+        while (connection = @available.pop)
+          destroy_connection(connection)
+        end
+
+        # NOTE: allocated connections will be closed when checked in
+        @resource.broadcast
+      end
+    end
+
+    # Reset the pool by closing all connections
+    def reset!
+      @mutex.synchronize do
+        # Close all available connections
+        while (connection = @available.pop)
+          destroy_connection(connection)
         end
+
+        @created = 0
+        @stats[:created] = 0
+        @stats[:destroyed] = 0
+      end
+    end
+
+    # Get pool statistics
+    #
+    # @return [Hash] Pool statistics
+    def stats
+      @mutex.synchronize do
+        @stats.merge(
+          size: @size,
+          available: @available.size,
+          allocated: @allocated.size,
+          created: @created
+        )
+      end
+    end
+
+    # Current pool utilization (0.0 to 1.0)
+    #
+    # @return [Float] Utilization percentage
+    def utilization
+      @mutex.synchronize do
+        return 0.0 if @size == 0
+
+        @allocated.size.to_f / @size
       end
     end
 
+    # Check if pool is healthy
+    #
+    # @return [Boolean] True if pool is functioning normally
+    def healthy?
+      return false if @shutting_down
+      return true if @stats[:requests] == 0
+
+      @stats[:timeouts] < (@stats[:requests] * 0.01)
+    end
+
     private def create_connection
-      @block.call
+      connection = @create_block.call
+      @created += 1
+      @stats[:created] += 1
+      connection
     end
 
-    class TimeoutError < StandardError; end
+    private def destroy_connection(connection)
+      # Call close if connection responds to it
+      connection.close if connection.respond_to?(:close)
+      @stats[:destroyed] += 1
+    rescue StandardError => e
+      # Log but don't raise on close errors
+      warn "Error closing connection: #{e.message}"
+    end
+  end
+
+  # Wrapper for pooled HTTP connections
+  class PooledHttpClient
+    def initialize(pool)
+      @pool = pool
+    end
+
+    def get(path, params = nil)
+      @pool.with { |conn| conn.get(path, params) }
+    end
+
+    def post(path, body = {})
+      @pool.with { |conn| conn.post(path, body) }
+    end
+
+    def patch(path, body = {})
+      @pool.with { |conn| conn.patch(path, body) }
+    end
+
+    def put(path, body = {})
+      @pool.with { |conn| conn.put(path, body) }
+    end
+
+    def delete(path, body = nil)
+      @pool.with { |conn| conn.delete(path, body) }
+    end
   end
 end