tarantool-client 0.1.0

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    class Pool
+      # One pool address: its client once connected and the role from the instance's latest box.status.
+      # An address that is down at start keeps being retried in the background.
+      # @api private
+      class Member
+        include Pool::MemberForkSafety
+
+        def initialize(uri, options)
+          @uri = uri
+          @options = options
+          @config = Configuration.build(uri, **options)
+          @lock = Mutex.new
+          @changed = ConditionVariable.new
+          @closed = false
+        end
+
+        def address = @config.address
+        def client = @lock.synchronize { @client }
+        def inspect = "#<#{self.class.name} #{address}>"
+
+        # Connects and waits up to connect_timeout for the first box.status. Returns the error when the
+        # instance is unreachable.
+        def start
+          connect
+          wait_for_status
+
+          nil
+        rescue Error => e
+          retry_in_background if @config.reconnect
+          e
+        end
+
+        # nil while disconnected or before the current connection's first box.status, else whether the
+        # instance is read-only. The role is dropped as soon as the connection is lost; it can briefly come
+        # back only while the watcher dispatcher still delivers that connection's queued box.status.
+        def read_only
+          @lock.synchronize { @read_only if @client&.connected? }
+        end
+
+        def close
+          retrier, client = @lock.synchronize do
+            @closed = true
+            @changed.broadcast
+            [@retrier, @client]
+          end
+          ThreadJoin.join(retrier)
+
+          client&.close
+        end
+
+        private
+
+        def connect
+          client = Client.new(@uri, **@options)
+          # A role belongs to one session; the next one must report its own before the member is routed to.
+          client.disconnect_handler = -> { @lock.synchronize { @read_only = nil } }
+          client.watch('box.status') { |_key, status| update(status) }
+
+          install(client)
+        rescue Error
+          client&.close
+          raise
+        end
+
+        def install(client)
+          closed = @lock.synchronize do
+            @client = client unless @closed
+            @closed
+          end
+
+          client.close if closed
+        end
+
+        def update(status)
+          @lock.synchronize do
+            @read_only = status['is_ro']
+            @changed.broadcast
+          end
+        end
+
+        def wait_for_status
+          deadline = Transport::Deadline.after(@config.connect_timeout)
+
+          @lock.synchronize do
+            while @read_only.nil? && !@closed
+              remaining = Transport::Deadline.remaining(deadline)
+              break if remaining&.zero?
+
+              @changed.wait(@lock, remaining)
+            end
+          end
+        end
+
+        def retry_in_background
+          @lock.synchronize do
+            next if @closed
+
+            @retrier = Thread.new { retry_connect }
+            @retrier.name = "tarantool-pool-connect #{address}"
+          end
+        end
+
+        # The thread must never die with an exception: #close joins it and would re-raise it.
+        def retry_connect
+          backoff = Backoff.new(base: @config.reconnect_delay, max: @config.reconnect_max_delay)
+          attempt = 0
+
+          while attempt < @config.reconnect_attempts && pause(backoff.delay(attempt))
+            return if try_connect
+
+            attempt += 1
+          end
+        rescue StandardError => e
+          warn "tarantool pool: gave up connecting to #{address}: #{e.class}: #{e.message}"
+        end
+
+        def try_connect
+          connect
+
+          true
+        rescue Error
+          false
+        rescue StandardError => e
+          warn "tarantool pool: connecting to #{address} failed: #{e.class}: #{e.message}"
+          false
+        end
+
+        def pause(delay)
+          @lock.synchronize do
+            @changed.wait(@lock, delay) unless @closed
+            !@closed
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    class Pool
+      # @api private
+      module MemberForkSafety
+        # Pool re-runs its startup in a forked child after this. The inherited client and retry thread belong
+        # to the parent: closing the client in the child only drops its socket copy, dead threads join at once.
+        # Nothing inherited may stop the reset, or the child's pool would never start its members.
+        def reset_for_fork
+          old_retrier, old_client = @lock.synchronize do
+            retrier = @retrier
+            client = @client
+            @retrier = nil
+            @client = nil
+            @read_only = nil
+            [retrier, client]
+          end
+          ThreadJoin.join(old_retrier)
+          close_inherited(old_client)
+        end
+
+        private
+
+        def close_inherited(client)
+          client&.close
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/pool.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Clients for the instances of one replica set. Each request goes to an instance picked by mode
+    # from the role it reports through box.status, round-robin among the matches. Starts with the
+    # addresses that answer; the others keep being retried in the background.
+    class Pool
+      MODES = %i[rw ro prefer_ro prefer_rw any].freeze
+
+      def initialize(addresses, **options)
+        raise ArgumentError, 'a pool needs at least one address' if addresses.empty?
+
+        @members = addresses.map { |address| Member.new(address, options) }
+        @lock = Mutex.new
+        @reinit_lock = Mutex.new
+        @turns = Hash.new(0)
+        @pid = Process.pid
+        start_members
+      rescue StandardError
+        close
+        raise
+      end
+
+      # Each instance resolves names against its own schema, so requests are delegated, not built here.
+      Operations.public_instance_methods.each do |name|
+        define_method(name) do |*args, mode: :any, **options, &block|
+          client_for(mode).public_send(name, *args, **options, &block)
+        end
+      end
+
+      def transaction(**, &)
+        client_for(:rw).transaction(**, &)
+      end
+
+      def close
+        errors = (@members || []).filter_map do |member|
+          member.close
+          nil
+        rescue StandardError => e
+          e
+        end
+
+        raise errors.first if errors.any?
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@members.map(&:address).join(', ')}>"
+      end
+
+      private
+
+      def start_members
+        results = start_in_parallel
+        unexpected = results.find { |result| result.is_a?(Exception) && !result.is_a?(Error) }
+        raise unexpected if unexpected
+
+        raise NoAvailableInstanceError, "no instance reachable: #{results.map(&:message).join('; ')}" if results.all?
+      end
+
+      # Each member's start error, or the exception its thread raised. Joins every thread before
+      # returning so none outlives a failed Pool.new.
+      def start_in_parallel
+        threads = @members.map { |member| start_thread(member) }
+
+        threads.map do |thread|
+          thread.value
+        rescue StandardError => e
+          e
+        end
+      end
+
+      def start_thread(member)
+        Thread.new { member.start }.tap do |thread|
+          thread.name = "tarantool-pool-start #{member.address}"
+          thread.report_on_exception = false
+        end
+      end
+
+      def client_for(mode)
+        ensure_fork_safe
+        members = candidates(mode)
+        raise NoAvailableInstanceError, "no instance available for mode #{mode.inspect}" if members.empty?
+
+        members[@lock.synchronize { @turns[mode] += 1 } % members.size].client
+      end
+
+      def ensure_fork_safe
+        return if @pid == Process.pid
+
+        @reinit_lock.synchronize do
+          return if @pid == Process.pid
+
+          @members.each(&:reset_for_fork)
+          start_members
+        ensure
+          @pid = Process.pid
+        end
+      end
+
+      def candidates(mode)
+        writable, read_only = split_by_role
+
+        case mode
+        when :rw then writable
+        when :ro then read_only
+        when :prefer_ro then fallback(read_only, writable)
+        when :prefer_rw then fallback(writable, read_only)
+        when :any then writable + read_only
+        else raise ArgumentError, "unknown mode #{mode.inspect}, expected one of #{MODES.join(', ')}"
+        end
+      end
+
+      def fallback(preferred, other) = preferred.empty? ? other : preferred
+
+      # Members with a known role: [writable, read-only].
+      def split_by_role
+        known = @members.filter_map do |member|
+          read_only = member.read_only
+          [member, read_only] unless read_only.nil?
+        end
+
+        known.partition { |_member, read_only| !read_only }.map { |pairs| pairs.map(&:first) }
+      end
+    end
+  end
+end

data/lib/tarantool/client/prepared_statement.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Server-side prepared SQL statement. Runs through the client or stream that prepared it.
+    class PreparedStatement
+      attr_reader :id
+
+      def initialize(id, perform)
+        @id = id
+        @perform = perform
+      end
+
+      def execute(bindings = [], timeout: nil)
+        SqlResult.from_response(@perform.call(Protocol::Requests::Execute.new(statement: id, bindings:), timeout:))
+      end
+
+      def close(timeout: nil)
+        @perform.call(Protocol::Requests::Prepare.new(statement: id), timeout:)
+
+        nil
+      end
+    end
+  end
+end

data/lib/tarantool/client/protocol/auth/chap_sha1.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'digest/sha1'
+
+module Tarantool
+  class Client
+    module Protocol
+      # @api private
+      module Auth
+        # chap-sha1: proves the password to the server without sending it.
+        # @api private
+        module ChapSha1
+          MECHANISM = 'chap-sha1'
+
+          module_function
+
+          def scramble(password, salt)
+            hash1 = Digest::SHA1.digest(password)
+            hash2 = Digest::SHA1.digest(hash1)
+            hash3 = Digest::SHA1.digest(salt.byteslice(0, Constants::SCRAMBLE_SIZE) + hash2)
+
+            hash1.bytes.zip(hash3.bytes).map { |left, right| left ^ right }.pack('C*')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Protocol
+      # IPROTO framing: MP_UINT32 size prefix, header map, body map.
+      # @api private
+      module Codec
+        SIZE_MARKER = 0xce
+        PREFIX_SIZE = 5
+        FACTORY = MessagePack::Factory.new.tap do |factory|
+          Extensions.each { |extension| factory.register_type(extension.type, extension.klass, **extension.options) }
+        end.freeze
+
+        module_function
+
+        def encode(request, sync:, stream_id: nil, schema_version: nil)
+          header = { Constants::REQUEST_TYPE => request.type, Constants::SYNC => sync }
+          header[Constants::STREAM_ID] = stream_id if stream_id
+          header[Constants::SCHEMA_VERSION] = schema_version if schema_version
+          payload = FACTORY.dump(header) + FACTORY.dump(request.body)
+
+          [SIZE_MARKER, payload.bytesize].pack('CN') + payload
+        end
+
+        def read_response(io, max_frame_size: nil)
+          marker, size = read_exactly(io, PREFIX_SIZE).unpack('CN')
+          raise ProtocolError, format('unexpected frame size marker 0x%02x', marker) unless marker == SIZE_MARKER
+
+          if max_frame_size && size > max_frame_size
+            raise ProtocolError, "frame of #{size} bytes exceeds max_frame_size #{max_frame_size}"
+          end
+
+          decode(read_exactly(io, size))
+        end
+
+        def decode(payload)
+          unpacker = FACTORY.unpacker(allow_unknown_ext: true)
+          unpacker.feed(payload)
+          header, body = unpack_frame(unpacker)
+
+          validate_header(header)
+          validate_body(body)
+          raise ProtocolError, 'malformed frame: trailing bytes' unless unpacker.buffer.empty?
+
+          Response.new(header, body)
+        end
+
+        def unpack_frame(unpacker)
+          header = unpacker.read
+          body = unpacker.buffer.empty? ? {} : unpacker.read
+
+          [header, body]
+        rescue StandardError => e
+          raise ProtocolError, "malformed frame: #{e.message}"
+        end
+
+        def validate_header(header)
+          return if header.is_a?(Hash) && header.key?(Constants::REQUEST_TYPE)
+
+          raise ProtocolError, 'malformed frame: header must be a map with a request type'
+        end
+
+        def validate_body(body)
+          raise ProtocolError, 'malformed frame: body must be a map' unless body.is_a?(Hash)
+        end
+
+        def read_exactly(io, size)
+          data = io.read(size)
+          raise EOFError, 'connection closed by server' if data.nil? || data.bytesize < size
+
+          data
+        end
+
+        private_class_method :unpack_frame, :validate_header, :validate_body
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # @api private
+    module Protocol
+      # IPROTO keys and codes: https://www.tarantool.io/en/doc/latest/reference/internals/iproto/keys/
+      # @api private
+      module Constants
+        REQUEST_TYPE = 0x00
+        SYNC = 0x01
+        SCHEMA_VERSION = 0x05
+        STREAM_ID = 0x0a
+
+        SPACE_ID = 0x10
+        INDEX_ID = 0x11
+        LIMIT = 0x12
+        OFFSET = 0x13
+        ITERATOR = 0x14
+        KEY = 0x20
+        TUPLE = 0x21
+        FUNCTION_NAME = 0x22
+        USER_NAME = 0x23
+        EXPR = 0x27
+        OPS = 0x28
+        AFTER_TUPLE = 0x2f
+        DATA = 0x30
+        ERROR_24 = 0x31
+        METADATA = 0x32
+        SQL_TEXT = 0x40
+        SQL_BIND = 0x41
+        SQL_INFO = 0x42
+        STMT_ID = 0x43
+        ERROR = 0x52
+        VERSION = 0x54
+        FEATURES = 0x55
+        TIMEOUT = 0x56
+        EVENT_KEY = 0x57
+        EVENT_DATA = 0x58
+        TXN_ISOLATION = 0x59
+
+        OK = 0x00
+        SELECT = 0x01
+        INSERT = 0x02
+        REPLACE = 0x03
+        UPDATE = 0x04
+        DELETE = 0x05
+        AUTH = 0x07
+        EVAL = 0x08
+        UPSERT = 0x09
+        CALL = 0x0a
+        EXECUTE = 0x0b
+        PREPARE = 0x0d
+        BEGIN_TRANSACTION = 0x0e
+        COMMIT = 0x0f
+        ROLLBACK = 0x10
+        PING = 0x40
+        ID = 0x49
+        WATCH = 0x4a
+        UNWATCH = 0x4b
+        EVENT = 0x4c
+        CHUNK = 0x80
+        TYPE_ERROR = 0x8000
+
+        ER_WRONG_SCHEMA_VERSION = 109
+
+        FIELD_NAME = 0x00
+        SQL_INFO_ROW_COUNT = 0x00
+        SQL_INFO_AUTOINCREMENT_IDS = 0x01
+
+        MP_DECIMAL = 0x01
+        MP_UUID = 0x02
+        MP_ERROR = 0x03
+        MP_DATETIME = 0x04
+        MP_INTERVAL = 0x06
+        ERROR_STACK = 0x00
+        ERROR_FIELDS = {
+          0x00 => :type, 0x01 => :file, 0x02 => :line, 0x03 => :message,
+          0x04 => :errno, 0x05 => :code, 0x06 => :fields
+        }.freeze
+
+        ITERATORS = {
+          eq: 0, req: 1, all: 2, lt: 3, le: 4, ge: 5, gt: 6,
+          bits_all_set: 7, bits_any_set: 8, bits_all_not_set: 9, overlaps: 10, neighbor: 11,
+          np: 12, pp: 13
+        }.freeze
+
+        ISOLATION_LEVELS = { default: 0, read_committed: 1, read_confirmed: 2, best_effort: 3, linearizable: 4 }.freeze
+
+        PROTOCOL_VERSION = 3
+        FEATURE_STREAMS = 0
+        FEATURE_TRANSACTIONS = 1
+        FEATURE_ERROR_EXTENSION = 2
+        FEATURE_WATCHERS = 3
+        CLIENT_FEATURES = [FEATURE_STREAMS, FEATURE_TRANSACTIONS, FEATURE_ERROR_EXTENSION, FEATURE_WATCHERS].freeze
+
+        GREETING_SIZE = 128
+        SCRAMBLE_SIZE = 20
+        MAX_LIMIT = 0xffff_ffff
+        VSPACE_ID = 281
+        VINDEX_ID = 289
+      end
+    end
+  end
+end

data/lib/tarantool/client/protocol/extensions/datetime.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Protocol
+      module Extensions
+        # MP_EXT datetime: int64 epoch seconds, then optional int32 nsec, int16 tzoffset, int16 tzindex.
+        # tzindex is ignored: Time keeps the offset, not the zone name.
+        # @api private
+        module Datetime
+          SECONDS = 'q<'
+          FULL = 'q<l<s<s<'
+          LAYOUTS = { 8 => SECONDS, 16 => FULL }.freeze
+
+          module_function
+
+          def pack(time)
+            offset, remainder = time.utc_offset.divmod(60)
+            raise ArgumentError, "utc_offset #{time.utc_offset}s is not in whole minutes" unless remainder.zero?
+            return [time.to_i].pack(SECONDS) if time.nsec.zero? && offset.zero?
+
+            [time.to_i, time.nsec, offset, 0].pack(FULL)
+          end
+
+          def unpack(payload)
+            layout = LAYOUTS.fetch(payload.bytesize) do
+              raise ArgumentError, "malformed datetime: #{payload.bytesize} bytes"
+            end
+            seconds, nsec, offset = payload.unpack(layout)
+
+            Time.at(seconds, nsec.to_i, :nsec, in: offset.to_i.zero? ? 'UTC' : offset * 60)
+          end
+
+          Extensions.register(Constants::MP_DATETIME, Time, packer: method(:pack), unpacker: method(:unpack))
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/protocol/extensions/decimal.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Protocol
+      module Extensions
+        # MP_EXT decimal: msgpack int scale, then BCD digits with a trailing sign nibble.
+        # @api private
+        module Decimal
+          MAX_DIGITS = 38
+          # Digits, the sign and the zero nibble that pads them to whole bytes.
+          MAX_NIBBLES = MAX_DIGITS + 2
+          # Tarantool's decimal context: exponents up to 999_999, and down to -1_000_074 for subnormals and zeros.
+          SCALES = (-999_999..1_000_074)
+          NEGATIVE_SIGNS = %w[b d].freeze
+          BCD_NIBBLES = /\A\d+[a-f]\z/
+
+          module_function
+
+          def pack(value)
+            raise ArgumentError, "cannot encode #{value} as decimal" unless value.finite?
+
+            scale, nibbles = scale_and_nibbles(value)
+
+            MessagePack.pack(scale) + [nibbles].pack('H*')
+          end
+
+          def unpack(payload)
+            unpacker = MessagePack::Unpacker.new.feed(payload)
+            scale = unpacker.read
+            nibbles = unpacker.buffer.read_all.unpack1('H*')
+            raise ArgumentError, "malformed decimal of #{payload.bytesize} bytes" unless valid?(scale, nibbles)
+
+            sign = NEGATIVE_SIGNS.include?(nibbles[-1]) ? '-' : ''
+
+            BigDecimal("#{sign}#{nibbles[0...-1]}e#{-scale}")
+          end
+
+          def valid?(scale, nibbles)
+            scale.is_a?(Integer) && SCALES.cover?(scale) && nibbles.length <= MAX_NIBBLES &&
+              nibbles.match?(BCD_NIBBLES) && nibbles.delete_prefix('0').length <= MAX_DIGITS + 1
+          end
+          private_class_method :valid?
+
+          def scale_and_nibbles(value)
+            sign, digits, _base, exponent = value.split
+            if digits.length > MAX_DIGITS
+              raise ArgumentError, "decimal exceeds #{MAX_DIGITS} digits: #{value.to_s('F')}"
+            end
+
+            scale = value.zero? ? 0 : digits.length - exponent
+            scale, digits = expand_negative_scale(scale, digits)
+            nibbles = digits + (sign.negative? ? 'd' : 'c')
+
+            [scale, nibbles.length.odd? ? "0#{nibbles}" : nibbles]
+          end
+          private_class_method :scale_and_nibbles
+
+          # Tarantool itself writes whole numbers with scale 0 and trailing zero digits;
+          # keeping a negative scale when that would overflow MAX_DIGITS stays lossless.
+          def expand_negative_scale(scale, digits)
+            return [scale, digits] if scale >= 0 || digits.length - scale > MAX_DIGITS
+
+            [0, digits + ('0' * -scale)]
+          end
+          private_class_method :expand_negative_scale
+
+          Extensions.register(Constants::MP_DECIMAL, BigDecimal, packer: method(:pack), unpacker: method(:unpack))
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/protocol/extensions/error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Protocol
+      module Extensions
+        # MP_ERROR: a box.error stack decoded into a BoxError chain. Error fields may hold further MP_ERRORs,
+        # each decoded by a nested call; the depth sits in fiber-local storage, so concurrent decoders never share it.
+        # @api private
+        module Error
+          MAX_DEPTH = 16
+          DEPTH_KEY = :tarantool_mp_error_depth
+
+          module_function
+
+          def unpack(payload)
+            depth = Thread.current[DEPTH_KEY] || 0
+            raise ProtocolError, "MP_ERROR nested deeper than #{MAX_DEPTH} levels" if depth >= MAX_DEPTH
+
+            Thread.current[DEPTH_KEY] = depth + 1
+            stack = Codec::FACTORY.load(payload, allow_unknown_ext: true).fetch(Constants::ERROR_STACK)
+
+            Client::BoxError.from_stack(stack)
+          ensure
+            Thread.current[DEPTH_KEY] = depth
+          end
+
+          Extensions.register(Constants::MP_ERROR, Client::BoxError, unpacker: method(:unpack))
+        end
+      end
+    end
+  end
+end