Keep alive pool size configurable

Author: erimicel

README.md

@@ -48,6 +48,8 @@ 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

lib/typesense/api_call.rb

@@ -21,6 +21,7 @@ def initialize(configuration)
       @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
 
@@ -175,7 +176,10 @@ 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
-        f.adapter :net_http_persistent, pool_size: 1 do |http|
+        # 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

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, :keep_alive_connections, :keep_alive_idle_timeout_seconds
+    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] || []
@@ -16,23 +16,26 @@ def initialize(options = {})
       @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
@@ -41,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?

spec/typesense/api_call_spec.rb

@@ -356,6 +356,24 @@
       expect(custom_client.configuration.keep_alive_idle_timeout_seconds).to eq(5)
       expect(described_class.new(custom_client.configuration).instance_variable_get(:@keep_alive_idle_timeout_seconds)).to eq(5)
     end
+
+    it 'defaults the pool size to 1' do
+      expect(keep_alive_typesense.configuration.keep_alive_pool_size).to eq(1)
+    end
+
+    it 'honours a custom keep_alive_pool_size' do
+      custom_client = Typesense::Client.new(
+        api_key: 'abcd',
+        nodes: typesense.configuration.nodes,
+        connection_timeout_seconds: 10,
+        log_level: Logger::ERROR,
+        keep_alive_connections: true,
+        keep_alive_pool_size: 5
+      )
+
+      expect(custom_client.configuration.keep_alive_pool_size).to eq(5)
+      expect(described_class.new(custom_client.configuration).instance_variable_get(:@keep_alive_pool_size)).to eq(5)
+    end
   end
 
   describe 'keep-alive disabled (default)' do
@@ -371,5 +389,27 @@
 
       expect(Thread.current[api_call.instance_variable_get(:@thread_connections_key)]).to be_nil
     end
+
+    it 'raises when keep_alive_idle_timeout_seconds is set without keep_alive_connections' do
+      expect do
+        Typesense::Client.new(
+          api_key: 'abcd',
+          nodes: typesense.configuration.nodes,
+          log_level: Logger::ERROR,
+          keep_alive_idle_timeout_seconds: 5
+        )
+      end.to raise_error(Typesense::Error::MissingConfiguration, /keep_alive_connections: true/)
+    end
+
+    it 'raises when keep_alive_pool_size is set without keep_alive_connections' do
+      expect do
+        Typesense::Client.new(
+          api_key: 'abcd',
+          nodes: typesense.configuration.nodes,
+          log_level: Logger::ERROR,
+          keep_alive_pool_size: 4
+        )
+      end.to raise_error(Typesense::Error::MissingConfiguration, /keep_alive_connections: true/)
+    end
   end
 end