tarantool-client 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 239078d6bcc2b8d55971852a3af66f3b1db2e40822bfec113f81442d7946bf08
-  data.tar.gz: 8244a106fca7d641f7eaaf42377679de89ed2d1641d2c964f665d3bdff7953c9
+  metadata.gz: 312e13dccce60b22bb3e74005e914cadcbf6dbbf096d378759a2697e6c0a1e8c
+  data.tar.gz: f0fd02d53f7bbb97ee347f7b81b1e9a9f83476a5af871042036b025c9cbb8060
 SHA512:
-  metadata.gz: c3fb785f1d6362c9f3a6e94f951b1c761b73152ea7b76d7b1666726b1e130892aada79ea38c7f46be339557e4000dee41da8db0e547e0ee47e8f1c3df76a8daf
-  data.tar.gz: 81fc563d05f48cc9cfa4d640fb00671d435951bea5cea85092394ab56914040967d99b89c0cc577bf6e37d71e0775c956060fe4fc5caecc4ec42941282e59495
+  metadata.gz: 81512742b3dfc97f726a1af22d2bbfd578cd083cc2dd75f3cbe3c4004bde4e1e73ee21ba03675581b7586d590c2624e6287bc8040ee281e3b3fe85ef8c093f4e
+  data.tar.gz: 8e4390ef152eab60197e2a5822a132266b12c4eb567801017a2dd0308426109823230b86df6700b1e220f9353f9de892cbe634acaa4d89578ff84c99167ead89

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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,7 +306,7 @@ 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.
 
 Everything else, including anything tagged `@api private` in its source comment, is an implementation detail

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/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/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/version.rb

@@ -2,6 +2,6 @@
 
 module Tarantool
   class Client
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tarantool-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Starlexxx
@@ -68,6 +68,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 +118,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