Merge branch 'master' into thread-safe-node-rotation

Author: erimicel

.github/workflows/tests.yml

@@ -10,10 +10,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.0', '3.2', '3.3', '3.4']
+        ruby-version: ['3.0', '3.2', '3.3', '3.4', '4.0']
     services:
       typesense:
-        image: typesense/typesense:30.0.alpha1
+        image: typesense/typesense:30.2
         ports:
           - 8108:8108
         volumes:

.rubocop.yml

@@ -47,5 +47,13 @@ RSpec/ExampleLength:
 RSpec/MultipleExpectations:
   Enabled: false
 
+RSpec/Output:
+  Exclude:
+    - spec/spec_helper.rb
+
+Naming/PredicateMethod:
+  Exclude:
+    - spec/spec_helper.rb
+
 Style/HashSyntax:
   Enabled: false # We still want to support older versions of Ruby

Gemfile

@@ -6,17 +6,13 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Dev dependencies
 gem 'awesome_print', '~> 1.8'
-gem 'bundler', '~> 2.0'
-gem 'codecov', '~> 0.1'
-gem 'erb'
+gem 'bundler', '>= 2.0'
 gem 'guard', '~> 2.16'
 gem 'guard-rubocop', '~> 1.3'
 gem 'rake', '~> 13.0'
 gem 'rspec', '~> 3.9'
-gem 'rspec_junit_formatter', '~> 0.4'
-gem 'rspec-legacy_formatters', '~> 1.0' # For codecov formatter
-gem 'rubocop', '1.72.2'
-gem 'rubocop-rspec', '~> 3.6', require: false
+gem 'rubocop', '~> 1.86'
+gem 'rubocop-rspec', '~> 3.9', require: false
 gem 'simplecov', '~> 0.18'
 gem 'timecop', '~> 0.9'
 gem 'webmock', '~> 3.8'

README.md

@@ -29,6 +29,29 @@ Here are some examples with inline comments that walk you through how to use the
 
 Tests are also a good place to know how the the library works internally: [spec](spec)
 
+### Keep-alive connections
+
+By default, the client opens a fresh HTTP connection (and TLS handshake) for every request. For high-traffic applications this can dominate request latency. Setting `keep_alive_connections: true` enables persistent connections via the `:net_http_persistent` Faraday adapter:
+
+```ruby
+Typesense::Client.new(
+  api_key: ENV['TYPESENSE_API_KEY'],
+  nodes: [{ host: 'localhost', port: 8108, protocol: 'https' }],
+  connection_timeout_seconds: 3,
+  num_retries: 1,
+  keep_alive_connections: true
+)
+```
+
+Notes:
+
+- Connections are cached per `(thread, node)`. `Net::HTTP` is not thread-safe, so each thread maintains its own keep-alive socket to each Typesense node, and the existing node round-robin still works.
+- A cached connection is dropped automatically when a network error occurs, so retries open a fresh socket. We recommend setting `num_retries` to at least `1` so the gem can recover from a server- or load-balancer-side idle timeout transparently.
+- Idle sockets are closed after 30 seconds by default. Override with `keep_alive_idle_timeout_seconds` to match or stay under your load balancer's idle timeout.
+- The underlying `net_http_persistent` adapter holds at most `keep_alive_pool_size` sockets per origin (default `1`, which matches the per-`(thread, node)` cache above). The default of `1` is the safe choice for the vast majority of users — because we already cache one Faraday connection per `(thread, node)` and `Net::HTTP` is not thread-safe, a single socket per pool is all the adapter needs. Only raise this if you have a specific reason to keep additional sockets warm per origin (e.g. a non-standard concurrency model layered on top of this client); a larger pool will not increase request throughput on its own.
+- `keep_alive_idle_timeout_seconds` and `keep_alive_pool_size` are only valid when `keep_alive_connections: true`; setting them otherwise raises `Typesense::Error::MissingConfiguration`.
+- The option defaults to `false`, so upgrading the gem does not change behaviour until you opt in.
+
 ## Compatibility
 
 | Typesense Server | typesense-ruby |

docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   typesense:
-    image: typesense/typesense:29.0
+    image: typesense/typesense:30.2
     ports:
       - "127.0.0.1:8108:8108"
     volumes:

lib/typesense/api_call.rb

@@ -19,10 +19,20 @@ def initialize(configuration)
       @healthcheck_interval_seconds = @configuration.healthcheck_interval_seconds
       @num_retries_per_request = @configuration.num_retries
       @retry_interval_seconds = @configuration.retry_interval_seconds
+      @keep_alive_connections = @configuration.keep_alive_connections
+      @keep_alive_idle_timeout_seconds = @configuration.keep_alive_idle_timeout_seconds
+      @keep_alive_pool_size = @configuration.keep_alive_pool_size
 
       @logger = @configuration.logger
 
       @nodes_mutex = Mutex.new
+
+      # Per-instance key for the thread-local connection cache so multiple
+      # Typesense::Client instances in the same process do not share sockets.
+      @thread_connections_key = :"_typesense_api_call_connections_#{object_id}"
+
+      require 'faraday/net_http_persistent' if @keep_alive_connections
+
       initialize_metadata_for_nodes
       @current_node_index = -1
     end
@@ -70,14 +80,11 @@ def perform_request(method, endpoint, query_parameters: nil, body_parameters: ni
         @logger.debug "Attempting #{method.to_s.upcase} request Try ##{num_tries} to Node #{node[:index]}"
 
         begin
-          conn = Faraday.new(uri_for(endpoint, node)) do |f|
-            f.options.timeout = @connection_timeout_seconds
-            f.options.open_timeout = @connection_timeout_seconds
-          end
+          conn, request_path = connection_and_path_for(endpoint, node)
 
           headers = default_headers.merge(additional_headers)
 
-          response = conn.send(method) do |req|
+          response = conn.send(method, request_path) do |req|
             req.headers = headers
             req.params = query_parameters unless query_parameters.nil?
             unless body_parameters.nil?
@@ -109,6 +116,9 @@ def perform_request(method, endpoint, query_parameters: nil, body_parameters: ni
           # Rescue network layer exceptions and HTTP 5xx errors, so the loop can continue.
           # Using loops for retries instead of rescue...retry to maintain consistency with client libraries in
           #   other languages that might not support the same construct.
+          # Drop the cached keep-alive connection (if any): the underlying socket is likely
+          # half-closed and reusing it would just fail again on retry.
+          discard_connection(node) if @keep_alive_connections
           set_node_healthcheck(node, is_healthy: false)
           last_exception = e
           @logger.warn "Request #{method}:#{uri_for(endpoint, node)} to Node #{node[:index]} failed due to \"#{e.class}: #{e.message}\""
@@ -126,6 +136,57 @@ def uri_for(endpoint, node)
       "#{node[:protocol]}://#{node[:host]}:#{node[:port]}#{endpoint}"
     end
 
+    # Returns [connection, request_path]. When keep-alive is enabled, the connection
+    # is cached per (thread, node) and the path is appended at request time. When it
+    # is disabled, the original behaviour is preserved: a fresh Faraday is built for
+    # the full per-request URL, so existing callers and stubs see no change.
+    def connection_and_path_for(endpoint, node)
+      if @keep_alive_connections
+        [connection_for(node), endpoint]
+      else
+        [build_one_shot_connection(endpoint, node), nil]
+      end
+    end
+
+    def build_one_shot_connection(endpoint, node)
+      Faraday.new(uri_for(endpoint, node)) do |f|
+        f.options.timeout = @connection_timeout_seconds
+        f.options.open_timeout = @connection_timeout_seconds
+      end
+    end
+
+    # Net::HTTP is not thread-safe, so connections are cached per (thread, node)
+    # rather than shared across threads.
+    def connection_for(node)
+      thread_connections[connection_key(node)] ||= build_keep_alive_connection(node)
+    end
+
+    def discard_connection(node)
+      conn = thread_connections.delete(connection_key(node))
+      conn&.close if conn.respond_to?(:close)
+    end
+
+    def thread_connections
+      Thread.current[@thread_connections_key] ||= {}
+    end
+
+    def connection_key(node)
+      "#{node[:protocol]}://#{node[:host]}:#{node[:port]}"
+    end
+
+    def build_keep_alive_connection(node)
+      Faraday.new(url: connection_key(node)) do |f|
+        f.options.timeout = @connection_timeout_seconds
+        f.options.open_timeout = @connection_timeout_seconds
+        # pool_size defaults to 1: we already cache one Faraday connection per
+        # (thread, node), and Net::HTTP is not thread-safe — so a single socket
+        # per pool is the safe default. Override only with a specific reason.
+        f.adapter :net_http_persistent, pool_size: @keep_alive_pool_size do |http|
+          http.idle_timeout = @keep_alive_idle_timeout_seconds
+        end
+      end
+    end
+
     ## Attempts to find the next healthy node, looping through the list of nodes once.
     #   But if no healthy nodes are found, it will just return the next node, even if it's unhealthy
     #     so we can try the request for good measure, in case that node has become healthy since

lib/typesense/configuration.rb

@@ -4,7 +4,7 @@
 
 module Typesense
   class Configuration
-    attr_accessor :nodes, :nearest_node, :connection_timeout_seconds, :healthcheck_interval_seconds, :num_retries, :retry_interval_seconds, :api_key, :logger, :log_level
+    attr_accessor :nodes, :nearest_node, :connection_timeout_seconds, :healthcheck_interval_seconds, :num_retries, :retry_interval_seconds, :api_key, :logger, :log_level, :keep_alive_connections, :keep_alive_idle_timeout_seconds, :keep_alive_pool_size
 
     def initialize(options = {})
       @nodes = options[:nodes] || []
@@ -14,23 +14,28 @@ def initialize(options = {})
       @num_retries = options[:num_retries] || (@nodes.length + (@nearest_node.nil? ? 0 : 1)) || 3
       @retry_interval_seconds = options[:retry_interval_seconds] || 0.1
       @api_key = options[:api_key]
+      @keep_alive_connections = options.fetch(:keep_alive_connections, false)
+      @keep_alive_idle_timeout_seconds = options[:keep_alive_idle_timeout_seconds] || 30
+      @keep_alive_pool_size = options[:keep_alive_pool_size] || 1
 
       @logger = options[:logger] || Logger.new($stdout)
       @log_level = options[:log_level] || Logger::WARN
       @logger.level = @log_level
 
       show_deprecation_warnings(options)
-      validate!
+      validate!(options)
     end
 
-    def validate!
+    def validate!(options = {})
       if @nodes.nil? ||
          @nodes.empty? ||
          @nodes.any? { |node| node_missing_parameters?(node) }
         raise Error::MissingConfiguration, 'Missing required configuration. Ensure that nodes[][:protocol], nodes[][:host] and nodes[][:port] are set.'
       end
 
       raise Error::MissingConfiguration, 'Missing required configuration. Ensure that api_key is set.' if @api_key.nil?
+
+      validate_keep_alive_options!(options)
     end
 
     private
@@ -39,6 +44,15 @@ def node_missing_parameters?(node)
       %i[protocol host port].any? { |attr| node.send(:[], attr).nil? }
     end
 
+    def validate_keep_alive_options!(options)
+      return if @keep_alive_connections
+
+      dependent_keys = %i[keep_alive_idle_timeout_seconds keep_alive_pool_size].select { |k| options.key?(k) }
+      return if dependent_keys.empty?
+
+      raise Error::MissingConfiguration, "#{dependent_keys.join(' and ')} require keep_alive_connections: true."
+    end
+
     def show_deprecation_warnings(options)
       @logger.warn 'Deprecation warning: timeout_seconds is now renamed to connection_timeout_seconds' unless options[:timeout_seconds].nil?
       @logger.warn 'Deprecation warning: master_node is now consolidated to nodes, starting with Typesense Server v0.12' unless options[:master_node].nil?