skaidb 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a452610f682221a59cfbbc48e42c9a37f1c0e880d2191037f1c9c7151a3034fa
-  data.tar.gz: 1a73f7f552091bfaed9b4072dfd684b57daac637ff12d163a34bf1c278bef784
+  metadata.gz: 0514ffe373981266d475977fd65030cbf7bdc8a2ba568c77b80afe963904e242
+  data.tar.gz: a7a1ce25bf193955ae0f765df14245ab0cf1a4d6ff6902f712291666646b0061
 SHA512:
-  metadata.gz: ce44a1e28e0add382aa9fde578eb09350e1b5306d22c3cf5d272faa5d606c8ec05be08b77967d014a33ceddba5fefd0ed449503c24d4997680c37af156ad2e5f
-  data.tar.gz: 3d34175d862982988e593fb42c631bdbb9cd6f23682908ec40fc53a7d25fe3868105201dd50988108508783bfb8bf076065737864d71c6cc5337c8b6c371e6c3
+  metadata.gz: e60490e9a1e5ef0381199c96981bf18a19cfd915da2926ce6ac3395bb31cdb20be2d3c5135a1cc7b6172ab48dae15877d0479ea6aa86b1aa0da0219e062f70e9
+  data.tar.gz: 9a8a3422a05a1eb3294bd67425a6d59291924254d6b9acac4002923d14867b3f30205a21446b254c2957a51090a76508deb69df6abd1058b5bdef96383402d95

data/CHANGELOG.md

@@ -4,6 +4,38 @@ 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
+- A streamed `CALL` whose procedure body `EMIT`s result sets returns them.
+  The server answers such a call with every set in one `ResultSets` frame
+  (tag 8) even to a stream request, and `conn.stream`, with or without
+  parameters, raised `QueryError` (`unexpected response tag 8 to stream
+  request`) and lost the sets. The frame is now decoded by the code `exec`
+  uses: the block receives the rows `exec`'s `Result` would yield (the
+  call's final result, the LAST set) and `stream` returns that same `:rows`
+  `Result`, every set in order under `result_sets`. Nothing is left in
+  flight, so the connection stays usable — the block may even run
+  statements on it.
+
 ## [1.3.0] - 2026-10-29
 
 ### Added
@@ -192,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.3.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.3.0.gem`.
+installs without registry access: `gem install ./skaidb-1.4.1.gem`.
 
 ## Quick start
 
@@ -306,7 +306,10 @@ unordered or in storage-key order), and no scan budget applies to a streamed
 page (server ≥ 0.330). With a block `stream` returns a `Result` whose `kind`
 is `:stream` and whose `fields` are the column names (the rows went to the
 block); a non-row statement returns its `:mutation` / `:ddl` Result without
-yielding.
+yielding. A `CALL` whose body `EMIT`s result sets is answered with all of
+them in one frame even when streamed: the block receives the rows `exec`
+would return (the last set), and `stream` returns that same `Result`, every
+set under `result_sets`.
 
 **The abandon/drain rule.** The connection is busy for the whole stream:
 a statement from another thread waits for it. Leaving the block early —
@@ -356,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`)
 
@@ -458,7 +464,7 @@ frame after every handshake. It shows up as `client_name = 'ruby'` /
 
 ```sql
 SELECT client_name, client_version FROM drivers;
--- ruby | 1.3.0
+-- ruby | 1.4.1
 ```
 
 The server records the row asynchronously, so a `SELECT` immediately after

data/docs/api.md

@@ -67,7 +67,10 @@ Raises `Skaidb::Error` before dialing for an unknown `auth_mechanism`, a
   `ArgumentError`. For a row stream the returned Result has
   `kind == :stream`, the column names in `fields` and no `rows` (they went to
   the block); a statement without rows returns its `:mutation` / `:ddl`
-  Result without yielding. Without a block returns an Enumerator.
+  Result without yielding; a `CALL` whose body `EMIT`s result sets (answered
+  in one frame even when streamed) yields the rows `exec` would return (the
+  last set) and returns that same `:rows` Result, every set under
+  `result_sets`. Without a block returns an Enumerator.
 - `subscribe(stream_name, after: nil, poll: 0.5) { |event| … }` — yields a
   `CREATE STREAM` log's events forever, each a Hash with `"id"`, `"op"`,
   `"k"`, `"ts"`, `"doc"`. Polls `_stream_<name>` 500 rows at a time with a

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/docs/streaming.md

@@ -28,6 +28,12 @@ end
 - A non-row statement (an `INSERT`, DDL, `USE`) answers with its ordinary
   result over the same opcode; `stream` returns that Result (`kind`
   `:mutation` with `cmd_tuples`, or `:ddl`) without yielding.
+- A `CALL` whose procedure body `EMIT`s result sets answers with all of them
+  in one frame, as it does to `exec`: the block receives the rows `exec`
+  would return (the call's final result, the last set) and `stream` returns
+  that same `:rows` Result, every set in order under `result_sets`. Nothing
+  is left in flight, so the connection is free again before the first row
+  reaches the block.
 - A server without the streaming opcode raises `Skaidb::QueryError`
   (`server does not support streaming: …`).
 

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.3.0"
+  VERSION = "1.4.1"
 
   # Base class for every error raised by this driver.
   class Error < StandardError; end
@@ -973,7 +973,12 @@ module Skaidb
     # +kind+ is +:stream+ and +fields+ holds the column names (known even when
     # no row arrived) while +rows+ stays empty — the rows went to the block;
     # a statement that produces no rows returns its ordinary +:mutation+ or
-    # +:ddl+ Result without yielding.
+    # +:ddl+ Result without yielding. A CALL whose body EMITs result sets is
+    # answered with all of them in one frame, streamed or not: the block
+    # receives the rows exec's Result would yield (the call's final result,
+    # the LAST set) and the return value is that same +:rows+ Result, every
+    # set under +result_sets+ — with nothing left in flight, so the block may
+    # use the connection.
     def stream(sql, params = [], consistency: nil)
       return enum_for(:stream, sql, params, consistency: consistency) unless block_given?
       raise ConnectionError, "connection is closed" if @closed
@@ -991,6 +996,7 @@ module Skaidb
 
       live = false
       summary = nil
+      sets = nil
       @mutex.synchronize do
         started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         begin
@@ -1015,6 +1021,12 @@ module Skaidb
           return Result.new(fields: [], rows: [], cmd_tuples: r.u64, kind: :mutation) # not row-producing
         when 2
           return Result.new(fields: [], rows: [], cmd_tuples: 0, kind: :ddl)
+        when 8
+          # ResultSets: a CALL whose body EMITted is answered with every set
+          # in ONE frame, streamed or not — the frame exec receives, decoded
+          # by the same code. Nothing follows it, so the rows are yielded
+          # below, with the connection free.
+          sets = parse_result_sets(r)
         when 5
           # The server has already committed to a row stream, so from here
           # the socket carries frames this call owns — mark it BEFORE
@@ -1065,6 +1077,12 @@ module Skaidb
           raise QueryError, "unexpected response tag #{tag} to stream request"
         end
       end
+      if sets
+        # What exec's Result yields (the call's final result, the LAST set),
+        # and that same Result back, every set under +result_sets+.
+        sets.each { |row| yield row }
+        return sets
+      end
       summary
     end
 
@@ -1388,27 +1406,9 @@ module Skaidb
       tag = r.u8
       case tag
       when 0 # Rows
-        ncols = r.u32
-        columns = Array.new(ncols) { r.text }
-        nrows = r.u32
-        rows = Array.new(nrows) do
-          ncells = r.u32
-          Array.new(ncells) { Skaidb.decode_value(Reader.new(r.blob)) }
-        end
-        Result.new(fields: columns, rows: rows, cmd_tuples: 0)
+        parse_rows(r)
       when 8 # ResultSets: a CALL whose body EMITted
-        sets = Array.new(r.u32) do
-          ncols = r.u32
-          columns = Array.new(ncols) { r.text }
-          nrows = r.u32
-          rows = Array.new(nrows) do
-            ncells = r.u32
-            Array.new(ncells) { Skaidb.decode_value(Reader.new(r.blob)) }
-          end
-          Result.new(fields: columns, rows: rows, cmd_tuples: 0)
-        end
-        last = sets.last || Result.new(fields: [], rows: [], cmd_tuples: 0)
-        Result.new(fields: last.fields, rows: last.rows, cmd_tuples: 0, result_sets: sets)
+        parse_result_sets(r)
       when 1 # Mutation
         Result.new(fields: [], rows: [], cmd_tuples: r.u64, kind: :mutation)
       when 2 # Ddl
@@ -1419,6 +1419,29 @@ module Skaidb
         raise ConnectionError, "unknown response tag #{tag}"
       end
     end
+
+    # A Rows body (PROTOCOL.md §3.2), also one set of ResultSets; +r+ sits
+    # just past the tag.
+    def parse_rows(r)
+      ncols = r.u32
+      columns = Array.new(ncols) { r.text }
+      nrows = r.u32
+      rows = Array.new(nrows) do
+        ncells = r.u32
+        Array.new(ncells) { Skaidb.decode_value(Reader.new(r.blob)) }
+      end
+      Result.new(fields: columns, rows: rows, cmd_tuples: 0)
+    end
+
+    # A ResultSets body (a CALL whose body EMITted), +r+ just past the tag:
+    # the LAST set is the Result's own rows, every set is under
+    # +result_sets+. The buffered path and a stream request both receive
+    # this frame, and both decode it here.
+    def parse_result_sets(r)
+      sets = Array.new(r.u32) { parse_rows(r) }
+      last = sets.last || Result.new(fields: [], rows: [], cmd_tuples: 0)
+      Result.new(fields: last.fields, rows: last.rows, cmd_tuples: 0, result_sets: sets)
+    end
   end
 
   # ---- module entry point --------------------------------------------------
@@ -1545,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
@@ -1568,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
 
@@ -1585,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
@@ -1594,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
 
@@ -1764,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
@@ -1781,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
@@ -1986,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
@@ -2089,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.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - skaidb contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-29 00:00:00.000000000 Z
+date: 2026-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal