vectra-client 0.3.0 → 0.3.2

data/lib/vectra/credential_rotation.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Vectra
+  # Credential rotation helper for seamless API key updates
+  #
+  # Provides utilities for rotating API keys without downtime by supporting
+  # multiple credentials and gradual migration.
+  #
+  # @example Basic rotation
+  #   rotator = Vectra::CredentialRotator.new(
+  #     primary_key: ENV['PINECONE_API_KEY'],
+  #     secondary_key: ENV['PINECONE_API_KEY_NEW']
+  #   )
+  #
+  #   # Test new key before switching
+  #   if rotator.test_secondary
+  #     rotator.switch_to_secondary
+  #   end
+  #
+  class CredentialRotator
+    attr_reader :primary_key, :secondary_key, :current_key
+
+    # Initialize credential rotator
+    #
+    # @param primary_key [String] Current active API key
+    # @param secondary_key [String, nil] New API key to rotate to
+    # @param provider [Symbol] Provider name
+    # @param test_client [Client, nil] Client instance for testing
+    def initialize(primary_key:, secondary_key: nil, provider: nil, test_client: nil)
+      @primary_key = primary_key
+      @secondary_key = secondary_key
+      @provider = provider
+      @test_client = test_client
+      @current_key = primary_key
+      @rotation_complete = false
+    end
+
+    # Test if secondary key is valid
+    #
+    # @param timeout [Float] Test timeout in seconds
+    # @return [Boolean] true if secondary key works
+    def test_secondary(timeout: 5)
+      return false if secondary_key.nil? || secondary_key.empty?
+
+      client = build_test_client(secondary_key)
+      client.healthy?(timeout: timeout)
+    rescue StandardError
+      false
+    end
+
+    # Switch to secondary key
+    #
+    # @param validate [Boolean] Validate key before switching
+    # @return [Boolean] true if switched successfully
+    # rubocop:disable Naming/PredicateMethod
+    def switch_to_secondary(validate: true)
+      return false if secondary_key.nil? || secondary_key.empty?
+
+      if validate && !test_secondary
+        raise CredentialRotationError, "Secondary key validation failed"
+      end
+
+      @current_key = secondary_key
+      @rotation_complete = true
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+
+    # Rollback to primary key
+    #
+    # @return [void]
+    def rollback
+      @current_key = primary_key
+      @rotation_complete = false
+    end
+
+    # Check if rotation is complete
+    #
+    # @return [Boolean]
+    def rotation_complete?
+      @rotation_complete
+    end
+
+    # Get current active key
+    #
+    # @return [String]
+    def active_key
+      @current_key
+    end
+
+    private
+
+    def build_test_client(key)
+      return @test_client if @test_client
+
+      config = Vectra::Configuration.new
+      config.provider = @provider || Vectra.configuration.provider
+      config.api_key = key
+      config.host = Vectra.configuration.host
+      config.environment = Vectra.configuration.environment
+
+      Vectra::Client.new(
+        provider: config.provider,
+        api_key: key,
+        host: config.host,
+        environment: config.environment
+      )
+    end
+  end
+
+  # Error raised during credential rotation
+  class CredentialRotationError < Vectra::Error; end
+
+  # Credential rotation manager for multiple providers
+  #
+  # @example
+  #   manager = Vectra::CredentialRotationManager.new
+  #
+  #   manager.register(:pinecone,
+  #     primary: ENV['PINECONE_API_KEY'],
+  #     secondary: ENV['PINECONE_API_KEY_NEW']
+  #   )
+  #
+  #   manager.rotate_all
+  #
+  module CredentialRotationManager
+    class << self
+      # Register a credential rotator
+      #
+      # @param provider [Symbol] Provider name
+      # @param primary [String] Primary API key
+      # @param secondary [String, nil] Secondary API key
+      # @return [CredentialRotator]
+      def register(provider, primary:, secondary: nil)
+        rotators[provider] = CredentialRotator.new(
+          primary_key: primary,
+          secondary_key: secondary,
+          provider: provider
+        )
+      end
+
+      # Get rotator for provider
+      #
+      # @param provider [Symbol] Provider name
+      # @return [CredentialRotator, nil]
+      def [](provider)
+        rotators[provider.to_sym]
+      end
+
+      # Test all secondary keys
+      #
+      # @return [Hash<Symbol, Boolean>] Test results
+      def test_all_secondary
+        rotators.transform_values(&:test_secondary)
+      end
+
+      # Rotate all providers
+      #
+      # @param validate [Boolean] Validate before rotating
+      # @return [Hash<Symbol, Boolean>] Rotation results
+      def rotate_all(validate: true)
+        rotators.transform_values { |r| r.switch_to_secondary(validate: validate) }
+      end
+
+      # Rollback all rotations
+      #
+      # @return [void]
+      def rollback_all
+        rotators.each_value(&:rollback)
+      end
+
+      # Get rotation status
+      #
+      # @return [Hash<Symbol, Hash>]
+      def status
+        rotators.transform_values do |r|
+          {
+            rotation_complete: r.rotation_complete?,
+            has_secondary: !r.secondary_key.nil?,
+            active_key: "#{r.active_key[0, 8]}..." # First 8 chars only
+          }
+        end
+      end
+
+      # Clear all rotators
+      #
+      # @return [void]
+      def clear!
+        @rotators = {}
+      end
+
+      private
+
+      def rotators
+        @rotators ||= {}
+      end
+    end
+  end
+end

