attio 0.2.0 → 0.4.0

data/lib/attio/observability.rb

@@ -0,0 +1,424 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+
+module Attio
+  # Observability and instrumentation for Attio client
+  #
+  # @example Basic usage
+  #   client.instrumentation = Attio::Observability.new(
+  #     logger: Rails.logger,
+  #     metrics_backend: :datadog
+  #   )
+  module Observability
+    # Base instrumentation class
+    class Instrumentation
+      attr_reader :logger, :metrics, :traces
+
+      def initialize(logger: nil, metrics_backend: nil, trace_backend: nil)
+        @logger = logger || Logger.new($stdout)
+        @metrics = Metrics.for(metrics_backend) if metrics_backend
+        @traces = Traces.for(trace_backend) if trace_backend
+        @enabled = true
+      end
+
+      # Record an API call
+      #
+      # @param method [Symbol] HTTP method
+      # @param path [String] API path
+      # @param duration [Float] Call duration in seconds
+      # @param status [Integer] HTTP status code
+      # @param error [Exception] Error if any
+      def record_api_call(method:, path:, duration:, status: nil, error: nil)
+        return unless @enabled
+
+        log_api_call(method, path, duration, status, error)
+        record_api_metrics(method, path, duration, error) if @metrics
+        record_api_trace(method, path, status, error) if @traces
+      end
+
+      # Record rate limit information
+      #
+      # @param remaining [Integer] Requests remaining
+      # @param limit [Integer] Rate limit
+      # @param reset_at [Time] When limit resets
+      def record_rate_limit(remaining:, limit:, reset_at:)
+        return unless @enabled
+
+        utilization = 1.0 - (remaining.to_f / limit)
+
+        @logger.debug(format_log_entry(
+                        event: "rate_limit",
+                        remaining: remaining,
+                        limit: limit,
+                        utilization: utilization.round(3),
+                        reset_in: (reset_at - Time.now).to_i
+                      ))
+
+        @metrics&.gauge("attio.rate_limit.remaining", remaining)
+        @metrics&.gauge("attio.rate_limit.utilization", utilization)
+      end
+
+      # Record cache hit/miss
+      #
+      # @param key [String] Cache key
+      # @param hit [Boolean] Whether it was a hit
+      def record_cache(key:, hit:)
+        return unless @enabled
+
+        @logger.debug(format_log_entry(
+                        event: "cache",
+                        key: key,
+                        hit: hit
+                      ))
+
+        @metrics&.increment("attio.cache.#{hit ? 'hits' : 'misses'}")
+      end
+
+      # Record circuit breaker state change
+      #
+      # @param endpoint [String] Endpoint name
+      # @param old_state [Symbol] Previous state
+      # @param new_state [Symbol] New state
+      def record_circuit_breaker(endpoint:, old_state:, new_state:)
+        return unless @enabled
+
+        @logger.warn(format_log_entry(
+                       event: "circuit_breaker",
+                       endpoint: endpoint,
+                       old_state: old_state,
+                       new_state: new_state
+                     ))
+
+        @metrics&.increment("attio.circuit_breaker.transitions", tags: {
+          from: old_state,
+          to: new_state,
+        })
+      end
+
+      # Record connection pool stats
+      #
+      # @param stats [Hash] Pool statistics
+      def record_pool_stats(stats)
+        return unless @enabled
+
+        @metrics&.gauge("attio.pool.size", stats[:size])
+        @metrics&.gauge("attio.pool.available", stats[:available])
+        @metrics&.gauge("attio.pool.allocated", stats[:allocated])
+        @metrics&.gauge("attio.pool.utilization", stats[:allocated].to_f / stats[:size])
+      end
+
+      # Disable instrumentation
+      def disable!
+        @enabled = false
+      end
+
+      # Enable instrumentation
+      def enable!
+        @enabled = true
+      end
+
+      private def format_log_entry(**fields)
+        fields[:timestamp] = Time.now.iso8601
+        fields[:service] = "attio-ruby"
+        JSON.generate(fields)
+      end
+
+      private def sanitize_path(path)
+        # Remove IDs from paths for metric aggregation
+        path.gsub(%r{/[a-f0-9-]{36}}, "/:id")            # UUIDs
+            .gsub(%r{/[a-zA-Z]+-\d+-[a-zA-Z]+}, "/:id")  # IDs like abc-123-def
+            .gsub(%r{/\d+}, "/:id")                      # Numeric IDs
+      end
+
+      private def log_api_call(method, path, duration, status, error)
+        @logger.info(format_log_entry(
+                       event: "api_call",
+                       method: method,
+                       path: path,
+                       duration_ms: (duration * 1000).round(2),
+                       status: status,
+                       error: error&.class&.name
+                     ))
+      end
+
+      private def record_api_metrics(method, path, duration, error)
+        @metrics.increment("attio.api.calls", tags: { method: method, path: sanitize_path(path) })
+        @metrics.histogram("attio.api.duration", duration * 1000, tags: { method: method })
+
+        return unless error
+
+        @metrics.increment("attio.api.errors", tags: {
+          method: method,
+          error_class: error.class.name,
+        })
+      end
+
+      private def record_api_trace(method, path, status, error)
+        @traces.span("attio.api.call") do |span|
+          span.set_attribute("http.method", method.to_s)
+          span.set_attribute("http.path", path)
+          span.set_attribute("http.status_code", status) if status
+          span.set_attribute("error", true) if error
+        end
+      end
+    end
+
+    # Metrics backends
+    module Metrics
+      def self.for(backend)
+        case backend
+        when :datadog then Datadog.new
+        when :statsd then StatsD.new
+        when :prometheus then Prometheus.new
+        when :memory then Memory.new
+        else
+          raise ArgumentError, "Unknown metrics backend: #{backend}"
+        end
+      end
+
+      # In-memory metrics for testing
+      class Memory
+        attr_reader :counters, :gauges, :histograms
+
+        def initialize
+          @counters = Hash.new(0)
+          @gauges = {}
+          @histograms = Hash.new { |h, k| h[k] = [] }
+        end
+
+        def increment(metric, tags: {})
+          key = tags.empty? ? "#{metric}:" : "#{metric}:#{format_tags(tags)}"
+          @counters[key] += 1
+        end
+
+        def gauge(metric, value, tags: {})
+          key = tags.empty? ? "#{metric}:" : "#{metric}:#{format_tags(tags)}"
+          @gauges[key] = value
+        end
+
+        def histogram(metric, value, tags: {})
+          key = tags.empty? ? "#{metric}:" : "#{metric}:#{format_tags(tags)}"
+          @histograms[key] << value
+        end
+
+        def reset!
+          @counters.clear
+          @gauges.clear
+          @histograms.clear
+        end
+
+        private def format_tags(tags)
+          # Format tags in a consistent way that works across Ruby versions
+          sorted = tags.sort.to_h
+          content = sorted.map { |k, v| ":#{k}=>#{v.inspect}" }.join(", ")
+          "{#{content}}"
+        end
+      end
+
+      # StatsD metrics
+      class StatsD
+        def initialize
+          require "statsd-ruby"
+          @client = ::Statsd.new("localhost", 8125)
+        rescue LoadError
+          raise "Please add 'statsd-ruby' to your Gemfile"
+        end
+
+        def increment(metric, tags: {})
+          @client.increment(metric, tags: format_tags(tags))
+        end
+
+        def gauge(metric, value, tags: {})
+          @client.gauge(metric, value, tags: format_tags(tags))
+        end
+
+        def histogram(metric, value, tags: {})
+          @client.histogram(metric, value, tags: format_tags(tags))
+        end
+
+        private def format_tags(tags)
+          tags.map { |k, v| "#{k}:#{v}" }
+        end
+      end
+
+      # Datadog metrics
+      class Datadog
+        def initialize
+          require "datadog/statsd"
+          @client = ::Datadog::Statsd.new("localhost", 8125)
+        rescue LoadError
+          raise "Please add 'dogstatsd-ruby' to your Gemfile"
+        end
+
+        def increment(metric, tags: {})
+          @client.increment(metric, tags: format_tags(tags))
+        end
+
+        def gauge(metric, value, tags: {})
+          @client.gauge(metric, value, tags: format_tags(tags))
+        end
+
+        def histogram(metric, value, tags: {})
+          @client.histogram(metric, value, tags: format_tags(tags))
+        end
+
+        private def format_tags(tags)
+          tags.map { |k, v| "#{k}:#{v}" }
+        end
+      end
+
+      # Prometheus metrics
+      class Prometheus
+        def initialize
+          require "prometheus/client"
+          @registry = ::Prometheus::Client.registry
+          @counters = {}
+          @gauges = {}
+          @histograms = {}
+        rescue LoadError
+          raise "Please add 'prometheus-client' to your Gemfile"
+        end
+
+        def increment(metric, tags: {})
+          counter = @counters[metric] ||= @registry.counter(
+            metric.to_sym,
+            docstring: "Counter for #{metric}",
+            labels: tags.keys
+          )
+          counter.increment(labels: tags)
+        end
+
+        def gauge(metric, value, tags: {})
+          gauge = @gauges[metric] ||= @registry.gauge(
+            metric.to_sym,
+            docstring: "Gauge for #{metric}",
+            labels: tags.keys
+          )
+          gauge.set(value, labels: tags)
+        end
+
+        def histogram(metric, value, tags: {})
+          histogram = @histograms[metric] ||= @registry.histogram(
+            metric.to_sym,
+            docstring: "Histogram for #{metric}",
+            labels: tags.keys
+          )
+          histogram.observe(value, labels: tags)
+        end
+      end
+    end
+
+    # Tracing backends
+    module Traces
+      def self.for(backend)
+        case backend
+        when :opentelemetry then OpenTelemetry.new
+        when :datadog then DatadogAPM.new
+        when :memory then Memory.new
+        else
+          raise ArgumentError, "Unknown trace backend: #{backend}"
+        end
+      end
+
+      # OpenTelemetry tracing
+      class OpenTelemetry
+        def initialize
+          require "opentelemetry-sdk"
+          @tracer = ::OpenTelemetry.tracer_provider.tracer("attio-ruby")
+        rescue LoadError
+          raise "Please add 'opentelemetry-sdk' to your Gemfile"
+        end
+
+        def span(name, &block)
+          @tracer.in_span(name, &block)
+        end
+      end
+
+      # Datadog APM tracing
+      class DatadogAPM
+        def initialize
+          require "datadog"
+          @tracer = ::Datadog::Tracing
+        rescue LoadError
+          raise "Please add 'datadog' to your Gemfile"
+        end
+
+        def span(name)
+          @tracer.trace(name) do |span|
+            yield(span) if block_given?
+          end
+        end
+      end
+
+      # In-memory tracing for testing
+      class Memory
+        attr_reader :spans
+
+        def initialize
+          @spans = []
+        end
+
+        def span(name)
+          span = Span.new(name)
+          @spans << span
+          yield(span) if block_given?
+          span
+        end
+
+        def reset!
+          @spans.clear
+        end
+
+        class Span
+          attr_reader :name, :attributes
+
+          def initialize(name)
+            @name = name
+            @attributes = {}
+          end
+
+          def set_attribute(key, value)
+            @attributes[key] = value
+          end
+        end
+      end
+    end
+
+    # Middleware for automatic instrumentation
+    class Middleware
+      def initialize(app, instrumentation)
+        @app = app
+        @instrumentation = instrumentation
+      end
+
+      def call(env)
+        start_time = Time.now
+        method = env[:method]
+        path = env[:url].path
+
+        begin
+          response = @app.call(env)
+
+          @instrumentation.record_api_call(
+            method: method,
+            path: path,
+            duration: Time.now - start_time,
+            status: response.status
+          )
+
+          response
+        rescue StandardError => e
+          @instrumentation.record_api_call(
+            method: method,
+            path: path,
+            duration: Time.now - start_time,
+            error: e
+          )
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/attio/rate_limiter.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Attio
+  # Rate limiter with intelligent retry and backoff strategies
+  #
+  # @example Using the rate limiter
+  #   limiter = Attio::RateLimiter.new(
+  #     max_requests: 100,
+  #     window_seconds: 60,
+  #     max_retries: 3
+  #   )
+  #
+  #   limiter.execute { client.records.list }
+  class RateLimiter
+    attr_reader :max_requests, :window_seconds, :max_retries
+    attr_accessor :current_limit, :remaining, :reset_at
+
+    # Initialize a new rate limiter
+    #
+    # @param max_requests [Integer] Maximum requests per window
+    # @param window_seconds [Integer] Time window in seconds
+    # @param max_retries [Integer] Maximum retry attempts
+    # @param enable_jitter [Boolean] Add jitter to backoff delays
+    def initialize(max_requests: 1000, window_seconds: 3600, max_retries: 3, enable_jitter: true)
+      @max_requests = max_requests
+      @window_seconds = window_seconds
+      @max_retries = max_retries
+      @enable_jitter = enable_jitter
+
+      @current_limit = max_requests
+      @remaining = max_requests
+      @reset_at = Time.now + window_seconds
+
+      @mutex = Mutex.new
+      @request_queue = []
+      @request_times = []
+    end
+
+    # Execute a block with rate limiting
+    #
+    # @yield The block to execute
+    # @return The result of the block
+    def execute
+      raise ArgumentError, "Block required" unless block_given?
+
+      @mutex.synchronize do
+        wait_if_needed
+        track_request
+      end
+
+      attempt = 0
+      begin
+        result = yield
+        # Thread-safe header update
+        @mutex.synchronize do
+          update_from_headers(result) if result.is_a?(Hash) && result["_headers"]
+        end
+        result
+      rescue Attio::RateLimitError => e
+        attempt += 1
+        raise e unless attempt <= @max_retries
+
+        wait_time = calculate_backoff(attempt, e)
+        sleep(wait_time)
+        retry
+      end
+    end
+
+    # Check if rate limit is exceeded
+    #
+    # @return [Boolean] True if rate limit would be exceeded
+    def rate_limited?
+      @mutex.synchronize do
+        cleanup_old_requests
+        @request_times.size >= @max_requests
+      end
+    end
+
+    # Get current rate limit status
+    #
+    # @return [Hash] Current status
+    def status
+      @mutex.synchronize do
+        cleanup_old_requests
+        {
+          limit: @current_limit,
+          remaining: [@remaining, @max_requests - @request_times.size].min,
+          reset_at: @reset_at,
+          reset_in: [@reset_at - Time.now, 0].max.to_i,
+          current_usage: @request_times.size,
+        }
+      end
+    end
+
+    # Update rate limit info from response headers
+    # NOTE: This method should be called within a mutex lock
+    #
+    # @param response [Hash] Response containing headers
+    private def update_from_headers(response)
+      return unless response.is_a?(Hash)
+
+      headers = response["_headers"] || {}
+
+      @current_limit = headers["x-ratelimit-limit"].to_i if headers["x-ratelimit-limit"]
+      @remaining = headers["x-ratelimit-remaining"].to_i if headers["x-ratelimit-remaining"]
+      @reset_at = Time.at(headers["x-ratelimit-reset"].to_i) if headers["x-ratelimit-reset"]
+    end
+
+    # Reset the rate limiter
+    def reset!
+      @mutex.synchronize do
+        @request_times.clear
+        @remaining = @max_requests
+        @reset_at = Time.now + @window_seconds
+      end
+    end
+
+    # Queue a request for later execution
+    #
+    # @param priority [Integer] Priority (lower = higher priority)
+    # @yield Block to execute
+    def queue_request(priority: 5, &block)
+      @mutex.synchronize do
+        @request_queue << { priority: priority, block: block, queued_at: Time.now }
+        @request_queue.sort_by! { |r| [r[:priority], r[:queued_at]] }
+      end
+    end
+
+    # Process queued requests
+    #
+    # @param max_per_batch [Integer] Maximum requests to process
+    # @return [Array] Results from processed requests
+    def process_queue(max_per_batch: 10)
+      results = []
+      processed = 0
+
+      while processed < max_per_batch
+        request = @mutex.synchronize { @request_queue.shift }
+        break unless request
+
+        begin
+          result = execute(&request[:block])
+          results << { success: true, result: result }
+        rescue StandardError => e
+          results << { success: false, error: e }
+        end
+
+        processed += 1
+      end
+
+      results
+    end
+
+    private def wait_if_needed
+      cleanup_old_requests
+
+      if @request_times.size >= @max_requests
+        wait_time = @request_times.first + @window_seconds - Time.now
+        if wait_time > 0
+          sleep(wait_time)
+          cleanup_old_requests
+        end
+      end
+
+      return unless @remaining <= 0 && @reset_at > Time.now
+
+      wait_time = @reset_at - Time.now
+      sleep(wait_time) if wait_time > 0
+    end
+
+    private def track_request
+      @request_times << Time.now
+      @remaining = [@remaining - 1, 0].max
+    end
+
+    private def cleanup_old_requests
+      cutoff = Time.now - @window_seconds
+      @request_times.reject! { |time| time < cutoff }
+    end
+
+    private def calculate_backoff(attempt, error = nil)
+      base_wait = 2**attempt
+
+      # Use server-provided retry-after if available
+      base_wait = error.retry_after if error && error.respond_to?(:retry_after) && error.retry_after
+
+      # Add jitter to prevent thundering herd
+      if @enable_jitter
+        jitter = rand * base_wait * 0.1
+        base_wait + jitter
+      else
+        base_wait
+      end
+    end
+  end
+
+  # Middleware for automatic rate limiting
+  class RateLimitMiddleware
+    def initialize(app, rate_limiter)
+      @app = app
+      @rate_limiter = rate_limiter
+    end
+
+    def call(env)
+      @rate_limiter.execute do
+        response = @app.call(env)
+        # Headers are automatically updated within execute block
+        response
+      end
+    end
+  end
+end