skaidb 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f947092b55d66cc8d7c55153cbea09ebcdd0298f48fcb6c97ea0f3a5edd5ac01
-  data.tar.gz: 9b472d16803f161f2aa6d4554c19aede65f9a227b79d29c7f015204c04a7bcc7
+  metadata.gz: 0514ffe373981266d475977fd65030cbf7bdc8a2ba568c77b80afe963904e242
+  data.tar.gz: a7a1ce25bf193955ae0f765df14245ab0cf1a4d6ff6902f712291666646b0061
 SHA512:
-  metadata.gz: 68d82f58f409113c18f1536023042343ffbfa86c8ec6029a0f799cd8f88fd038f418ced9c1be77beca7826c7d5756e523de221c6bf798e7069db1e14be7aaf12
-  data.tar.gz: f95915e0918b17e31d2b9e63cfbcbe92ee717f07b49075bbd1da055cb49f60f592c346eb579b6c65a8dc855ddf669c41d467086dec90ccb59abc0861c784dacc
+  metadata.gz: e60490e9a1e5ef0381199c96981bf18a19cfd915da2926ce6ac3395bb31cdb20be2d3c5135a1cc7b6172ab48dae15877d0479ea6aa86b1aa0da0219e062f70e9
+  data.tar.gz: 9a8a3422a05a1eb3294bd67425a6d59291924254d6b9acac4002923d14867b3f30205a21446b254c2957a51090a76508deb69df6abd1058b5bdef96383402d95

data/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to the skaidb Ruby driver. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.4.1] - 2026-10-31
+
+### Fixed
+- One slow round trip at the start can no longer get a healthy member
+  ejected for latency. A member's first round trip set its average
+  outright, so a statement that stalled in the client — a CPU-bound
+  application holding the thread while it starts — put seconds into it;
+  ten round trips later the member was compared with the others, and the
+  average had barely decayed: ejected (`latency 4153.7 ms vs median
+  0.2 ms`) while it answered in milliseconds. The fastest of a member's
+  first three round trips now seeds its average (a round trip is only ever
+  lengthened), and later ones move it as before; until then the member
+  counts as not measured, and `pool.members` reports its `latency_ms` as
+  `nil`.
+- A latency ejection's `logger` warning names the slowest of the member's
+  last 10 round trips alongside its average and the median, which tells a
+  slow member from one slow statement.
+
 ## [1.4.0] - 2026-10-29
 
 ### Fixed
@@ -206,6 +224,8 @@ batches, a 2 500-row stream, error handling, and the `drivers` table showing
   because it is a bundled gem since Ruby 3.4.
 - The example moved to `examples/basic.rb`.
 
+[1.4.1]: https://github.com/porcupin26/skaidb-ruby/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.3...v1.1.0

data/README.md

@@ -55,13 +55,13 @@ Xcode command-line tools on macOS). `gem install skaidb` and vendoring reuse
 the `bigdecimal` already installed.
 
 Or vendor the single file: copy
-[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.4.0/lib/skaidb.rb)
+[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.4.1/lib/skaidb.rb)
 into your project and `require_relative` it. It has no dependencies beyond
 Ruby's standard library.
 
 Every release is also attached as a `.gem` to its
 [GitHub release](https://github.com/porcupin26/skaidb-ruby/releases) for
-installs without registry access: `gem install ./skaidb-1.4.0.gem`.
+installs without registry access: `gem install ./skaidb-1.4.1.gem`.
 
 ## Quick start
 
@@ -359,8 +359,11 @@ pool.members # => [{ endpoint: "db1:7000", canonical: "10.0.0.1:7000", state: :r
 
 A member with consecutive transport failures, or a round-trip average far
 above the others', is ejected and re-admitted by a background probe (the last
-usable member never is); `idle_order: :fifo` keeps every idle connection in
-use. Details: [docs/pooling.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/pooling.md).
+usable member never is). The fastest of a member's first three round trips
+seeds its average, so a statement that stalls in your own process cannot get
+a healthy member ejected; a latency ejection's `logger:` warning names the
+average, the median and the slowest of the member's last 10 round trips.
+`idle_order: :fifo` keeps every idle connection in use. Details: [docs/pooling.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/pooling.md).
 
 ## Streams (`CREATE STREAM`)
 
@@ -461,7 +464,7 @@ frame after every handshake. It shows up as `client_name = 'ruby'` /
 
 ```sql
 SELECT client_name, client_version FROM drivers;
--- ruby | 1.4.0
+-- ruby | 1.4.1
 ```
 
 The server records the row asynchronously, so a `SELECT` immediately after

data/docs/pooling.md

