barkibu-kb 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72ba3947460c029c6dee0dc965b1066b03b645d3bb6a891b291c2383b8d581e3
-  data.tar.gz: d0b5ca779b79f1e7017dbafca93376215faac264ec55210ef1af8f981f352ec5
+  metadata.gz: 5edd7ddce6b2d27e72f6cafcfb8efba18c35c001efe54ce96eb7a51a83d1d8ae
+  data.tar.gz: 7d1be392c9297f09f8420258adf07ad3b69b7f57d7a6a07210ef9f250aeb193e
 SHA512:
-  metadata.gz: 0d596248f6f49451a5a4bcb9ea1648b3175b3d8b1d7cbf0665082332841d63c32867e7f408d221f2a47ef7387e1b70836c74af5bfd8e5e37ae9536ea9b19ec42
-  data.tar.gz: e832f256a27bfbe905d6e122b81245370c932dad1801d5772608778851131c9da1e761817e164df8a91e5e770af79804cd2c0cfdc90310148048bd92ef761ea7
+  metadata.gz: 5427db71ffb7d349463fa04291f24106676b1761ea9e55c5cc0c0440e424dd8c5da57a70dbc17a7528f3e79a37dbe9f0ac57e80f6d735661c984eaf31b3b21a2
+  data.tar.gz: 2c92ff67fe128d0d5d9ae10e575e2df5d95d73945dbe10534aba6a6f1e493829fe09f8f0cb0613300f8b7318c73a46828139ea6a9098f6b15aa113b0f963d136

data/CHANGELOG.md

@@ -6,7 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [unreleased]
-- See diff: https://github.com/barkibu/kb-ruby/compare/v1.3.0...HEAD
+- See diff: https://github.com/barkibu/kb-ruby/compare/v1.4.0...HEAD
+
+## [1.4.0]
+- Reuse connections to KB (keep-alive) with the stock faraday-net_http_persistent adapter. New runtime dependencies: `faraday-net_http_persistent ~> 1.2`, `net-http-persistent ~> 4.0` (4.0.8 accepts `connection_pool` 2.2.4 up to < 4). On by default; `KB.config.request.keep_alive = false` restores one connection per call. New `KB.config.request.idle_timeout` (default 30s, below the Heroku router's ~55s idle close).
+- Every `KB::Client` now shares one Faraday connection (`KB::Connections`), so all model clients use one connection pool per process. Clients send full URLs and their own `x-api-key` header per request; URLs, headers and cache keys are unchanged. Settings are read when that connection is built, on the process's first KB call; `KB::Connections.reset!` applies later changes.
+- A call with its own `read_timeout:` goes through a separate plain net_http connection, so its override never reaches the shared pool's other calls.
+- With keep-alive, a connect timeout is `Faraday::TimeoutError` (was `Faraday::ConnectionFailed`) wrapping `Net::OpenTimeout`, and a refused connection is `Faraday::ConnectionFailed` wrapping `Net::HTTP::Persistent::Error`. Both still become `KB::Error` in model calls and are still retried for every verb: `KB::RetryPolicy.root_cause` unwraps `Net::HTTP::Persistent::Error` to the underlying `Errno`. Datadog `error.type` on connect-timeout spans changes accordingly.
 
 ## [1.3.0]
 - Retry transport failures once (`faraday-retry`, already in the Faraday 1.10 bundle, now an explicit dependency). `KB::RetryPolicy` decides by the underlying error, not the Faraday class: failures where the request never left (`Net::OpenTimeout`, `ECONNREFUSED`, `EHOSTUNREACH`, `ENETUNREACH`, `EADDRNOTAVAIL`, `SocketError`) retry for every verb; any other transport failure (read/write timeout, reset, EOF, TLS) retries for GET/HEAD only (and not when the call raised its own `read_timeout:`, so a 30s read isn't doubled); HTTP error responses never retry. New settings `KB.config.request.retries` (default 1, 0 disables) and `retry_interval` (default 0.1s, randomized up to 2x). Worst-case latency is now two attempts' worth of phase budgets.

data/Gemfile.lock

@@ -1,18 +1,20 @@
 PATH
   remote: .
   specs:
-    barkibu-kb (1.3.0)
+    barkibu-kb (1.4.0)
       activemodel (>= 4.0.2)
       activerecord
       activesupport (>= 3.0.0)
       dry-configurable (~> 0.9)
       faraday
       faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.2)
       faraday-retry (~> 1.0)
       faraday_middleware
       i18n
-    barkibu-kb-fake (1.3.0)
-      barkibu-kb (= 1.3.0)
+      net-http-persistent (~> 4.0)
+    barkibu-kb-fake (1.4.0)
+      barkibu-kb (= 1.4.0)
       countries
       sinatra
       webmock
@@ -110,6 +112,8 @@ GEM
     multipart-post (2.3.0)
     mustermann (3.0.0)
       ruby2_keywords (~> 0.0.1)
+    net-http-persistent (4.0.8)
+      connection_pool (>= 2.2.4, < 4)
     parallel (1.24.0)
     parser (3.3.0.5)
       ast (~> 2.4.1)

data/README.md

@@ -99,13 +99,48 @@ KB.config.request.retries = 1          # default; 0 disables retries
 KB.config.request.retry_interval = 0.1 # default, seconds; each wait is 1x-2x this
 ```
 
-Like the timeouts, these are read when a client builds its connection, i.e. on
-its first call, so set them in an initializer.
+Like the timeouts, these are read when the process's shared KB connection is
+built, i.e. on its first KB call, so set them in an initializer (or call
+`KB::Connections.reset!` after changing them at runtime).
 
 Worst case, a call now takes two attempts' worth of phase budgets plus the
 interval, e.g. a GET that read-times-out twice takes about 2 x (1 + 3 + 5)s with
 the default timeouts.
 
+#### Keep-alive connections
+
+KB calls reuse TCP/TLS connections instead of opening a new one per call, through
+the stock `net_http_persistent` Faraday adapter (net-http-persistent). Every
+model's client shares one Faraday connection (`KB::Connections`), so they all
+draw on one connection pool per process; each
+thread checks a connection out per call. A pooled connection idle for longer
+than `idle_timeout` is closed and reopened on the next call.
+
+```ruby
+# config/initializers/kb_ruby.rb
+KB.config.request.keep_alive = true # default; false opens a connection per call (net_http)
+KB.config.request.idle_timeout = 30 # default, seconds
+```
+
+Keep `idle_timeout` below the Heroku router's own idle close: it drops an idle
+client connection after about 55 seconds (measured against KB staging,
+2026-09-23). A connection the server already closed is noticed before the next
+request is written, and reopened. A close that races the request in the same
+instant can't be noticed: a GET is retried on a fresh connection (see Retries),
+a POST fails with `Faraday::ConnectionFailed` wrapping `EOFError`.
+
+Net::HTTP's own retry of idempotent requests stays off (`max_retries = 0`), so a
+PUT is never resent behind `KB::RetryPolicy`'s back.
+
+A call with its own `read_timeout:` goes through a separate plain connection,
+opened for that call: the pooled adapter keeps one timeout setting for the whole
+pool, where one call's override would reach other threads' calls.
+
+Differences from `keep_alive = false`: a connect timeout surfaces as
+`Faraday::TimeoutError` wrapping `Net::OpenTimeout` (retries classify it by that
+underlying error, so it is still retried for every verb), and a refused
+connection as `Faraday::ConnectionFailed` wrapping `Net::HTTP::Persistent::Error`.
+
 #### Instrumentation
 
 Every KB call emits one `request.kb_client` event through

data/barkibu-kb.gemspec

@@ -53,7 +53,9 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'activesupport', '>= 3.0.0'
   spec.add_runtime_dependency 'faraday'
   spec.add_runtime_dependency 'faraday-net_http', '~> 1.0'
+  spec.add_runtime_dependency 'faraday-net_http_persistent', '~> 1.2'
   spec.add_runtime_dependency 'faraday_middleware'
   spec.add_runtime_dependency 'faraday-retry', '~> 1.0'
   spec.add_runtime_dependency 'i18n'
+  spec.add_runtime_dependency 'net-http-persistent', '~> 4.0'
 end

data/lib/barkibu-kb.rb

@@ -24,6 +24,12 @@ module KB
     # Retries after a transport failure, per KB::RetryPolicy. 0 disables retries.
     setting :retries, default: 1
     setting :retry_interval, default: 0.1
+    # Reuse connections to KB across calls (faraday-net_http_persistent, one pool
+    # per process, see KB::Connections). false opens a connection per call.
+    setting :keep_alive, default: true
+    # Seconds a pooled connection may sit idle before it is closed and reopened.
+    # Keep it below the Heroku router's idle close (about 55s, see README).
+    setting :idle_timeout, default: 30
   end
 end
 
@@ -33,6 +39,7 @@ require 'kb/cache'
 require 'kb/client_resolver'
 require 'kb/errors'
 require 'kb/retry_policy'
+require 'kb/connections'
 require 'kb/client'
 
 require 'kb/concerns'

data/lib/kb/client.rb

@@ -75,10 +75,7 @@ module KB
     end
 
     def http(event, payload, read_timeout)
-      response = connection.public_send(event[:verb], event[:path], payload) do |req|
-        req.options.read_timeout = read_timeout if read_timeout
-        RetryPolicy.track(req, event, read_timeout)
-      end
+      response = send_request(event, payload, read_timeout)
       event[:status] = response.status
       response.body
     rescue Faraday::ClientError, Faraday::ServerError => e
@@ -86,11 +83,12 @@ module KB
       raise
     end
 
-    def headers
-      {
-        'Content-Type': 'application/json',
-        'x-api-key': api_key
-      }
+    def send_request(event, payload, read_timeout)
+      connection(read_timeout).public_send(event[:verb], url_for(event[:path]), payload) do |req|
+        req.headers[:'x-api-key'] = api_key # a symbol, so Faraday names it X-api-key, as the log filter expects
+        req.options.read_timeout = read_timeout if read_timeout
+        RetryPolicy.track(req, event, read_timeout)
+      end
     end
 
     def attributes_case_transform(attributes)
@@ -103,26 +101,18 @@ module KB
       attributes_case_transform(attributes).to_json
     end
 
-    def connection
-      @connection ||= Faraday.new(url: base_url, headers: headers, request: request_timeouts) do |conn|
-        conn.request :retry, RetryPolicy.middleware_options
-        conn.response :json
-        conn.response :raise_error
-        if KB.config.log_level == :debugger
-          conn.response :logger do |logger|
-            logger.filter(/(X-api-key:\s)("\w+")/, '\1[API_KEY_SCRUBBED]')
-          end
-        end
-        conn.adapter :net_http
-      end
+    # The process-wide connection every client shares (see KB::Connections):
+    # keep-alive unless disabled, or unless this one call sets its own read_timeout.
+    def connection(read_timeout = nil)
+      Connections.fetch(keep_alive: KB.config.request.keep_alive && read_timeout.nil?)
     end
 
-    def request_timeouts
-      {
-        open_timeout: KB.config.request.connect_timeout,
-        write_timeout: KB.config.request.write_timeout,
-        read_timeout: KB.config.request.read_timeout
-      }
+    # The URL a Faraday connection on base_url would build for `path`, by Faraday's
+    # own joining rules ("" is base_url itself, anything else is relative to
+    # base_url + "/"), so sharing one connection across clients changes no URL.
+    def url_for(path)
+      @url_builder ||= Faraday::Connection.new(url: base_url)
+      @url_builder.build_exclusive_url(path).to_s
     end
   end
 end

data/lib/kb/connections.rb

@@ -0,0 +1,70 @@
+require 'faraday/net_http_persistent'
+
+module KB
+  # The Faraday connections behind every KB::Client, shared per process.
+  #
+  # Each model class has its own KB::Client (PetParent, Pet, Breed...). Sharing
+  # one Faraday connection between them means one adapter instance, so with
+  # keep-alive (the stock faraday-net_http_persistent adapter) one connection
+  # pool serves every client. Clients send full URLs and their own API key per
+  # request, so nothing on the connection is specific to one client; the pool
+  # keeps its sockets per host and port.
+  #
+  # Two connections:
+  # - keep-alive, for every call on the global timeouts;
+  # - plain net_http (a new connection per call), for calls that set their own
+  #   `read_timeout:`. The persistent adapter writes each call's timeouts onto the
+  #   shared pool object, where any thread's next checkout reads them, so a
+  #   per-call override there would leak into other threads' calls.
+  #
+  # Built on first use from KB.config; `reset!` applies later config changes.
+  module Connections
+    MUTEX = Mutex.new
+    @connections = {}
+
+    class << self
+      def fetch(keep_alive:)
+        @connections[keep_alive] || MUTEX.synchronize { @connections[keep_alive] ||= build(keep_alive) }
+      end
+
+      def reset!
+        MUTEX.synchronize { @connections = {} }
+      end
+
+      private
+
+      def build(keep_alive)
+        Faraday.new(headers: { 'Content-Type': 'application/json' }, request: timeouts) do |conn|
+          conn.request :retry, RetryPolicy.middleware_options
+          conn.response :json
+          conn.response :raise_error
+          log(conn) if KB.config.log_level == :debugger
+          adapter(conn, keep_alive)
+        end
+      end
+
+      # The block runs on every request, on the shared Net::HTTP::Persistent.
+      # faraday-net_http's configure_request also sets max_retries = 0 there, so
+      # Net::HTTP never retries on its own: retries belong to KB::RetryPolicy.
+      def adapter(conn, keep_alive)
+        return conn.adapter(:net_http) unless keep_alive
+
+        conn.adapter(:net_http_persistent) { |http| http.idle_timeout = KB.config.request.idle_timeout }
+      end
+
+      def log(conn)
+        conn.response :logger do |logger|
+          logger.filter(/(X-api-key:\s)("\w+")/, '\1[API_KEY_SCRUBBED]')
+        end
+      end
+
+      def timeouts
+        {
+          open_timeout: KB.config.request.connect_timeout,
+          write_timeout: KB.config.request.write_timeout,
+          read_timeout: KB.config.request.read_timeout
+        }
+      end
+    end
+  end
+end

data/lib/kb/retry_policy.rb

@@ -1,5 +1,6 @@
 require 'socket'
 require 'net/http'
+require 'net/http/persistent'
 require 'faraday/retry'
 
 module KB
@@ -49,9 +50,12 @@ module KB
     # The Ruby error behind a Faraday error. `wrapped_exception` is Faraday's own
     # explicit link to it (Ruby's `cause` is only whatever was being rescued at
     # the raise, usually the same object). Faraday's adapters wrap the Ruby error
-    # one level deep, so one level is enough.
+    # one level deep, so one level is enough, except that net-http-persistent
+    # re-raises a refused connection as its own Net::HTTP::Persistent::Error with
+    # the Errno as its `cause`.
     def root_cause(error)
-      (error.respond_to?(:wrapped_exception) && error.wrapped_exception) || error.cause || error
+      cause = (error.respond_to?(:wrapped_exception) && error.wrapped_exception) || error.cause || error
+      cause.is_a?(Net::HTTP::Persistent::Error) && cause.cause ? cause.cause : cause
     end
 
     # Options for faraday-retry's middleware, read from KB.config.request.

data/lib/kb/version.rb

@@ -1,3 +1,3 @@
 module KB
-  VERSION = '1.3.0'.freeze
+  VERSION = '1.4.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: barkibu-kb
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Léo Figea
@@ -247,6 +247,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http_persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: faraday_middleware
   requirement: !ruby/object:Gem::Requirement
@@ -289,6 +303,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: net-http-persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: A wrapper of Barkibu's Knowledge Base Endpoint to make those entities
   and their respective CRUD operations available to a ruby app
 email:
@@ -325,6 +353,7 @@ files:
 - lib/kb/client_resolver.rb
 - lib/kb/concerns.rb
 - lib/kb/concerns/as_kb_wrapper.rb
+- lib/kb/connections.rb
 - lib/kb/errors.rb
 - lib/kb/errors/client_error.rb
 - lib/kb/errors/conflict_error.rb