data/lib/vectra/health_check.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Vectra
+  # Health check functionality for Vectra clients
+  #
+  # Provides health check methods to verify connectivity and status
+  # of vector database providers.
+  #
+  # @example Basic health check
+  #   client = Vectra::Client.new(provider: :pinecone, ...)
+  #   result = client.health_check
+  #   puts result[:healthy]  # => true/false
+  #
+  # @example Detailed health check
+  #   result = client.health_check(
+  #     index: "my-index",
+  #     include_stats: true
+  #   )
+  #
+  module HealthCheck
+    # Perform health check on the provider
+    #
+    # @param index [String, nil] Index to check (uses first available if nil)
+    # @param include_stats [Boolean] Include index statistics
+    # @param timeout [Float] Health check timeout in seconds
+    # @return [HealthCheckResult]
+    def health_check(index: nil, include_stats: false, timeout: 5)
+      start_time = Time.now
+
+      indexes = with_timeout(timeout) { list_indexes }
+      index_name = index || indexes.first&.dig(:name)
+
+      result = base_result(start_time, indexes)
+      add_index_stats(result, index_name, include_stats, timeout)
+      add_pool_stats(result)
+
+      HealthCheckResult.new(**result)
+    rescue StandardError => e
+      failure_result(start_time, e)
+    end
+
+    # Quick health check - just tests connectivity
+    #
+    # @param timeout [Float] Timeout in seconds
+    # @return [Boolean] true if healthy
+    def healthy?(timeout: 5)
+      health_check(timeout: timeout).healthy?
+    end
+
+    private
+
+    def with_timeout(seconds, &)
+      Timeout.timeout(seconds, &)
+    rescue Timeout::Error
+      raise Vectra::TimeoutError, "Health check timed out after #{seconds}s"
+    end
+
+    def base_result(start_time, indexes)
+      {
+        healthy: true,
+        provider: provider_name,
+        latency_ms: latency_since(start_time),
+        indexes_available: indexes.size,
+        checked_at: current_time_iso
+      }
+    end
+
+    def add_index_stats(result, index_name, include_stats, timeout)
+      return unless include_stats && index_name
+
+      stats = with_timeout(timeout) { stats(index: index_name) }
+      result[:index] = index_name
+      result[:stats] = {
+        vector_count: stats[:total_vector_count],
+        dimension: stats[:dimension]
+      }.compact
+    end
+
+    def add_pool_stats(result)
+      return unless provider.respond_to?(:pool_stats)
+
+      pool = provider.pool_stats
+      result[:pool] = pool unless pool[:status] == "not_initialized"
+    end
+
+    def failure_result(start_time, error)
+      HealthCheckResult.new(
+        healthy: false,
+        provider: provider_name,
+        latency_ms: latency_since(start_time),
+        error: error.class.name,
+        error_message: error.message,
+        checked_at: current_time_iso
+      )
+    end
+
+    def latency_since(start_time)
+      ((Time.now - start_time) * 1000).round(2)
+    end
+
+    def current_time_iso
+      Time.now.utc.iso8601
+    end
+  end
+
+  # Health check result object
+  #
+  # @example
+  #   result = client.health_check
+  #   if result.healthy?
+  #     puts "All good! Latency: #{result.latency_ms}ms"
+  #   else
+  #     puts "Error: #{result.error_message}"
+  #   end
+  #
+  class HealthCheckResult
+    attr_reader :provider, :latency_ms, :indexes_available, :checked_at,
+                :index, :stats, :pool, :error, :error_message
+
+    def initialize(healthy:, provider:, latency_ms:, checked_at:,
+                   indexes_available: nil, index: nil, stats: nil,
+                   pool: nil, error: nil, error_message: nil)
+      @healthy = healthy
+      @provider = provider
+      @latency_ms = latency_ms
+      @checked_at = checked_at
+      @indexes_available = indexes_available
+      @index = index
+      @stats = stats
+      @pool = pool
+      @error = error
+      @error_message = error_message
+    end
+
+    # Check if the health check passed
+    #
+    # @return [Boolean]
+    def healthy?
+      @healthy
+    end
+
+    # Check if the health check failed
+    #
+    # @return [Boolean]
+    def unhealthy?
+      !@healthy
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash]
+    def to_h
+      {
+        healthy: @healthy,
+        provider: provider,
+        latency_ms: latency_ms,
+        checked_at: checked_at,
+        indexes_available: indexes_available,
+        index: index,
+        stats: stats,
+        pool: pool,
+        error: error,
+        error_message: error_message
+      }.compact
+    end
+
+    # Convert to JSON
+    #
+    # @return [String]
+    def to_json(*)
+      JSON.generate(to_h)
+    end
+  end
+
+  # Aggregate health checker for multiple providers
+  #
+  # @example
+  #   checker = Vectra::AggregateHealthCheck.new(
+  #     pinecone: pinecone_client,
+  #     qdrant: qdrant_client,
+  #     pgvector: pgvector_client
+  #   )
+  #
+  #   result = checker.check_all
+  #   puts result[:overall_healthy]
+  #
+  class AggregateHealthCheck
+    attr_reader :clients
+
+    # Initialize aggregate health checker
+    #
+    # @param clients [Hash<Symbol, Client>] Named clients to check
+    def initialize(**clients)
+      @clients = clients
+    end
+
+    # Check health of all clients
+    #
+    # @param parallel [Boolean] Run checks in parallel
+    # @param timeout [Float] Timeout per check
+    # @return [Hash] Aggregate results
+    def check_all(parallel: true, timeout: 5)
+      start_time = Time.now
+
+      results = if parallel
+                  check_parallel(timeout)
+                else
+                  check_sequential(timeout)
+                end
+
+      healthy_count = results.count { |_, r| r.healthy? }
+      all_healthy = healthy_count == results.size
+
+      {
+        overall_healthy: all_healthy,
+        healthy_count: healthy_count,
+        total_count: results.size,
+        total_latency_ms: ((Time.now - start_time) * 1000).round(2),
+        checked_at: Time.now.utc.iso8601,
+        results: results.transform_values(&:to_h)
+      }
+    end
+
+    # Check if all providers are healthy
+    #
+    # @return [Boolean]
+    def all_healthy?(timeout: 5)
+      check_all(timeout: timeout)[:overall_healthy]
+    end
+
+    # Check if any provider is healthy
+    #
+    # @return [Boolean]
+    def any_healthy?(timeout: 5)
+      check_all(timeout: timeout)[:healthy_count].positive?
+    end
+
+    private
+
+    def check_parallel(timeout)
+      threads = clients.map do |name, client|
+        Thread.new { [name, client.health_check(timeout: timeout)] }
+      end
+
+      threads.to_h(&:value)
+    end
+
+    def check_sequential(timeout)
+      clients.transform_values { |client| client.health_check(timeout: timeout) }
+    end
+  end
+end