@@ -81,7 +81,7 @@ pool = Skaidb::Pool.new(
 | `idle_order` | `:lifo` | `:lifo` hands out the most recently returned connection first, so a quiet pool keeps few sockets warm. `:fifo` hands out the longest-idle one first, so every idle connection keeps being used and a server-side idle timeout never finds one. |
 | `discover` | `false` | Reads the members with `SHOW ENDPOINTS` (server ≥ 0.327; no privilege needed) when a member is first reached and every `refresh_interval` (60 s) after — every 5 s while a member is `resyncing` or `unreachable`. New members are added, members that left are dropped (seeds are kept, marked `unlisted`), and members the server reports `resyncing` or `unreachable` get no new connections until they are `ready` again, when they start with a fresh latency average. An older or standalone server leaves the seeds as they are, and the pool stops asking. |
 | `eject_errors` | `3` | Consecutive transport failures (a failed dial, an I/O error mid-request, a capacity refusal) that eject a member. Statement errors and refused logins do not count. |
-| `eject_latency_factor`, `eject_latency_floor` | `3.0`, `0.05` | A member whose round-trip average is above factor × the other usable members' median **and** more than floor seconds above it is ejected (once it and another member have 10 samples each). A factor of `0` disables it. |
+| `eject_latency_factor`, `eject_latency_floor` | `3.0`, `0.05` | A member whose round-trip average is above factor × the other usable members' median **and** more than floor seconds above it is ejected (once it and another member have 10 samples each). The fastest of a member's first three round trips seeds its average, so a statement that stalls in your own process — a CPU-bound start-up — cannot get a healthy member ejected; the `logger` warning names the average, the median and the slowest of the member's last 10 round trips. A factor of `0` disables it. |
 | `eject_backoff`, `eject_backoff_max` | `5.0`, `60.0` | How long an ejection lasts, doubling for each repeat up to the max; a member that stays healthy for `eject_backoff_max` after a re-admission starts over at the base. When the time is up a background thread dials the member and runs one statement: success re-admits it (with a fresh latency average), failure ejects it again. The last usable member is never ejected — a slow or flaky member beats none. |
 | `read_your_writes` | `0.0` | Seconds after a write during which checkouts with the same `affinity` go to the member that took the write. |
 | `logger` | `nil` | A `Logger` (or anything with `warn`) told of each ejection and re-admission. |
@@ -94,10 +94,15 @@ through to the other usable members, then to the unusable ones, so a
 checkout never has nowhere to go while any member is configured.
 
 **Latency.** Per member the pool keeps an exponentially weighted average of
-round trips (request sent to the first response frame): each sample moves it
-5 % of the way, and no sample counts for more than 10 × the larger of the
-current average and `eject_latency_floor`. One slow statement barely moves
-it; a member that stays slow is noticed within a few dozen statements.
+round trips (request sent to the first response frame). The fastest of the
+member's first three round trips seeds it: a round trip is only ever
+lengthened — by the member, the network or your own process (a thread that
+stalls while the application starts, say) — so one or two slow first
+statements cannot set it. From then on each sample moves it 5 % of the way,
+and no sample counts for more than 10 × the larger of the current average
+and `eject_latency_floor`. One slow statement barely moves it; a member that
+stays slow is noticed within a few dozen statements. Until its average is
+seeded a member counts as not measured.
 
 **Read-your-writes.** The member that coordinated a write reads it back at
 any consistency, `ONE` included; another member may not have applied it yet.
@@ -139,7 +144,8 @@ endpoint:
 `endpoint` is what the pool dials, `canonical` the name the member reports
 for itself (once discovered), `state` one of `:ready`, `:ejected`,
 `:resyncing`, `:unreachable`, `:unlisted`, and `latency_ms` is `nil` until
-the member has been measured. The rules are the same in every skaidb driver
+the member has been measured (its first three round trips). The rules are
+the same in every skaidb driver
 ([PROTOCOL.md §6.1](https://skaidb.org/docs/PROTOCOL.html#61-balancing-a-pool-across-members)).
 
 ## Behaviour

data/lib/skaidb.rb

@@ -35,7 +35,7 @@ require "bigdecimal"
 module Skaidb
   # The package version — the single source of truth. The gemspec reads it,
   # and it is what the driver reports to the server in the Hello frame.
-  VERSION = "1.4.0"
+  VERSION = "1.4.1"
 
   # Base class for every error raised by this driver.
   class Error < StandardError; end
@@ -1568,13 +1568,18 @@ module Skaidb
   class Pool
     POLICIES = %i[random round_robin least_latency].freeze
     IDLE_ORDERS = %i[lifo fifo].freeze
-    # Latency EWMA: each round trip moves a member's average 5% toward it,
-    # and no sample counts for more than 10x the larger of the current
-    # average and the ejection floor — one slow query does not eject a
-    # healthy member, a member that stays slow is ejected within a few dozen
-    # statements.
+    # Latency EWMA: the fastest of a member's first round trips seeds it (a
+    # round trip is only ever lengthened — by the member, the network or this
+    # process stalling — so a slow first statement cannot set it); then each
+    # round trip moves it 5% toward it, and no sample counts for more than
+    # 10x the larger of the current average and the ejection floor — one slow
+    # query does not eject a healthy member, a member that stays slow is
+    # ejected within a few dozen statements.
+    EWMA_SEED_SAMPLES = 3
     EWMA_WEIGHT = 0.05
     EWMA_CLAMP = 10.0
+    # Round trips a latency ejection's warning reports the slowest of.
+    RECENT_SAMPLES = 10
     # Round trips a member (and at least one other) needs before its average
     # can eject it.
     EWMA_MIN_SAMPLES = 10
@@ -1591,12 +1596,13 @@ module Skaidb
     MAINTAIN_TICK = 0.25
     # Read-your-writes keys kept before the expired ones are swept.
     AFFINITY_SWEEP = 4096
-    private_constant :EWMA_WEIGHT, :EWMA_CLAMP, :EWMA_MIN_SAMPLES, :STALE_SAMPLE,
-                     :REFRESH_NOT_READY, :MAINTAIN_TICK, :AFFINITY_SWEEP
+    private_constant :EWMA_SEED_SAMPLES, :EWMA_WEIGHT, :EWMA_CLAMP, :RECENT_SAMPLES,
+                     :EWMA_MIN_SAMPLES, :STALE_SAMPLE, :REFRESH_NOT_READY, :MAINTAIN_TICK,
+                     :AFFINITY_SWEEP
 
     # One member as the pool sees it.
     class Member
-      attr_reader :endpoint, :host, :port, :seed
+      attr_reader :endpoint, :host, :port, :seed, :firsts, :recent
       attr_accessor :canonical, :listed, :ewma, :samples, :last_sample, :errors,
                     :ejected_until, :ejections, :readmitted_at, :in_use, :probing
 
@@ -1608,6 +1614,8 @@ module Skaidb
         @canonical = nil              # its own SHOW ENDPOINTS name
         @listed = :ready              # :ready, :resyncing, :unreachable, :unlisted
         @ewma = nil                   # seconds
+        @firsts = []                  # round trips before the average is seeded
+        @recent = []                  # the last RECENT_SAMPLES round trips
         @samples = 0
         @last_sample = 0.0
         @errors = 0                   # consecutive transport failures
@@ -1617,6 +1625,14 @@ module Skaidb
         @in_use = 0
         @probing = false
       end
+
+      # Measure the member afresh (a re-admission, back to ready).
+      def reset_latency
+        @ewma = nil
+        @firsts.clear
+        @recent.clear
+        @samples = 0
+      end
     end
     private_constant :Member
 
@@ -1787,15 +1803,21 @@ module Skaidb
         next if m.nil?
 
         m.errors = 0
+        m.recent.push(elapsed)
+        m.recent.shift if m.recent.length > RECENT_SAMPLES
         if m.ewma.nil?
-          m.ewma = elapsed
+          m.firsts.push(elapsed)
+          if m.firsts.length >= EWMA_SEED_SAMPLES
+            m.ewma = m.firsts.min
+            m.firsts.clear
+          end
         else
           cap = EWMA_CLAMP * [m.ewma, @eject_floor].max
           m.ewma += EWMA_WEIGHT * ([elapsed, cap].min - m.ewma)
         end
         m.samples += 1
         m.last_sample = now
-        next unless m.samples >= EWMA_MIN_SAMPLES && @eject_factor.positive? && m.ejected_until.nil?
+        next unless m.ewma && m.samples >= EWMA_MIN_SAMPLES && @eject_factor.positive? && m.ejected_until.nil?
 
         others = @members.each_value.select do |o|
           !o.equal?(m) && usable?(o) && o.ewma && o.samples >= EWMA_MIN_SAMPLES
@@ -1804,7 +1826,9 @@ module Skaidb
 
         median = others[(others.length - 1) / 2]
         if m.ewma > @eject_factor * median && m.ewma - median > @eject_floor
-          eject(m, format("latency %.1f ms vs median %.1f ms", m.ewma * 1000, median * 1000))
+          eject(m, format("latency %.1f ms vs median %.1f ms; " \
+                          "slowest of the last %d round trips %.1f ms",
+                          m.ewma * 1000, median * 1000, m.recent.length, m.recent.max * 1000))
         end
       end
     end
@@ -2009,8 +2033,7 @@ module Skaidb
         if ok && !@closed
           m.ejected_until = nil
           m.errors = 0
-          m.ewma = nil
-          m.samples = 0
+          m.reset_latency
           m.readmitted_at = now
           log("re-admitted #{m.endpoint}")
           if @idle.length < @maxsize
@@ -2112,8 +2135,7 @@ module Skaidb
         state = %w[ready resyncing unreachable].include?(state) ? state.to_sym : :ready
         if state == :ready && m.listed != :ready
           # Back in rotation: measured afresh, like a re-admission.
-          m.ewma = nil
-          m.samples = 0
+          m.reset_latency
           m.errors = 0
         end
         m.listed = state

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skaidb
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - skaidb contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-30 00:00:00.000000000 Z
+date: 2026-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal