tarantool-client 0.1.0 → 0.3.0

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

@@ -5,21 +5,24 @@ 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.
-        def initialize(config, on_connect:, on_ready:, on_lost: nil, backoff: nil)
+        # 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
           @on_ready = on_ready
           @on_lost = on_lost
           @backoff = backoff || Backoff.new(base: config.reconnect_delay, max: config.reconnect_max_delay)
           @state = LinkState.new(config.address, reconnect: config.reconnect)
+          @instrumentation = instrumentation
         end
 
         def connect
@@ -49,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
@@ -93,25 +98,28 @@ module Tarantool
         end
 
         def lost(connection)
-          return unless @config.reconnect
+          return report_lost(connection) unless @config.reconnect
 
           @state.start_reconnect(connection) do |previous|
-            Thread.new { reconnect(previous) }.tap { |thread| thread.name = "tarantool-reconnect #{@config.address}" }
+            Thread.new { reconnect(previous, connection) }.tap do |thread|
+              thread.name = "tarantool-reconnect #{@config.address}"
+            end
           end
         rescue ThreadError => e
-          @state.give_up(ConnectionError.new("cannot reconnect to #{@config.address}: #{e.message}"))
+          fail_reconnect(ConnectionError.new("cannot reconnect to #{@config.address}: #{e.message}"))
         end
 
         # Joining the previous thread first lets close join only the newest one. Nothing may escape: a dead
         # thread would leave the link reconnecting forever, and its exception would resurface in every join.
-        def reconnect(previous)
+        def reconnect(previous, connection)
           ThreadJoin.join(previous)
+          emit('disconnect.tarantool', reason: connection.failure&.message)
           run_hook('on_lost') { @on_lost&.call }
 
           reconnect_with_backoff
         rescue StandardError => e
-          warn(e.full_message)
-          @state.give_up(ConnectionError.new("reconnect to #{@config.address} failed: #{e.class}: #{e.message}"))
+          Diagnostics.warn(@config.logger, e.full_message)
+          fail_reconnect(ConnectionError.new("reconnect to #{@config.address} failed: #{e.class}: #{e.message}"))
         end
 
         def reconnect_with_backoff
@@ -119,7 +127,7 @@ module Tarantool
 
           while @state.pause(@backoff.delay(attempt))
             result = attempt_connect
-            return run_hook('on_ready') { install(result) } if result.is_a?(Connection)
+            return reconnected(result, attempt + 1) if result.is_a?(Connection)
 
             attempt += 1
             return give_up(attempt, result) if attempt >= @config.reconnect_attempts