data/lib/vectra/instrumentation/honeybadger.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Instrumentation
+    # Honeybadger error tracking adapter
+    #
+    # Automatically reports Vectra errors to Honeybadger with context.
+    #
+    # @example Enable Honeybadger instrumentation
+    #   # config/initializers/vectra.rb
+    #   require 'vectra/instrumentation/honeybadger'
+    #
+    #   Vectra.configure do |config|
+    #     config.instrumentation = true
+    #   end
+    #
+    #   Vectra::Instrumentation::Honeybadger.setup!
+    #
+    module Honeybadger
+      class << self
+        # Setup Honeybadger instrumentation
+        #
+        # @param notify_on_rate_limit [Boolean] Report rate limit errors (default: false)
+        # @param notify_on_validation [Boolean] Report validation errors (default: false)
+        # @return [void]
+        def setup!(notify_on_rate_limit: false, notify_on_validation: false)
+          @notify_on_rate_limit = notify_on_rate_limit
+          @notify_on_validation = notify_on_validation
+
+          unless defined?(::Honeybadger)
+            warn "Honeybadger gem not found. Install with: gem 'honeybadger'"
+            return
+          end
+
+          Vectra::Instrumentation.on_operation do |event|
+            add_breadcrumb(event)
+            notify_error(event) if should_notify?(event)
+          end
+        end
+
+        private
+
+        # Add breadcrumb for operation tracing
+        def add_breadcrumb(event)
+          ::Honeybadger.add_breadcrumb(
+            "Vectra #{event.operation}",
+            category: "vectra",
+            metadata: {
+              provider: event.provider.to_s,
+              operation: event.operation.to_s,
+              index: event.index,
+              duration_ms: event.duration,
+              success: event.success?,
+              vector_count: event.metadata[:vector_count],
+              result_count: event.metadata[:result_count]
+            }.compact
+          )
+        end
+
+        # Check if error should be reported
+        def should_notify?(event)
+          return false if event.success?
+
+          case event.error
+          when Vectra::RateLimitError
+            @notify_on_rate_limit
+          when Vectra::ValidationError
+            @notify_on_validation
+          else
+            true
+          end
+        end
+
+        # Notify Honeybadger of error
+        def notify_error(event)
+          ::Honeybadger.notify(
+            event.error,
+            context: {
+              vectra: {
+                provider: event.provider.to_s,
+                operation: event.operation.to_s,
+                index: event.index,
+                duration_ms: event.duration,
+                metadata: event.metadata
+              }
+            },
+            tags: build_tags(event),
+            fingerprint: build_fingerprint(event)
+          )
+        end
+
+        # Build tags for error grouping
+        def build_tags(event)
+          [
+            "vectra",
+            "provider:#{event.provider}",
+            "operation:#{event.operation}",
+            error_severity(event.error)
+          ]
+        end
+
+        # Build fingerprint for error grouping
+        def build_fingerprint(event)
+          [
+            "vectra",
+            event.provider.to_s,
+            event.operation.to_s,
+            event.error.class.name
+          ].join("-")
+        end
+
+        # Determine severity tag
+        def error_severity(error)
+          case error
+          when Vectra::AuthenticationError
+            "severity:critical"
+          when Vectra::ServerError
+            "severity:high"
+          when Vectra::RateLimitError
+            "severity:medium"
+          else
+            "severity:low"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vectra/instrumentation/sentry.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Instrumentation
+    # Sentry error tracking adapter
+    #
+    # Automatically reports Vectra errors to Sentry with context.
+    #
+    # @example Enable Sentry instrumentation
+    #   # config/initializers/vectra.rb
+    #   require 'vectra/instrumentation/sentry'
+    #
+    #   Vectra.configure do |config|
+    #     config.instrumentation = true
+    #   end
+    #
+    #   Vectra::Instrumentation::Sentry.setup!
+    #
+    module Sentry
+      class << self
+        # Setup Sentry instrumentation
+        #
+        # @param capture_all_errors [Boolean] Capture all errors, not just failures (default: false)
+        # @param fingerprint_by_operation [Boolean] Group errors by operation (default: true)
+        # @return [void]
+        def setup!(capture_all_errors: false, fingerprint_by_operation: true)
+          @capture_all_errors = capture_all_errors
+          @fingerprint_by_operation = fingerprint_by_operation
+
+          unless defined?(::Sentry)
+            warn "Sentry gem not found. Install with: gem 'sentry-ruby'"
+            return
+          end
+
+          Vectra::Instrumentation.on_operation do |event|
+            record_breadcrumb(event)
+            capture_error(event) if event.failure?
+          end
+        end
+
+        private
+
+        # Add breadcrumb for operation tracing
+        def record_breadcrumb(event)
+          ::Sentry.add_breadcrumb(
+            ::Sentry::Breadcrumb.new(
+              category: "vectra",
+              message: "#{event.operation} on #{event.index}",
+              level: event.success? ? "info" : "error",
+              data: {
+                provider: event.provider.to_s,
+                operation: event.operation.to_s,
+                index: event.index,
+                duration_ms: event.duration,
+                vector_count: event.metadata[:vector_count],
+                result_count: event.metadata[:result_count]
+              }.compact
+            )
+          )
+        end
+
+        # Capture error with context
+        def capture_error(event)
+          ::Sentry.with_scope do |scope|
+            scope.set_tags(
+              vectra_provider: event.provider.to_s,
+              vectra_operation: event.operation.to_s,
+              vectra_index: event.index
+            )
+
+            scope.set_context("vectra", build_context(event))
+
+            # Custom fingerprint to group similar errors
+            if @fingerprint_by_operation
+              scope.set_fingerprint(build_fingerprint(event))
+            end
+
+            # Set error level based on error type
+            scope.set_level(error_level(event.error))
+
+            ::Sentry.capture_exception(event.error)
+          end
+        end
+
+        # Build context hash for Sentry
+        def build_context(event)
+          {
+            provider: event.provider.to_s,
+            operation: event.operation.to_s,
+            index: event.index,
+            duration_ms: event.duration,
+            metadata: event.metadata
+          }
+        end
+
+        # Build fingerprint array for error grouping
+        def build_fingerprint(event)
+          ["vectra", event.provider.to_s, event.operation.to_s, event.error.class.name]
+        end
+
+        # Determine error level based on error type
+        def error_level(error)
+          case error
+          when Vectra::RateLimitError
+            :warning
+          when Vectra::ValidationError
+            :info
+          when Vectra::ServerError, Vectra::ConnectionError, Vectra::TimeoutError
+            :error
+          when Vectra::AuthenticationError
+            :fatal
+          end
+        end
+      end
+    end
+  end
+end