feat: opt-in HTTP keep-alive via keep_alive_connections

[erimicel]

Motivation

Typesense::ApiCall#perform_request (lib/typesense/api_call.rb:72) constructs a fresh Faraday.new(...) on every call, which in turn builds a new Net::HTTP instance per request. For HTTPS clusters this means the TCP connection and TLS handshake are repeated on every search/index call, even when the same client instance is being reused as a process-wide singleton.

We profiled this on a hot search endpoint and the OpenSSL::X509::Store#set_default_paths plus the TLS handshake consistently dominated the request, despite the client itself being a singleton. The fix at the application layer is impossible while the gem rebuilds the Faraday connection on every call.

What

Adds an opt-in keep_alive_connections config option (default false — no behaviour change for existing users).

Typesense::Client.new(
  api_key: ENV['TYPESENSE_API_KEY'],
  nodes: [{ host: 'localhost', port: 8108, protocol: 'https' }],
  num_retries: 1,
  keep_alive_connections: true,
  keep_alive_idle_timeout_seconds: 30 # optional, default 30
)

When enabled:

• Faraday connections are cached per (thread, node) (Net::HTTP is not thread-safe), keyed by protocol://host:port. Existing node round-robin and nearest_node logic are unchanged.
• Uses the :net_http_persistent adapter; keep_alive_idle_timeout_seconds (default 30s) controls how long an idle socket is reused before being dropped — set this at or below your load balancer's idle timeout.
• On any rescued network error the cached connection is discarded before retry, so a half-closed socket can't fail the retry too. Pair with num_retries >= 1 for transparent recovery.
• Cache is keyed by ApiCall#object_id, so multiple Typesense::Client instances don't share sockets.

Default-off safety

require 'faraday/net_http_persistent' is gated on the flag, so the new dependency isn't loaded when keep-alive is off. The legacy per-request Faraday.new codepath is preserved verbatim. Rescue/retry list is unchanged.

Tests

spec/typesense/api_call_spec.rb (+10 examples, all green): connection reuse, per-node keying, per-thread isolation, per-instance isolation, eviction on network error, timeout propagation, custom + default keep_alive_idle_timeout_seconds, default-off path.

PR Checklist

• I have read and signed the Contributor License Agreement.