tarantool-client 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 239078d6bcc2b8d55971852a3af66f3b1db2e40822bfec113f81442d7946bf08
-  data.tar.gz: 8244a106fca7d641f7eaaf42377679de89ed2d1641d2c964f665d3bdff7953c9
+  metadata.gz: 046c9d293325df27a2971c6c6257cd6691e3e6c2cb565ea41eb9cb1aa5a2ccf3
+  data.tar.gz: 2dc134d5da8d6f5a99fd8b73f28340ae022ae9243c62d750287e35e5d088d159
 SHA512:
-  metadata.gz: c3fb785f1d6362c9f3a6e94f951b1c761b73152ea7b76d7b1666726b1e130892aada79ea38c7f46be339557e4000dee41da8db0e547e0ee47e8f1c3df76a8daf
-  data.tar.gz: 81fc563d05f48cc9cfa4d640fb00671d435951bea5cea85092394ab56914040967d99b89c0cc577bf6e37d71e0775c956060fe4fc5caecc4ec42941282e59495
+  metadata.gz: 8cb3cae463060a270127eea6427eacef15edd25ec159d6d377f97af2692d9fc7fade4fef6b871943cfe78387d740621c5061b583bfe2ae755ca06f8e8a7f282c
+  data.tar.gz: c456c5a8fa8a0c8de99804f29fd0c36831a35f692391c3cda7c582f1901fc7ee46cbf7fc709fed866bcba121b6fa4b5de6bbc4da6a5ea8ebe3e380f99a133a18

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.1 (2026-10-18)
+
+- Allows `bigdecimal` 4.x, the version Ruby 4 ships with.
+
+## 0.3.0 (2026-10-17)
+
+- `select(fetch_position: true)` returns a `Page` with the server-side position of the last tuple; `after:` takes that position (String) as well as a tuple.
+- Graceful shutdown: the client subscribes to `box.shutdown`; on the event it stops sending, a `Pool` member leaves the rotation, requests in flight finish, and the connection is closed by the client before the server stops (`shutdown.tarantool` event, `disconnect.tarantool` with the reason `server ... is shutting down`).
+
 ## 0.2.0 (2026-10-17)
 
 - `as: :hash` and `as: :row` on `select`, `insert`, `replace`, `update` and `delete` return tuples as Hashes by the space format (`Client::Row` keeps the raw tuple too); `SpaceInfo#to_hash` and `#to_tuple` do the conversion.

data/README.md

@@ -72,6 +72,16 @@ page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50)
 next_page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50, after: page.last)
 ```
 
+With `fetch_position: true` the server hands back a position instead, so the caller carries an opaque String rather than the last tuple (`IPROTO_FETCH_POSITION`, `IPROTO_POSITION`, `IPROTO_AFTER_POSITION`; 2.11+). `select` then returns a `Client::Page`: `tuples` (converted by `as:` as usual, also reachable through `each`), and `position`, nil once a page comes back empty. A position is tied to the index and iterator of the select that produced it; don't parse it or reuse it with another index. `after:` accepts a position (String) or a tuple (Array).
+
+```ruby
+page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50, fetch_position: true)
+until page.empty?
+  page.each { |user| ... }
+  page = client.select(:users, [18], index: :age, iterator: :ge, limit: 50, fetch_position: true, after: page.position)
+end
+```
+
 `delete_by` deletes every tuple a select finds, including by a non-unique index, which IPROTO `DELETE` can't do. It selects `batch_size` tuples at a time (default 1000), continues past the last one with `after:`, deletes each by primary key, and returns the number deleted. TREE indexes only, like `after:`. Multikey and functional indexes are not supported either: tuple-based `after` raises `ServerError` there, before deleting anything.
 
 ```ruby
@@ -188,6 +198,12 @@ pool.close
 
 Roles come from `box.status` (`is_ro`), so a switchover is picked up as soon as the instances report it. Requests are spread round-robin among matching instances. If none matches, the call raises `NoAvailableInstanceError`. `Pool.new` raises it only if no address answers; addresses that are down keep being retried in the background. That retrying covers start-up only: once connected, a member relies on its client's reconnect, so with a finite `reconnect_attempts` a member that gives up stays out of rotation. `Pool#close` may wait for an in-progress background connect attempt, up to `connect_timeout` + `request_timeout`. Options are passed to each client. A prepared statement from `pool.prepare` stays bound to the instance that prepared it.
 
+## Graceful shutdown
+
+Tarantool 2.10+ announces `SIGTERM` through the `box.shutdown` event and waits, up to `box.ctl.set_on_shutdown_timeout` (3 s by default), for the connections subscribed to it to close. Every `Client` subscribes. When the event arrives the client stops sending: `connected?` turns false, a `Pool` member leaves the rotation at once, and new requests on a bare `Client` wait for the next connection as they do while reconnecting. Requests already in flight get their replies; once none is left, or after `request_timeout`, the client closes the connection itself with the reason `server <address> is shutting down` and the usual reconnect follows. A transaction open on that connection fails on its next request, as after any loss. Nothing is retried elsewhere.
+
+Watching `box.shutdown` yourself works as before; the client's own subscription is never unwatched.
+
 ## Forking servers
 
 `Client` and `Pool` are fork-safe. The first request in a child process after `fork` reinitializes the connection transparently — a new socket is opened, background threads are restarted, and watchers are resubscribed. The parent's connection is unaffected.
@@ -227,6 +243,7 @@ Lifecycle events have the instance `address` too. Subscribers should be fast: `d
 | `reconnect_failed.tarantool` | `attempts` (when known), `exception`, `exception_object` | error |
 | `fork.tarantool` | | info |
 | `role_change.tarantool` | `read_only` (pool members) | info |
+| `shutdown.tarantool` | `pending` (requests in flight when the server announced its shutdown) | info |
 
 `role_change.tarantool` fires only when the role actually changes, not on the first report after connecting.
 
@@ -289,9 +306,11 @@ Don't create multikey indexes on these containers: with `memtx_use_mvcc_engine =
 ## Public API
 
 `Tarantool::Client`, `Tarantool::Client::Pool`, `Tarantool::Client::Stream` (yielded by `transaction`),
-`Watcher` (returned by `watch`), `SqlResult`, `PreparedStatement`, `SpaceInfo`, `IndexInfo`, `Row`, `Configuration`
+`Watcher` (returned by `watch`), `SqlResult`, `PreparedStatement`, `SpaceInfo`, `IndexInfo`, `Row`, `Page`, `Configuration`
 (returned by `client.config`), `Tarantool::Client::UUID`, `Interval`, `BoxError`, and the error classes above.
 
+RBS signatures for this API ship with the gem in `sig/`.
+
 Everything else, including anything tagged `@api private` in its source comment, is an implementation detail
 and may change in any release.
 

data/lib/tarantool/client/configuration.rb

@@ -24,15 +24,15 @@ module Tarantool
 
       def self.parse_uri(uri)
         return {} if uri.nil?
-        return parse_unix_uri(uri) if uri.match?(%r{\Aunix/?:})
+        return parse_unix_uri(uri) if uri.match?(Configuration::UNIX_URI)
 
         parse_tcp_uri(uri)
       end
 
       def self.parse_unix_uri(uri)
-        match = %r{\Aunix/?:(?://(?=/))?(.+)\z}.match(uri)
+        match = Configuration::UNIX_PATH.match(uri)
         path = match && match[1]
-        raise ArgumentError, 'invalid Tarantool URI' if path.nil? || path.match?(%r{\A/*\z})
+        raise ArgumentError, 'invalid Tarantool URI' if path.nil? || path.match?(Configuration::EMPTY_PATH)
 
         { path: path }
       end
@@ -84,5 +84,11 @@ module Tarantool
         klass.name ? "#<#{klass.name}>" : klass.inspect
       end
     end
+
+    class Configuration
+      UNIX_URI = %r{\Aunix/?:}
+      UNIX_PATH = %r{\Aunix/?:(?://(?=/))?(.+)\z}
+      EMPTY_PATH = %r{\A/*\z}
+    end
   end
 end

data/lib/tarantool/client/fork_safety.rb

@@ -27,16 +27,24 @@ module Tarantool
         nil
       end
 
-      # Watcher registrations outlive a fork; on_ready resubscribes them on the new link.
+      # Watcher registrations outlive a fork; on_ready resubscribes them on the new link, the shutdown
+      # subscription among them.
       def open_link
         @link = Transport::Link.new(@config, instrumentation: @instrumentation, **link_hooks)
         @watchers&.restart_after_fork(@link)
+        first = @watchers.nil?
         @watchers ||= Watchers.new(@link, timeout: @config.request_timeout)
         @link.event_handler = @watchers.method(:dispatch)
         @schema_cache = SchemaCache.new
         @stream_ids = Transport::StreamIds.new
         @link.connect
         @pid = Process.pid
+        subscribe_to_shutdown if first
+      end
+
+      # box.shutdown is true once the server starts stopping; the value on subscribing is nil before that.
+      def subscribe_to_shutdown
+        @watchers.add('box.shutdown', ->(_key, value) { @link.drain if value })
       end
     end
   end

data/lib/tarantool/client/instrumentation/log_lines.rb

@@ -8,7 +8,8 @@ module Tarantool
       module LogLines
         LEVELS = {
           'request.tarantool' => :debug, 'disconnect.tarantool' => :warn, 'reconnect.tarantool' => :info,
-          'reconnect_failed.tarantool' => :error, 'fork.tarantool' => :info, 'role_change.tarantool' => :info
+          'reconnect_failed.tarantool' => :error, 'fork.tarantool' => :info, 'role_change.tarantool' => :info,
+          'shutdown.tarantool' => :info
         }.freeze
 
         LINES = {
@@ -27,6 +28,9 @@ module Tarantool
           end,
           'role_change.tarantool' => lambda do |payload, _duration|
             "tarantool #{payload[:address]} is now #{payload[:read_only] ? 'read-only' : 'writable'}"
+          end,
+          'shutdown.tarantool' => lambda do |payload, _duration|
+            "tarantool #{payload[:address]} is shutting down, #{requests(payload[:pending])} in flight"
           end
         }.freeze
 
@@ -49,6 +53,7 @@ module Tarantool
         def request_name(payload) = payload[:request] ? "tarantool #{payload[:request]}" : 'tarantool'
 
         def attempts(count) = count == 1 ? '1 attempt' : "#{count} attempts"
+        def requests(count) = count == 1 ? '1 request' : "#{count} requests"
         def error(payload) = payload[:exception].join(': ')
 
         # The message may quote data (ER_TUPLE_FOUND repeats the tuple), so the request line keeps only the

data/lib/tarantool/client/operations.rb

@@ -19,10 +19,13 @@ module Tarantool
         lookup_space(space, timeout)
       end
 
+      # `after:` takes a tuple or a position; `fetch_position: true` returns a Page carrying the position instead
+      # of a plain Array.
       def select(space, key = [], index: 0, limit: Protocol::Constants::MAX_LIMIT, offset: 0, iterator: :eq,
-                 after: nil, as: :tuple, timeout: nil)
-        on_space(space, index, as:, timeout:) do |space_id, index_id|
-          Protocol::Requests::Select.new(space_id:, index_id:, key: key_tuple(key), limit:, offset:, iterator:, after:)
+                 after: nil, fetch_position: false, as: :tuple, timeout: nil)
+        on_space(space, index, as:, timeout:, page: fetch_position) do |space_id, index_id|
+          Protocol::Requests::Select.new(space_id:, index_id:, key: key_tuple(key), limit:, offset:, iterator:, after:,
+                                         fetch_position:)
         end
       end
 
@@ -99,7 +102,7 @@ module Tarantool
       private
 
       # A retry after a schema change calls the block again, so the SpaceInfo kept is the one the response came from.
-      def on_space(space, index, as:, timeout:, format: false)
+      def on_space(space, index, as:, timeout:, format: false, page: false)
         TupleShape.check(as)
         space_info = nil
         needs_format = format || as != :tuple
@@ -107,8 +110,9 @@ module Tarantool
           space_info = info
           yield space_id, index_id, info
         end
+        tuples = response.data.map { |tuple| TupleShape.apply(as, tuple, space_info) }
 
-        response.data.map { |tuple| TupleShape.apply(as, tuple, space_info) }
+        page ? Page.new(tuples:, position: response.position) : tuples
       end
 
       def tuple_for(tuple, space_info) = tuple.is_a?(Hash) ? space_info.to_tuple(tuple) : tuple

data/lib/tarantool/client/page.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # One page of a select asked with `fetch_position: true`: the tuples (converted by `as:`) and the position to
+    # continue after with `after:`, nil when the page is empty. Opaque: tied to the index and iterator that
+    # produced it.
+    Page = Data.define(:tuples, :position) do
+      include Enumerable
+
+      def each(&) = tuples.each(&)
+
+      def empty? = tuples.empty?
+
+      def size = tuples.size
+    end
+  end
+end

data/lib/tarantool/client/pool/member_role.rb

@@ -3,8 +3,8 @@
 module Tarantool
   class Client
     class Pool
-      # The role a member's instance reports through box.status. Includers set @lock, @changed, @read_only and
-      # @instrumentation.
+      # The role a member's instance reports through box.status. Includers set @lock, @changed, @read_only
+      # and @instrumentation.
       # @api private
       module MemberRole
         private

data/lib/tarantool/client/protocol/constants.rb

@@ -17,16 +17,19 @@ module Tarantool
         LIMIT = 0x12
         OFFSET = 0x13
         ITERATOR = 0x14
+        FETCH_POSITION = 0x1f
         KEY = 0x20
         TUPLE = 0x21
         FUNCTION_NAME = 0x22
         USER_NAME = 0x23
         EXPR = 0x27
         OPS = 0x28
+        AFTER_POSITION = 0x2e
         AFTER_TUPLE = 0x2f
         DATA = 0x30
         ERROR_24 = 0x31
         METADATA = 0x32
+        POSITION = 0x35
         SQL_TEXT = 0x40
         SQL_BIND = 0x41
         SQL_INFO = 0x42

data/lib/tarantool/client/protocol/greeting.rb

@@ -6,8 +6,6 @@ module Tarantool
       # Greeting sent by the server on connect: a 64-byte banner and a 64-byte base64 salt line.
       # @api private
       Greeting = Data.define(:version, :salt) do
-        self::BANNER_VERSION = /\ATarantool (\S+)/
-
         def self.parse(bytes)
           banner = bytes.byteslice(0, 64)
           version = banner[Greeting::BANNER_VERSION, 1]
@@ -16,6 +14,10 @@ module Tarantool
           new(version:, salt: bytes.byteslice(64, 64).strip.unpack1('m'))
         end
       end
+
+      class Greeting
+        BANNER_VERSION = /\ATarantool (\S+)/
+      end
     end
   end
 end

data/lib/tarantool/client/protocol/requests/select.rb

@@ -4,11 +4,17 @@ module Tarantool
   class Client
     module Protocol
       module Requests
-        # IPROTO_SELECT: index lookup or scan. `after` continues past a tuple (keyset pagination, 2.11+).
+        # IPROTO_SELECT: index lookup or scan. `after` continues past a tuple (Array) or a position (String, from
+        # a response asked with `fetch_position`); keyset pagination, 2.11+.
         # @api private
-        Select = Data.define(:space_id, :index_id, :key, :limit, :offset, :iterator, :after) do
-          def initialize(iterator:, after: nil, **)
+        Select = Data.define(:space_id, :index_id, :key, :limit, :offset, :iterator, :after, :fetch_position) do
+          def self.cursor?(after) = after.nil? || after.is_a?(Array) || after.is_a?(String)
+
+          def initialize(iterator:, after: nil, fetch_position: false, **)
             raise ArgumentError, "unknown iterator: #{iterator.inspect}" unless Constants::ITERATORS.key?(iterator)
+            unless Select.cursor?(after)
+              raise ArgumentError, "after: expected a tuple (Array) or a position (String), got #{after.inspect}"
+            end
 
             super
           end
@@ -22,8 +28,19 @@ module Tarantool
               Constants::LIMIT => limit,
               Constants::OFFSET => offset,
               Constants::ITERATOR => Constants::ITERATORS.fetch(iterator),
-              Constants::KEY => key
-            }.tap { |body| body[Constants::AFTER_TUPLE] = after unless after.nil? }
+              Constants::KEY => key,
+              **pagination
+            }
+          end
+
+          private
+
+          def pagination
+            keys = {}
+            keys[after.is_a?(String) ? Constants::AFTER_POSITION : Constants::AFTER_TUPLE] = after unless after.nil?
+            keys[Constants::FETCH_POSITION] = true if fetch_position
+
+            keys
           end
         end
       end

data/lib/tarantool/client/protocol/response.rb

@@ -17,6 +17,7 @@ module Tarantool
         def sync = header[Constants::SYNC]
         def schema_version = header[Constants::SCHEMA_VERSION]
         def data = body[Constants::DATA]
+        def position = body[Constants::POSITION]
         def error? = type.anybits?(Constants::TYPE_ERROR)
         def push? = type == Constants::CHUNK
         def event? = type == Constants::EVENT

data/lib/tarantool/client/transport/connection.rb

@@ -58,6 +58,14 @@ module Tarantool
           !@pending.failure.nil?
         end
 
+        def in_flight = @pending.size
+
+        # True once every request got its answer, false at the deadline.
+        def wait_idle(timeout) = @pending.wait_empty(timeout)
+
+        # Ends the connection on the client's initiative with a reason the requests and the disconnect handler see.
+        def shut_down(reason) = break_connection(reason)
+
         def failure = @pending.failure
 
         private

data/lib/tarantool/client/transport/link.rb

@@ -5,16 +5,16 @@ module Tarantool
     module Transport
       # Keeps one instance connected. Owns the current Connection; once it is lost, a background thread
       # opens new ones with backoff while requests wait for one to become ready.
-      # States: connecting -> ready -> reconnecting -> closed.
+      # States: connecting -> ready -> draining | reconnecting -> closed.
       # @api private
       class Link
         include LinkEvents
+        include LinkDraining
 
         attr_writer :event_handler
 
-        # on_connect runs on each new connection before requests can use it and may raise to fail the
-        # attempt; on_ready runs once the connection is current; on_lost runs when a reconnect starts,
-        # before its first attempt.
+        # on_connect runs on each new connection before requests can use it and may raise to fail the attempt;
+        # on_ready runs once the connection is current; on_lost runs when a reconnect starts, before its first attempt.
         def initialize(config, on_connect:, on_ready:, on_lost: nil, backoff: nil, instrumentation: nil)
           @config = config
           @on_connect = on_connect
@@ -52,14 +52,16 @@ module Tarantool
         def greeting = @state.connection.greeting
         def connected? = @state.connected?
 
-        # Closing the attempt first fails a handshake or on_connect blocked on it, so the join is short.
+        # Closing the attempt first fails a handshake or on_connect blocked on it, so the join is short. Closing
+        # the connection wakes the drain thread, so it is joined last.
         def close
-          reconnector, attempt = @state.close
+          reconnector, attempt, drainer = @state.close
           attempt&.close
           begin
             ThreadJoin.join(reconnector)
           ensure
             @state.connection&.close
+            ThreadJoin.join(drainer)
           end
 
           nil
@@ -137,13 +139,6 @@ module Tarantool
         rescue StandardError => e
           e
         end
-
-        # A failing hook is the caller's bug, not a reason to stop reconnecting or to drop the new connection.
-        def run_hook(name)
-          yield
-        rescue StandardError => e
-          Diagnostics.warn(@config.logger, "#{name} failed for #{@config.address}: #{e.full_message}")
-        end
       end
     end
   end

data/lib/tarantool/client/transport/link_draining.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # Graceful shutdown of a Link's connection. Includers set @config and @state, and provide #emit.
+      # @api private
+      module LinkDraining
+        # The server announced its shutdown and waits for this connection to close: new requests wait for the
+        # next connection, in-flight ones finish, then the connection is closed and its loss handled as usual.
+        def drain
+          connection = @state.connection
+
+          @state.start_draining(connection) do
+            Thread.new { drain_connection(connection) }.tap do |thread|
+              thread.name = "tarantool-drain #{@config.address}"
+            end
+          end
+        end
+
+        private
+
+        # Without reconnect the drained connection becomes current again so requests fail with its reason.
+        def drain_connection(connection)
+          emit('shutdown.tarantool', pending: connection.in_flight)
+          connection.wait_idle(@config.request_timeout)
+          @state.finish_draining(connection) unless @config.reconnect
+          connection.shut_down("server #{@config.address} is shutting down")
+        rescue StandardError => e
+          Diagnostics.warn(@config.logger, "drain failed for #{@config.address}: #{e.full_message}")
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/transport/link_events.rb

@@ -3,12 +3,19 @@
 module Tarantool
   class Client
     module Transport
-      # Lifecycle events of a Link. Includers set @config, @state and @instrumentation, and provide
-      # #run_hook and #install.
+      # Lifecycle events and hooks of a Link. Includers set @config, @state and @instrumentation, and provide
+      # #install.
       # @api private
       module LinkEvents
         private
 
+        # A failing hook is the caller's bug, not a reason to stop reconnecting or to drop the new connection.
+        def run_hook(name)
+          yield
+        rescue StandardError => e
+          Diagnostics.warn(@config.logger, "#{name} failed for #{@config.address}: #{e.full_message}")
+        end
+
         # Without reconnect the link keeps the lost connection, so the loss of the current one is all to
         # report. The reader thread's disconnect handler and install's own loss check can both reach this
         # for the same connection, so LinkState claims the loss once.

data/lib/tarantool/client/transport/link_state.rb

@@ -52,11 +52,34 @@ module Tarantool
           end
         end
 
-        # Leaves ready only for the current connection, so a loss is handled once. The block gets the previous
-        # reconnect thread and returns the new one; the state flips only once that thread exists.
+        # The server announced its shutdown: requests wait as while reconnecting, in-flight ones finish on the
+        # connection. The block returns the drain thread; only the current connection drains, once.
+        def start_draining(connection)
+          @lock.synchronize do
+            next false unless @state == :ready && @connection.equal?(connection)
+
+            @drainer = yield
+            @state = :draining
+            @changed.broadcast
+            true
+          end
+        end
+
+        # Without reconnect the drained connection stays current, failing requests with the shutdown reason.
+        def finish_draining(connection)
+          @lock.synchronize do
+            next unless @state == :draining && @connection.equal?(connection)
+
+            @state = :ready
+            @changed.broadcast
+          end
+        end
+
+        # Leaves ready or draining only for the current connection, so a loss is handled once. The block gets
+        # the previous reconnect thread and returns the new one; the state flips only once that thread exists.
         def start_reconnect(connection)
           @lock.synchronize do
-            next unless @state == :ready && @connection.equal?(connection)
+            next unless %i[ready draining].include?(@state) && @connection.equal?(connection)
 
             @reconnector = yield @reconnector
             @state = :reconnecting
@@ -64,7 +87,8 @@ module Tarantool
           end
         end
 
-        # Returns the reconnect thread and the connection it is opening, for the caller to abort and join.
+        # Returns the reconnect thread, the connection it is opening and the drain thread, for the caller to
+        # abort and join.
         def close
           @lock.synchronize do
             @error = ClientClosedError.new("connection to #{@address} closed")
@@ -72,7 +96,7 @@ module Tarantool
               @state = :closed
               @changed.broadcast
             end
-            [@reconnector, @attempt]
+            [@reconnector, @attempt, @drainer]
           end
         end
 

data/lib/tarantool/client/transport/pending_requests.rb

@@ -8,6 +8,7 @@ module Tarantool
       class PendingRequests
         def initialize
           @lock = Mutex.new
+          @emptied = ConditionVariable.new
           @futures = {}
           @last_sync = 0
           @failure = nil
@@ -31,7 +32,32 @@ module Tarantool
         end
 
         def delete(sync)
-          @lock.synchronize { @futures.delete(sync) }
+          @lock.synchronize do
+            future = @futures.delete(sync)
+            @emptied.broadcast if @futures.empty?
+
+            future
+          end
+        end
+
+        def size
+          @lock.synchronize { @futures.size }
+        end
+
+        # True once no request is in flight, false at the deadline.
+        def wait_empty(timeout)
+          deadline = Deadline.after(timeout)
+
+          @lock.synchronize do
+            until @futures.empty?
+              remaining = Deadline.remaining(deadline)
+              return false if remaining&.zero?
+
+              @emptied.wait(@lock, remaining)
+            end
+
+            true
+          end
         end
 
         def failure
@@ -43,6 +69,7 @@ module Tarantool
           first, failure, futures = @lock.synchronize do
             first = @failure.nil?
             @failure ||= error
+            @emptied.broadcast
             [first, @failure, @futures.values.tap { @futures.clear }]
           end
           futures.each { |future| future.reject(failure) }

data/lib/tarantool/client/uuid.rb

@@ -4,8 +4,6 @@ module Tarantool
   class Client
     # A Tarantool uuid value; only instances of this type are sent as MP_EXT uuid, never plain strings.
     UUID = Data.define(:value) do
-      self::FORMAT = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
-
       def initialize(value:)
         raise ArgumentError, "invalid UUID: #{value.inspect}" unless value.is_a?(String) && value.match?(UUID::FORMAT)
 
@@ -16,5 +14,9 @@ module Tarantool
         value
       end
     end
+
+    class UUID
+      FORMAT = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+    end
   end
 end

data/lib/tarantool/client/version.rb

@@ -2,6 +2,6 @@
 
 module Tarantool
   class Client
-    VERSION = '0.2.0'
+    VERSION = '0.3.1'
   end
 end

data/lib/tarantool/client.rb

@@ -58,6 +58,7 @@ require_relative 'client/transport/handshake'
 require_relative 'client/transport/connection'
 require_relative 'client/transport/link_state'
 require_relative 'client/transport/link_events'
+require_relative 'client/transport/link_draining'
 require_relative 'client/transport/link'
 require_relative 'client/index_info'
 require_relative 'client/tuple_mapping'
@@ -69,6 +70,7 @@ require_relative 'client/prepared_statement'
 require_relative 'client/batch_delete'
 require_relative 'client/transaction_schema'
 require_relative 'client/row'
+require_relative 'client/page'
 require_relative 'client/tuple_shape'
 require_relative 'client/operations'
 require_relative 'client/transaction_scope'

data/sig/tarantool/client/pool.rbs

@@ -0,0 +1,41 @@
+module Tarantool
+  class Client
+    # Clients for the instances of one replica set, routed by the role each reports through box.status.
+    class Pool
+      type mode = :rw | :ro | :prefer_ro | :prefer_rw | :any
+
+      MODES: Array[mode]
+
+      def initialize: (Array[String] addresses, ?host: String, ?port: Integer, ?path: String?, ?user: String?,
+                       ?password: String?, ?connect_timeout: Numeric?, ?request_timeout: Numeric?, ?reconnect: bool,
+                       ?reconnect_attempts: Numeric, ?reconnect_delay: Numeric, ?reconnect_max_delay: Numeric,
+                       ?max_frame_size: Integer, ?instrumenter: _Instrumenter?, ?logger: _Logger?) -> void
+
+      def ping: (?mode: mode, ?timeout: Numeric?) -> true
+      def space_info: (space_ref space, ?mode: mode, ?timeout: Numeric?) -> SpaceInfo
+      def select: (space_ref space, ?key key, ?mode: mode, ?index: index_ref, ?limit: Integer, ?offset: Integer,
+                   ?iterator: iterator, ?after: cursor?, ?fetch_position: bool, ?as: shape,
+                   ?timeout: Numeric?) -> (Array[row] | Page)
+      def insert: (space_ref space, tuple_input tuple, ?mode: mode, ?as: shape, ?timeout: Numeric?) -> row
+      def replace: (space_ref space, tuple_input tuple, ?mode: mode, ?as: shape, ?timeout: Numeric?) -> row
+      def update: (space_ref space, key key, Array[operation] operations, ?mode: mode, ?index: index_ref, ?as: shape,
+                   ?timeout: Numeric?) -> row?
+      def upsert: (space_ref space, tuple_input tuple, Array[operation] operations, ?mode: mode,
+                   ?timeout: Numeric?) -> nil
+      def delete: (space_ref space, key key, ?mode: mode, ?index: index_ref, ?as: shape, ?timeout: Numeric?) -> row?
+      def delete_by: (space_ref space, key key, index: index_ref, ?mode: mode, ?iterator: iterator,
+                      ?batch_size: Integer, ?timeout: Numeric?) -> Integer
+      def call: (String function_name, ?Array[untyped] arguments, ?mode: mode, ?timeout: Numeric?,
+                 ?on_push: (^(untyped message) -> void)?) -> Array[untyped]
+      def eval: (String expression, ?Array[untyped] arguments, ?mode: mode, ?timeout: Numeric?) -> Array[untyped]
+      def execute: (String | Integer | PreparedStatement sql, ?Array[untyped] bindings, ?mode: mode,
+                    ?timeout: Numeric?) -> SqlResult
+      def prepare: (String sql, ?mode: mode, ?timeout: Numeric?) -> PreparedStatement
+
+      # Always on a writable instance.
+      def transaction: [T] (?isolation: isolation, ?timeout: Numeric?) { (Stream) -> T } -> T
+      def close: () -> void
+      def inspect: () -> String
+    end
+  end
+end

data/sig/tarantool/client/stream.rbs

@@ -0,0 +1,26 @@
+module Tarantool
+  class Client
+    # The operations of one interactive transaction, yielded by Client#transaction and Pool#transaction.
+    class Stream
+      def ping: (?timeout: Numeric?) -> true
+      def space_info: (space_ref space, ?timeout: Numeric?) -> SpaceInfo
+      def select: (space_ref space, ?key key, ?index: index_ref, ?limit: Integer, ?offset: Integer,
+                   ?iterator: iterator, ?after: cursor?, ?fetch_position: bool, ?as: shape,
+                   ?timeout: Numeric?) -> (Array[row] | Page)
+      def insert: (space_ref space, tuple_input tuple, ?as: shape, ?timeout: Numeric?) -> row
+      def replace: (space_ref space, tuple_input tuple, ?as: shape, ?timeout: Numeric?) -> row
+      def update: (space_ref space, key key, Array[operation] operations, ?index: index_ref, ?as: shape,
+                   ?timeout: Numeric?) -> row?
+      def upsert: (space_ref space, tuple_input tuple, Array[operation] operations, ?timeout: Numeric?) -> nil
+      def delete: (space_ref space, key key, ?index: index_ref, ?as: shape, ?timeout: Numeric?) -> row?
+      def delete_by: (space_ref space, key key, index: index_ref, ?iterator: iterator, ?batch_size: Integer,
+                      ?timeout: Numeric?) -> Integer
+      def call: (String function_name, ?Array[untyped] arguments, ?timeout: Numeric?,
+                 ?on_push: (^(untyped message) -> void)?) -> Array[untyped]
+      def eval: (String expression, ?Array[untyped] arguments, ?timeout: Numeric?) -> Array[untyped]
+      def execute: (String | Integer | PreparedStatement sql, ?Array[untyped] bindings, ?timeout: Numeric?) -> SqlResult
+      # Raises TransactionError: prepare on the client, execute the statement here.
+      def prepare: (*untyped) -> bot
+    end
+  end
+end

data/sig/tarantool/client/values.rbs

@@ -0,0 +1,179 @@
+module Tarantool
+  class Client
+    # Subscription returned by Client#watch.
+    class Watcher
+      attr_reader key: String
+
+      def unwatch: () -> nil
+    end
+
+    # Server-side prepared SQL statement, bound to the session that prepared it.
+    class PreparedStatement
+      attr_reader id: Integer
+
+      def execute: (?Array[untyped] bindings, ?timeout: Numeric?) -> SqlResult
+      def close: (?timeout: Numeric?) -> nil
+    end
+
+    # Rows and column names of an SQL query, or the counters of a data-changing statement.
+    class SqlResult < Data
+      attr_reader rows: Array[Array[untyped]]
+      attr_reader columns: Array[String]
+      attr_reader row_count: Integer?
+      attr_reader autoincrement_ids: Array[Integer]
+
+      def self.new: (rows: Array[Array[untyped]], columns: Array[String], row_count: Integer?,
+                     autoincrement_ids: Array[Integer]) -> SqlResult
+      def with: (?rows: Array[Array[untyped]], ?columns: Array[String], ?row_count: Integer?,
+                 ?autoincrement_ids: Array[Integer]) -> SqlResult
+    end
+
+    # A tuple as the server returned it, with its fields by name. Returned for `as: :row`.
+    class Row < Data
+      attr_reader tuple: tuple
+      attr_reader attributes: row_hash
+
+      def self.new: (tuple: tuple, attributes: row_hash) -> Row
+      def with: (?tuple: tuple, ?attributes: row_hash) -> Row
+    end
+
+    # One page of a select asked with `fetch_position: true`.
+    class Page < Data
+      include Enumerable[row]
+
+      attr_reader tuples: Array[row]
+      # Opaque, tied to the index and iterator that produced it; nil when the page is empty.
+      attr_reader position: String?
+
+      def self.new: (tuples: Array[row], position: String?) -> Page
+      def with: (?tuples: Array[row], ?position: String?) -> Page
+      def each: () { (row) -> void } -> Array[row]
+              | () -> Enumerator[row, Array[row]]
+      def empty?: () -> bool
+      def size: () -> Integer
+    end
+
+    # Format and indexes of a space from the loaded schema; `indexes` maps names to IndexInfo in id order.
+    class SpaceInfo < Data
+      attr_reader id: Integer
+      attr_reader name: String
+      attr_reader fields: Array[SpaceInfo::Field]
+      attr_reader indexes: Hash[String, IndexInfo]
+
+      def self.new: (id: Integer, name: String, fields: Array[SpaceInfo::Field], indexes: Hash[String, IndexInfo]) -> SpaceInfo
+      def with: (?id: Integer, ?name: String, ?fields: Array[SpaceInfo::Field], ?indexes: Hash[String, IndexInfo]) -> SpaceInfo
+      def primary_index: () -> IndexInfo?
+      def to_hash: (tuple tuple) -> row_hash
+      # An unknown name raises UnknownFieldError; missing fields go out as nil.
+      def to_tuple: (Hash[Symbol | String | Integer, untyped] hash) -> tuple
+
+      class Field < Data
+        attr_reader name: String
+        attr_reader type: String
+        attr_reader is_nullable: bool
+
+        def self.new: (name: String, type: String, is_nullable: bool) -> Field
+        def with: (?name: String, ?type: String, ?is_nullable: bool) -> Field
+      end
+    end
+
+    # One index of a space.
+    class IndexInfo < Data
+      attr_reader id: Integer
+      attr_reader name: String
+      attr_reader type: String
+      attr_reader unique: bool
+      attr_reader parts: Array[IndexInfo::Part]
+
+      def self.new: (id: Integer, name: String, type: String, unique: bool, parts: Array[IndexInfo::Part]) -> IndexInfo
+      def with: (?id: Integer, ?name: String, ?type: String, ?unique: bool, ?parts: Array[IndexInfo::Part]) -> IndexInfo
+
+      # `fieldno` is 0-based; `name` is nil for a field beyond the space format.
+      class Part < Data
+        attr_reader fieldno: Integer
+        attr_reader name: String?
+        attr_reader type: String
+        attr_reader is_nullable: bool
+        attr_reader path: String?
+
+        def self.new: (fieldno: Integer, name: String?, type: String, is_nullable: bool, path: String?) -> Part
+        def with: (?fieldno: Integer, ?name: String?, ?type: String, ?is_nullable: bool, ?path: String?) -> Part
+      end
+    end
+
+    # A Tarantool uuid; only instances of this type are sent as MP_EXT uuid.
+    class UUID < Data
+      FORMAT: Regexp
+
+      attr_reader value: String
+
+      def self.new: (String value) -> UUID
+                  | (value: String) -> UUID
+      def with: (?value: String) -> UUID
+      def to_s: () -> String
+    end
+
+    # A Tarantool datetime.interval; adjust is :none, :excess or :last.
+    class Interval < Data
+      type adjust = :none | :excess | :last
+
+      attr_reader year: Integer
+      attr_reader month: Integer
+      attr_reader week: Integer
+      attr_reader day: Integer
+      attr_reader hour: Integer
+      attr_reader min: Integer
+      attr_reader sec: Integer
+      attr_reader nsec: Integer
+      attr_reader adjust: adjust
+
+      def self.new: (?year: Integer, ?month: Integer, ?week: Integer, ?day: Integer, ?hour: Integer, ?min: Integer,
+                     ?sec: Integer, ?nsec: Integer, ?adjust: adjust) -> Interval
+      def with: (?year: Integer, ?month: Integer, ?week: Integer, ?day: Integer, ?hour: Integer, ?min: Integer,
+                 ?sec: Integer, ?nsec: Integer, ?adjust: adjust) -> Interval
+    end
+
+    # A box.error object returned as data (MP_ERROR), with its cause chain.
+    class BoxError < Data
+      attr_reader type: String?
+      attr_reader message: String?
+      attr_reader code: Integer?
+      attr_reader file: String?
+      attr_reader line: Integer?
+      attr_reader errno: Integer?
+      attr_reader fields: Hash[String, untyped]?
+      attr_reader cause: BoxError?
+
+      def self.new: (type: String?, message: String?, code: Integer?, file: String?, line: Integer?, errno: Integer?,
+                     fields: Hash[String, untyped]?, cause: BoxError?) -> BoxError
+      def with: (?type: String?, ?message: String?, ?code: Integer?, ?file: String?, ?line: Integer?, ?errno: Integer?,
+                 ?fields: Hash[String, untyped]?, ?cause: BoxError?) -> BoxError
+    end
+
+    # Immutable connection settings; `inspect` and `to_s` hide the password, `to_h` keeps it.
+    class Configuration < Data
+      attr_reader host: String
+      attr_reader port: Integer
+      attr_reader path: String?
+      attr_reader user: String?
+      attr_reader password: String?
+      attr_reader connect_timeout: Numeric?
+      attr_reader request_timeout: Numeric?
+      attr_reader reconnect: bool
+      attr_reader reconnect_attempts: Numeric
+      attr_reader reconnect_delay: Numeric
+      attr_reader reconnect_max_delay: Numeric
+      attr_reader max_frame_size: Integer
+      attr_reader instrumenter: _Instrumenter?
+      attr_reader logger: _Logger?
+
+      def self.build: (?String? uri, ?host: String, ?port: Integer, ?path: String?, ?user: String?, ?password: String?,
+                       ?connect_timeout: Numeric?, ?request_timeout: Numeric?, ?reconnect: bool,
+                       ?reconnect_attempts: Numeric, ?reconnect_delay: Numeric, ?reconnect_max_delay: Numeric,
+                       ?max_frame_size: Integer, ?instrumenter: _Instrumenter?, ?logger: _Logger?) -> Configuration
+      def address: () -> String
+      def inspect: () -> String
+      def to_s: () -> String
+    end
+  end
+end

data/sig/tarantool/client.rbs

@@ -0,0 +1,73 @@
+module Tarantool
+  # Connection to one Tarantool instance.
+  class Client
+    VERSION: String
+
+    # A space or index, by name or numeric id.
+    type space_ref = String | Symbol | Integer
+    type index_ref = String | Symbol | Integer
+    # A tuple as sent and received: an Array of msgpack values.
+    type tuple = Array[untyped]
+    # A tuple keyed by field name; fields beyond the format are keyed by their 0-based position.
+    type row_hash = Hash[Symbol | Integer, untyped]
+    # Tuples go out as Arrays or as Hashes keyed by field name (Symbol or String).
+    type tuple_input = tuple | Hash[Symbol | String, untyped]
+    # One msgpack value of a key part.
+    type scalar = Integer | Float | String | bool | nil | BigDecimal | Time | UUID | Interval
+    # An index key: the parts as an Array, or one scalar for a single-part key.
+    type key = Array[untyped] | scalar
+    type iterator = :eq | :req | :all | :lt | :le | :ge | :gt | :bits_all_set | :bits_any_set | :bits_all_not_set |
+                    :overlaps | :neighbor | :np | :pp
+    type shape = :tuple | :hash | :row
+    # One update operation, e.g. ['=', 'name', value] or ['+', 2, 1]; splice operations have five elements.
+    type operation = Array[untyped]
+    # What select returns for one tuple, by `as:`.
+    type row = tuple | row_hash | Row
+    type isolation = :default | :read_committed | :read_confirmed | :best_effort | :linearizable
+    # A position from Page#position, or the last tuple of the previous page.
+    type cursor = String | tuple
+
+    interface _Instrumenter
+      def instrument: (String name, Hash[Symbol, untyped] payload) { () -> untyped } -> untyped
+    end
+
+    interface _Logger
+      def debug: (?untyped message) ?{ () -> untyped } -> untyped
+      def info: (?untyped message) ?{ () -> untyped } -> untyped
+      def warn: (?untyped message) ?{ () -> untyped } -> untyped
+      def error: (?untyped message) ?{ () -> untyped } -> untyped
+    end
+
+    attr_reader config: Configuration
+
+    def initialize: (?String? uri, ?host: String, ?port: Integer, ?path: String?, ?user: String?, ?password: String?,
+                     ?connect_timeout: Numeric?, ?request_timeout: Numeric?, ?reconnect: bool,
+                     ?reconnect_attempts: Numeric, ?reconnect_delay: Numeric, ?reconnect_max_delay: Numeric,
+                     ?max_frame_size: Integer, ?instrumenter: _Instrumenter?, ?logger: _Logger?) -> void
+
+    def ping: (?timeout: Numeric?) -> true
+    def space_info: (space_ref space, ?timeout: Numeric?) -> SpaceInfo
+    def select: (space_ref space, ?key key, ?index: index_ref, ?limit: Integer, ?offset: Integer, ?iterator: iterator,
+                 ?after: cursor?, ?fetch_position: bool, ?as: shape, ?timeout: Numeric?) -> (Array[row] | Page)
+    def insert: (space_ref space, tuple_input tuple, ?as: shape, ?timeout: Numeric?) -> row
+    def replace: (space_ref space, tuple_input tuple, ?as: shape, ?timeout: Numeric?) -> row
+    def update: (space_ref space, key key, Array[operation] operations, ?index: index_ref, ?as: shape,
+                 ?timeout: Numeric?) -> row?
+    def upsert: (space_ref space, tuple_input tuple, Array[operation] operations, ?timeout: Numeric?) -> nil
+    def delete: (space_ref space, key key, ?index: index_ref, ?as: shape, ?timeout: Numeric?) -> row?
+    def delete_by: (space_ref space, key key, index: index_ref, ?iterator: iterator, ?batch_size: Integer,
+                    ?timeout: Numeric?) -> Integer
+    def call: (String function_name, ?Array[untyped] arguments, ?timeout: Numeric?,
+               ?on_push: (^(untyped message) -> void)?) -> Array[untyped]
+    def eval: (String expression, ?Array[untyped] arguments, ?timeout: Numeric?) -> Array[untyped]
+    def execute: (String | Integer | PreparedStatement sql, ?Array[untyped] bindings, ?timeout: Numeric?) -> SqlResult
+    def prepare: (String sql, ?timeout: Numeric?) -> PreparedStatement
+
+    def server_version: () -> String
+    def connected?: () -> bool
+    def transaction: [T] (?isolation: isolation, ?timeout: Numeric?) { (Stream) -> T } -> T
+    def watch: (String key) { (String key, untyped value) -> void } -> Watcher
+    def close: () -> void
+    def inspect: () -> String
+  end
+end

data/sig/tarantool/errors.rbs

@@ -0,0 +1,47 @@
+module Tarantool
+  # Base class for every error raised by the tarantool-* gems.
+  class Error < StandardError
+    # Rows delete_by confirmed deleted before it failed; nil for any other operation.
+    attr_accessor deleted: Integer?
+  end
+
+  class ConnectionError < Error
+  end
+
+  class ClientClosedError < ConnectionError
+  end
+
+  class TimeoutError < Error
+  end
+
+  class AuthenticationError < Error
+    attr_reader code: Integer?
+
+    def initialize: (?String? message, ?code: Integer?) -> void
+  end
+
+  class ProtocolError < Error
+  end
+
+  class SchemaError < Error
+  end
+
+  class UnknownFieldError < ArgumentError
+  end
+
+  class TransactionError < Error
+  end
+
+  class NoAvailableInstanceError < Error
+  end
+
+  class ServerError < Error
+    attr_reader code: Integer
+    # The box.error stack as sent: one Hash per error (keys :type, :file, :line, :message, :errno, :code,
+    # :fields); the constructor takes whatever Array it is given.
+    attr_reader error_stack: Array[untyped]
+    attr_reader schema_version: Integer?
+
+    def initialize: (String? message, code: Integer, ?error_stack: Array[untyped], ?schema_version: Integer?) -> void
+  end
+end

metadata

@@ -1,29 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: tarantool-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Starlexxx
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: msgpack
   requirement: !ruby/object:Gem::Requirement
@@ -68,6 +74,7 @@ files:
 - lib/tarantool/client/interval.rb
 - lib/tarantool/client/named_requests.rb
 - lib/tarantool/client/operations.rb
+- lib/tarantool/client/page.rb
 - lib/tarantool/client/pool.rb
 - lib/tarantool/client/pool/member.rb
 - lib/tarantool/client/pool/member_fork_safety.rb
@@ -117,6 +124,7 @@ files:
 - lib/tarantool/client/transport/future.rb
 - lib/tarantool/client/transport/handshake.rb
 - lib/tarantool/client/transport/link.rb
+- lib/tarantool/client/transport/link_draining.rb
 - lib/tarantool/client/transport/link_events.rb
 - lib/tarantool/client/transport/link_state.rb
 - lib/tarantool/client/transport/pending_requests.rb
@@ -130,6 +138,11 @@ files:
 - lib/tarantool/client/watcher.rb
 - lib/tarantool/client/watchers.rb
 - lib/tarantool/client/watchers/dispatcher.rb
+- sig/tarantool/client.rbs
+- sig/tarantool/client/pool.rbs
+- sig/tarantool/client/stream.rbs
+- sig/tarantool/client/values.rbs
+- sig/tarantool/errors.rbs
 homepage: https://github.com/Starlexxx/tarantool-ruby
 licenses:
 - MIT