vectra-client 1.0.8 → 1.1.0

data/lib/vectra/middleware/response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Response object returned through middleware chain
+    #
+    # @example Success response
+    #   response = Response.new(result: { success: true })
+    #   response.success? # => true
+    #   response.result   # => { success: true }
+    #
+    # @example Error response
+    #   response = Response.new(error: StandardError.new('Failed'))
+    #   response.failure? # => true
+    #   response.error    # => #<StandardError: Failed>
+    #
+    # @example With metadata
+    #   response = Response.new(result: [])
+    #   response.metadata[:duration_ms] = 45
+    #   response.metadata[:cache_hit] = true
+    #
+    class Response
+      attr_accessor :result, :error, :metadata
+
+      # @param result [Object] The successful result
+      # @param error [Exception, nil] The error if failed
+      def initialize(result: nil, error: nil)
+        @result = result
+        @error = error
+        @metadata = {}
+      end
+
+      # Check if the response was successful
+      #
+      # @return [Boolean] true if no error
+      def success?
+        error.nil?
+      end
+
+      # Check if the response failed
+      #
+      # @return [Boolean] true if error present
+      def failure?
+        !success?
+      end
+
+      # Raise error if present
+      #
+      # @raise [Exception] The stored error
+      # @return [void]
+      def raise_if_error!
+        raise error if error
+      end
+
+      # Get the result or raise error
+      #
+      # @return [Object] The result
+      # @raise [Exception] If error present
+      def value!
+        raise_if_error!
+        result
+      end
+    end
+  end
+end

data/lib/vectra/middleware/retry.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Retry middleware for handling transient failures
+    #
+    # Automatically retries failed requests with configurable backoff strategy.
+    #
+    # @example With default settings (3 attempts, exponential backoff)
+    #   Vectra::Client.use Vectra::Middleware::Retry
+    #
+    # @example With custom settings
+    #   Vectra::Client.use Vectra::Middleware::Retry, max_attempts: 5, backoff: :linear
+    #
+    # @example Per-client retry
+    #   client = Vectra::Client.new(
+    #     provider: :pinecone,
+    #     middleware: [[Vectra::Middleware::Retry, { max_attempts: 3 }]]
+    #   )
+    #
+    class Retry < Base
+      # @param max_attempts [Integer] Maximum number of attempts (default: 3)
+      # @param backoff [Symbol, Numeric] Backoff strategy (:exponential, :linear) or fixed delay
+      def initialize(max_attempts: 3, backoff: :exponential)
+        super()
+        @max_attempts = max_attempts
+        @backoff = backoff
+      end
+
+      def call(request, app)
+        attempt = 0
+        last_error = nil
+
+        loop do
+          attempt += 1
+
+          begin
+            response = app.call(request)
+
+            # If successful, return immediately
+            if response.success?
+              response.metadata[:retry_count] = attempt - 1
+              return response
+            end
+
+            # If error is retryable and we haven't exceeded max attempts, retry
+            if response.error && retryable?(response.error) && attempt < @max_attempts
+              sleep(backoff_delay(attempt))
+              next
+            end
+
+            # Error is not retryable or max attempts reached, return response
+            response.metadata[:retry_count] = attempt - 1
+            return response
+          rescue StandardError => e
+            last_error = e
+
+            # If error is retryable and we haven't exceeded max attempts, retry
+            if retryable?(e) && attempt < @max_attempts
+              sleep(backoff_delay(attempt))
+              next
+            end
+
+            # Error is not retryable or max attempts reached, raise
+            raise
+          end
+        end
+      end
+
+      private
+
+      # Check if error is retryable
+      #
+      # @param error [Exception] The error to check
+      # @return [Boolean] true if error is retryable
+      def retryable?(error)
+        error.is_a?(Vectra::RateLimitError) ||
+          error.is_a?(Vectra::ConnectionError) ||
+          error.is_a?(Vectra::TimeoutError) ||
+          error.is_a?(Vectra::ServerError)
+      end
+
+      # Calculate backoff delay
+      #
+      # @param attempt [Integer] Current attempt number
+      # @return [Float] Delay in seconds
+      def backoff_delay(attempt)
+        case @backoff
+        when :exponential
+          # 0.2s, 0.4s, 0.8s, 1.6s, ...
+          (2**(attempt - 1)) * 0.2
+        when :linear
+          # 0.5s, 1.0s, 1.5s, 2.0s, ...
+          attempt * 0.5
+        when Numeric
+          @backoff
+        else
+          1.0
+        end
+      end
+    end
+  end
+end