@@ -131,19 +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
-          warn("#{name} failed for #{@config.address}: #{e.full_message}")
-        end
-
-        def give_up(attempts, error)
-          @state.give_up(
-            ConnectionError.new("cannot reconnect to #{@config.address} after #{attempts} attempts: #{error.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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # 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.
+        def report_lost(connection)
+          emit('disconnect.tarantool', reason: connection.failure&.message) if @state.claim_loss(connection)
+        end
+
+        # A connection the link was closed under, or that broke during on_ready, is no reconnect to report.
+        def reconnected(connection, attempts)
+          run_hook('on_ready') { install(connection) }
+          emit('reconnect.tarantool', attempts:) unless connection.closed?
+        end
+
+        def give_up(attempts, error)
+          message = "cannot reconnect to #{@config.address} after #{attempts} attempts: #{error.message}"
+
+          fail_reconnect(ConnectionError.new(message), attempts:)
+        end
+
+        def fail_reconnect(error, **payload)
+          @state.give_up(error)
+          emit('reconnect_failed.tarantool', **payload, **Instrumentation.exception_keys(error))
+        end
+
+        # Link already has a public #notify for WATCH/UNWATCH requests, so events use a different name.
+        def emit(name, **payload) = @instrumentation&.notify(name, payload)
+      end
+    end
+  end
+end

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

@@ -20,6 +20,16 @@ module Tarantool
           @lock.synchronize { @state == :ready && !@connection.closed? }
         end
 
+        # Without reconnect the link stays on the lost connection; the first caller reports its loss.
+        def claim_loss(connection)
+          @lock.synchronize do
+            next false unless @connection.equal?(connection) && !@lost.equal?(connection)
+
+            @lost = connection
+            true
+          end
+        end
+
         # Records the connection being opened so that close can abort it; raises once the link is closed.
         def attempting(connection)
           @lock.synchronize do
@@ -42,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
@@ -54,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")
@@ -62,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/tuple_mapping.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Tuple <-> Hash by the space format, for SpaceInfo. Fields beyond the format are keyed by their 0-based position.
+    # @api private
+    module TupleMapping
+      # A position this far past the format would otherwise let a huge Integer key allocate a giant Array.
+      MAX_POSITIONS_BEYOND_FORMAT = 1024
+
+      def to_hash(tuple)
+        hash = fields.each_with_index.to_h { |field, position| [field.name.to_sym, tuple[position]] }
+        (fields.size...tuple.size).each { |position| hash[position] = tuple[position] }
+
+        hash
+      end
+
+      # A missing field goes out as nil; on 3.x the server applies the field default to nil as well.
+      def to_tuple(hash)
+        positions = fields.each_with_index.to_h { |field, position| [field.name, position] }
+        named_positions = {}
+
+        hash.each_with_object(Array.new(fields.size)) do |(key, value), tuple|
+          position = position_of(key, positions)
+          check_not_duplicate(key, position, named_positions)
+          tuple[position] = value
+        end
+      end
+
+      private
+
+      def position_of(key, positions)
+        case key
+        when Symbol, String
+          positions.fetch(key.to_s) { raise UnknownFieldError, "space #{name} has no field '#{key}'" }
+        when Integer then position_beyond_format(key)
+        else raise ArgumentError, "unsupported key #{key.inspect} for space #{name}"
+        end
+      end
+
+      # `:a` and 'a' name the same field; the later one would otherwise win silently.
+      def check_not_duplicate(key, position, named_positions)
+        return unless key.is_a?(Symbol) || key.is_a?(String)
+        raise ArgumentError, "space #{name} field '#{fields[position].name}' given twice" if named_positions[position]
+
+        named_positions[position] = true
+      end
+
+      def position_beyond_format(position)
+        raise ArgumentError, "position #{position} is negative for space #{name}" if position.negative?
+
+        if position < fields.size
+          raise ArgumentError, "position #{position} is inside the format of space #{name}; use the field name"
+        end
+
+        if position >= fields.size + MAX_POSITIONS_BEYOND_FORMAT
+          raise ArgumentError, "position #{position} is more than #{MAX_POSITIONS_BEYOND_FORMAT} past the format " \
+                               "of space #{name}"
+        end
+
+        position
+      end
+    end
+  end
+end

data/lib/tarantool/client/tuple_shape.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # What data operations return for each tuple, chosen with `as:`.
+    # @api private
+    module TupleShape
+      SHAPES = %i[tuple hash row].freeze
+
+      def self.check(shape)
+        return if SHAPES.include?(shape)
+
+        raise ArgumentError, "unknown as: #{shape.inspect}, expected one of #{SHAPES.join(', ')}"
+      end
+
+      def self.apply(shape, tuple, space_info)
+        case shape
+        when :hash then space_info.to_hash(tuple)
+        when :row then Row.new(tuple:, attributes: space_info.to_hash(tuple))
+        else tuple
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/version.rb

@@ -2,6 +2,6 @@
 
 module Tarantool
   class Client
-    VERSION = '0.1.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/tarantool/client.rb

@@ -8,6 +8,7 @@ require_relative 'client/errors'
 require_relative 'client/configuration'
 require_relative 'client/backoff'
 require_relative 'client/thread_join'
+require_relative 'client/diagnostics'
 require_relative 'client/protocol/constants'
 require_relative 'client/box_error'
 require_relative 'client/uuid'
@@ -40,6 +41,12 @@ require_relative 'client/protocol/requests/auth'
 require_relative 'client/protocol/requests/id'
 require_relative 'client/protocol/requests/watch'
 require_relative 'client/protocol/requests/unwatch'
+require_relative 'client/instrumentation'
+require_relative 'client/instrumentation/request_payload'
+require_relative 'client/instrumentation/log_lines'
+require_relative 'client/instrumentation/log_instrumenter'
+require_relative 'client/instrumented'
+require_relative 'client/named_requests'
 require_relative 'client/transport/future'
 require_relative 'client/transport/pending_requests'
 require_relative 'client/transport/stream_ids'
@@ -50,14 +57,21 @@ require_relative 'client/transport/frame_writer'
 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'
 require_relative 'client/space_info'
 require_relative 'client/schema'
 require_relative 'client/schema_cache'
 require_relative 'client/sql_result'
 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'
 require_relative 'client/stream'
@@ -68,6 +82,7 @@ require_relative 'client/watchers/dispatcher'
 require_relative 'client/fork_safety'
 require_relative 'client/pool'
 require_relative 'client/pool/member_fork_safety'
+require_relative 'client/pool/member_role'
 require_relative 'client/pool/member'
 
 module Tarantool
@@ -75,6 +90,8 @@ module Tarantool
   class Client
     include Operations
     include ForkSafety
+    include Instrumented
+    include NamedRequests
 
     attr_reader :config
 
@@ -85,6 +102,7 @@ module Tarantool
 
     def initialize(uri = nil, **)
       @config = Configuration.build(uri, **)
+      @instrumentation = Instrumentation.build(@config)
       @pid = Process.pid
       @reinit_lock = Mutex.new
       open_link
@@ -107,7 +125,7 @@ module Tarantool
       TransactionScope.enter(self) do
         stream = Stream.new(
           connection: @link.connection, schema_cache: @schema_cache, id: @stream_ids.next,
-          request_timeout: @config.request_timeout
+          request_timeout: @config.request_timeout, instrumentation: @instrumentation
         )
         stream.transaction(isolation:, timeout:, &block)
       end
@@ -139,7 +157,7 @@ module Tarantool
 
     def link_hooks = { on_connect: method(:load_schema), on_ready: method(:resubscribe), on_lost: method(:lost) }
 
-    def perform(request, timeout: nil, schema_version: nil, on_push: nil)
+    def transmit(request, timeout: nil, schema_version: nil, on_push: nil)
       ensure_fork_safe
       @link.perform(request, timeout: timeout || @config.request_timeout, schema_version:, on_push:)
     end
@@ -164,53 +182,12 @@ module Tarantool
 
     # Name-resolved requests carry the schema version they were resolved against, so the
     # server rejects them (ER_WRONG_SCHEMA_VERSION) instead of running them on a stale id.
-    def perform_on_space(space, index, timeout: nil, &)
-      return perform(yield(space, index), timeout:) if space.is_a?(Integer) && index.is_a?(Integer)
+    # A request that needs the space format is resolved the same way even by ids, so the
+    # format and the version it carries come from one schema.
+    def transmit_on_space(space, index, timeout: nil, format: false, payload: nil, &)
+      return transmit(yield(space, index), timeout:) if !format && space.is_a?(Integer) && index.is_a?(Integer)
 
-      perform_by_name(space, index, timeout || @config.request_timeout, &)
-    end
-
-    # Every schema fetch and attempt draws on one deadline, so the whole call stays within timeout.
-    # Waiting for a connection first means the cache already holds its schema or a newer one.
-    def perform_by_name(space, index, timeout, &)
-      ensure_fork_safe
-      deadline = Transport::Deadline.after(timeout)
-      @link.connection(deadline)
-
-      perform_with_schema_check(space, index, deadline, &)
-    rescue TimeoutError
-      raise TimeoutError, "no response within #{timeout}s"
-    end
-
-    def lookup_space(space, timeout)
-      ensure_fork_safe
-      timeout ||= @config.request_timeout
-      deadline = Transport::Deadline.after(timeout)
-      @link.connection(deadline)
-
-      @schema_cache.space_info(space, deadline)
-    rescue TimeoutError
-      raise TimeoutError, "no response within #{timeout}s"
-    end
-
-    def perform_with_schema_check(space, index, deadline)
-      schema, ids = @schema_cache.resolve(space, index, deadline)
-
-      perform_resolved(schema, yield(*ids), deadline)
-    rescue ServerError => e
-      raise unless e.code == Protocol::Constants::ER_WRONG_SCHEMA_VERSION
-
-      fresh = @schema_cache.reload(schema, timeout: Transport::Deadline.remaining(deadline))
-      schema, ids = @schema_cache.resolve(space, index, deadline, fresh)
-      perform_resolved(schema, yield(*ids), deadline)
-    end
-
-    # Only the connection the schema came from: once it is lost, another instance may reuse the
-    # schema version with other ids, so the request fails with it rather than wait for a reconnect.
-    def perform_resolved(schema, request, deadline)
-      timeout = Transport::Deadline.remaining(deadline)
-
-      schema.connection.perform(request, timeout:, schema_version: schema.version)
+      perform_by_name(space, index, timeout || @config.request_timeout, payload, &)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tarantool-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Starlexxx
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -52,17 +52,27 @@ files:
 - README.md
 - lib/tarantool/client.rb
 - lib/tarantool/client/backoff.rb
+- lib/tarantool/client/batch_delete.rb
 - lib/tarantool/client/box_error.rb
 - lib/tarantool/client/callback_guard.rb
 - lib/tarantool/client/configuration.rb
+- lib/tarantool/client/diagnostics.rb
 - lib/tarantool/client/errors.rb
 - lib/tarantool/client/fork_safety.rb
 - lib/tarantool/client/index_info.rb
+- lib/tarantool/client/instrumentation.rb
+- lib/tarantool/client/instrumentation/log_instrumenter.rb
+- lib/tarantool/client/instrumentation/log_lines.rb
+- lib/tarantool/client/instrumentation/request_payload.rb
+- lib/tarantool/client/instrumented.rb
 - 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
+- lib/tarantool/client/pool/member_role.rb
 - lib/tarantool/client/prepared_statement.rb
 - lib/tarantool/client/protocol/auth/chap_sha1.rb
 - lib/tarantool/client/protocol/codec.rb
@@ -93,6 +103,7 @@ files:
 - lib/tarantool/client/protocol/requests/upsert.rb
 - lib/tarantool/client/protocol/requests/watch.rb
 - lib/tarantool/client/protocol/response.rb
+- lib/tarantool/client/row.rb
 - lib/tarantool/client/schema.rb
 - lib/tarantool/client/schema_cache.rb
 - lib/tarantool/client/space_info.rb
@@ -107,11 +118,15 @@ 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
 - lib/tarantool/client/transport/stream_ids.rb
 - lib/tarantool/client/transport/timed_lock.rb
 - lib/tarantool/client/transport/timed_read.rb
+- lib/tarantool/client/tuple_mapping.rb
+- lib/tarantool/client/tuple_shape.rb
 - lib/tarantool/client/uuid.rb
 - lib/tarantool/client/version.rb
 - lib/tarantool/client/watcher.rb