data/lib/vectra/middleware/stack.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Vectra
+  module Middleware
+    # Middleware stack executor
+    #
+    # Builds and executes a chain of middleware around provider calls.
+    # Similar to Rack middleware, each middleware wraps the next one
+    # in the chain until reaching the actual provider.
+    #
+    # @example Basic usage
+    #   provider = Vectra::Providers::Memory.new
+    #   middlewares = [LoggingMiddleware.new, RetryMiddleware.new]
+    #   stack = Stack.new(provider, middlewares)
+    #
+    #   result = stack.call(:upsert, index: 'test', vectors: [...])
+    #
+    class Stack
+      # @param provider [Vectra::Providers::Base] The actual provider
+      # @param middlewares [Array<Base>] Array of middleware instances
+      def initialize(provider, middlewares = [])
+        @provider = provider
+        @middlewares = middlewares
+      end
+
+      # Execute the middleware stack for an operation
+      #
+      # @param operation [Symbol] The operation to perform (:upsert, :query, etc.)
+      # @param params [Hash] The operation parameters
+      # @return [Object] The result from the provider
+      # @raise [Exception] Any error from middleware or provider
+      def call(operation, **params)
+        request = Request.new(operation: operation, **params)
+
+        # Build middleware chain
+        app = build_chain(request)
+
+        # Execute chain
+        response = app.call(request)
+
+        # Raise if error occurred
+        raise response.error if response.error
+
+        response.result
+      end
+
+      private
+
+      # Build the middleware chain
+      #
+      # @param request [Request] The request object (unused here, but available)
+      # @return [Proc] The complete middleware chain
+      def build_chain(_request)
+        # Final app: actual provider call
+        final_app = lambda do |req|
+          # Remove middleware-specific params before calling provider
+          provider_params = req.to_h.except(:provider)
+          result = @provider.public_send(req.operation, **provider_params)
+          Response.new(result: result)
+        rescue StandardError => e
+          Response.new(error: e)
+        end
+
+        # Wrap with middlewares in reverse order
+        # (last middleware in array is first to execute)
+        @middlewares.reverse.inject(final_app) do |next_app, middleware|
+          lambda do |req|
+            middleware.call(req, next_app)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vectra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectra
-  VERSION = "1.0.8"
+  VERSION = "1.1.0"
 end

data/lib/vectra.rb

@@ -18,6 +18,15 @@ require_relative "vectra/health_check"
 require_relative "vectra/credential_rotation"
 require_relative "vectra/audit_log"
 require_relative "vectra/active_record"
+require_relative "vectra/middleware/request"
+require_relative "vectra/middleware/response"
+require_relative "vectra/middleware/base"
+require_relative "vectra/middleware/stack"
+require_relative "vectra/middleware/logging"
+require_relative "vectra/middleware/retry"
+require_relative "vectra/middleware/instrumentation"
+require_relative "vectra/middleware/pii_redaction"
+require_relative "vectra/middleware/cost_tracker"
 require_relative "vectra/providers/base"
 require_relative "vectra/providers/pinecone"
 require_relative "vectra/providers/qdrant"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vectra-client
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.1.0
 platform: ruby
 authors:
 - Mijo Kristo
@@ -268,6 +268,7 @@ files:
 - docs/guides/faq.md
 - docs/guides/getting-started.md
 - docs/guides/installation.md
+- docs/guides/middleware.md
 - docs/guides/monitoring.md
 - docs/guides/performance.md
 - docs/guides/rails-integration.md
@@ -294,6 +295,7 @@ files:
 - examples/grafana-dashboard.json
 - examples/grafana-setup.md
 - examples/instrumentation_demo.rb
+- examples/middleware_demo.rb
 - examples/prometheus-exporter.rb
 - lib/generators/vectra/index_generator.rb
 - lib/generators/vectra/install_generator.rb
@@ -316,6 +318,15 @@ files:
 - lib/vectra/instrumentation/new_relic.rb
 - lib/vectra/instrumentation/sentry.rb
 - lib/vectra/logging.rb
+- lib/vectra/middleware/base.rb
+- lib/vectra/middleware/cost_tracker.rb
+- lib/vectra/middleware/instrumentation.rb
+- lib/vectra/middleware/logging.rb
+- lib/vectra/middleware/pii_redaction.rb
+- lib/vectra/middleware/request.rb
+- lib/vectra/middleware/response.rb
+- lib/vectra/middleware/retry.rb
+- lib/vectra/middleware/stack.rb
 - lib/vectra/pool.rb
 - lib/vectra/providers/base.rb
 - lib/vectra/providers/memory.rb