tarantool-client 0.1.0

data/lib/tarantool/client/space_info.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Format and indexes of a space from the loaded schema. `indexes` maps names to IndexInfo in id order.
+    SpaceInfo = Data.define(:id, :name, :fields, :indexes) do
+      def self.from_tuples(space, index_tuples)
+        id, _owner, name, _engine, _field_count, _flags, format = space
+        fields = (format || []).map { |raw| SpaceInfo::Field.from_raw(raw) }
+        indexes = index_tuples.map { |tuple| IndexInfo.from_tuple(tuple, fields) }.sort_by(&:id)
+
+        new(id:, name:, fields:, indexes: indexes.to_h { |index| [index.name, index] })
+      end
+
+      def primary_index
+        indexes.each_value.find { |index| index.id.zero? }
+      end
+    end
+
+    SpaceInfo::Field = Data.define(:name, :type, :is_nullable) do
+      # A format entry without a type accepts any value.
+      def self.from_raw(raw)
+        new(name: raw['name'], type: raw.fetch('type', 'any'), is_nullable: raw.fetch('is_nullable', false))
+      end
+    end
+  end
+end

data/lib/tarantool/client/sql_result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Rows and column names of an SQL query, or the counters of a data-changing statement.
+    SqlResult = Data.define(:rows, :columns, :row_count, :autoincrement_ids) do
+      def self.from_response(response)
+        info = response.body.fetch(Protocol::Constants::SQL_INFO, {})
+
+        new(
+          rows: response.data || [],
+          columns: column_names(response.body),
+          row_count: info[Protocol::Constants::SQL_INFO_ROW_COUNT],
+          autoincrement_ids: info.fetch(Protocol::Constants::SQL_INFO_AUTOINCREMENT_IDS, [])
+        )
+      end
+
+      def self.column_names(body)
+        body.fetch(Protocol::Constants::METADATA, []).map { |field| field.fetch(Protocol::Constants::FIELD_NAME) }
+      end
+      private_class_method :column_names
+    end
+  end
+end

data/lib/tarantool/client/stream.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Operations sent over one IPROTO stream inside an interactive transaction; the server runs a
+    # stream's requests in order. Created by Client#transaction.
+    class Stream
+      include Operations
+
+      LOST = 'connection lost during the transaction; the server rolled it back'
+      FINISHED = 'transaction is finished'
+
+      def initialize(connection:, schema_cache:, id:, request_timeout:)
+        @connection = connection
+        @schema_cache = schema_cache
+        @id = id
+        @request_timeout = request_timeout
+        @state = :idle
+        @pid = Process.pid
+      end
+
+      def transaction(isolation:, timeout:, &)
+        raise TransactionError, TransactionScope::NESTED unless @state == :idle
+
+        start(isolation, timeout)
+
+        run(&)
+      end
+
+      def prepare(*)
+        raise TransactionError,
+              'prepare statements on the client; execute them in the transaction with tx.execute(statement, bindings)'
+      end
+
+      private
+
+      def start(isolation, timeout)
+        response = perform(Protocol::Requests::Begin.new(isolation:, timeout:))
+        @schema = TransactionSchema.new(@schema_cache, @connection, response.schema_version)
+
+        @state = :active
+      end
+
+      # Anything but normal completion of the block, including break and throw, rolls back.
+      def run
+        result = yield self
+        finish(Protocol::Requests::Commit.new)
+
+        result
+      ensure
+        abandon if @state == :active
+      end
+
+      def perform(request, timeout: nil, schema_version: nil, on_push: nil)
+        check_active
+
+        send_request(request, timeout: timeout || @request_timeout, schema_version:, on_push:)
+      end
+
+      def perform_on_space(space, index, timeout: nil, &)
+        return perform(yield(space, index), timeout:) if space.is_a?(Integer) && index.is_a?(Integer)
+
+        perform_by_name(space, index, timeout || @request_timeout, &)
+      end
+
+      # Checks for a lost connection first: resolving would otherwise meet the next connection's schema
+      # and report a schema change instead.
+      def perform_by_name(space, index, timeout)
+        check_connection
+        deadline = Transport::Deadline.after(timeout)
+        request = yield(*@schema.resolve(space, index, deadline))
+
+        perform(request, timeout: remaining(deadline), schema_version: @schema.version)
+      rescue ServerError => e
+        raise unless e.code == Protocol::Constants::ER_WRONG_SCHEMA_VERSION
+
+        @schema.raise_changed(deadline)
+      rescue TimeoutError
+        raise TimeoutError, "no response within #{timeout}s"
+      end
+
+      def lookup_space(space, timeout)
+        check_active
+        check_connection
+        timeout ||= @request_timeout
+
+        @schema.space_info(space, Transport::Deadline.after(timeout))
+      rescue TimeoutError
+        raise TimeoutError, "no response within #{timeout}s"
+      end
+
+      def remaining(deadline)
+        Transport::Deadline.remaining(deadline)
+      end
+
+      # State flips to finished before the request so a failed COMMIT is not followed by ROLLBACK:
+      # its outcome is unknown (the server may have committed), and a rollback would add nothing.
+      def finish(request)
+        @state = :finished
+
+        send_request(request, timeout: @request_timeout)
+      end
+
+      # A stream is bound to its connection's session, so a reconnect can't carry the transaction over.
+      def send_request(request, **)
+        check_connection
+
+        @connection.perform(request, stream_id: @id, **)
+      end
+
+      def check_connection
+        raise ConnectionError, 'stream was created before fork and cannot be used in a child process' \
+          if Process.pid != @pid
+        raise TransactionError, LOST if @state != :idle && @connection.closed?
+      end
+
+      def check_active
+        raise TransactionError, FINISHED if @state == :finished
+      end
+
+      # Runs while an error or a non-local exit is already propagating, which a failed rollback must
+      # not replace. A lost connection takes the transaction with it.
+      def abandon
+        finish(Protocol::Requests::Rollback.new)
+      rescue Error
+        nil
+      end
+    end
+  end
+end

data/lib/tarantool/client/thread_join.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Joins an internal thread without re-raising the exception it died with: the failure has already
+    # reached whoever was waiting on the thread, and closing must not fail because of it. An exception
+    # raised in the joining thread itself while it waits still propagates.
+    # @api private
+    module ThreadJoin
+      module_function
+
+      def join(thread)
+        thread&.join unless Thread.current == thread
+      rescue Exception
+        raise unless thread.status.nil?
+      end
+    end
+  end
+end

data/lib/tarantool/client/transaction_schema.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Name lookup for one transaction, pinned to the schema version the server reported for BEGIN.
+    # Re-resolving names against a newer schema mid-transaction could send later statements to a
+    # different space than earlier ones, so a schema change fails the transaction instead.
+    # @api private
+    class TransactionSchema
+      CHANGED = 'schema changed during the transaction; retry the whole transaction'
+
+      attr_reader :version
+
+      def initialize(cache, connection, version)
+        @cache = cache
+        @connection = connection
+        @version = version
+      end
+
+      def resolve(space, index, deadline)
+        pinned(deadline).resolve(space, index)
+      end
+
+      def space_info(space, deadline)
+        pinned(deadline).space_info(space)
+      end
+
+      # A request rejected for its schema version did not run, so the transaction still rolls back
+      # cleanly. The reload spares the retried transaction the same rejection.
+      def raise_changed(deadline)
+        schema = @cache.schema
+        reload(schema, deadline) if schema.version == version
+
+        raise TransactionError, CHANGED
+      end
+
+      private
+
+      # A cache older than BEGIN was stale before the transaction started and may catch up;
+      # anything newer means the schema changed after BEGIN. A schema of another connection means
+      # this one was lost, and the versions of two instances can't be compared.
+      def pinned(deadline)
+        schema = @cache.schema
+        raise TransactionError, Stream::LOST unless schema.connection.equal?(@connection)
+
+        schema = reload(schema, deadline) if schema.version < version
+        raise TransactionError, CHANGED unless schema.version == version
+
+        schema
+      end
+
+      def reload(schema, deadline)
+        @cache.reload(schema, timeout: Transport::Deadline.remaining(deadline))
+      end
+    end
+  end
+end

data/lib/tarantool/client/transaction_scope.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Clients with a transaction open in the current fiber. Thread#[] is fiber-local and, unlike
+    # Fiber storage, not inherited, so a thread or fiber spawned inside a transaction block may
+    # open its own transaction.
+    # @api private
+    module TransactionScope
+      NESTED = 'nested transactions are not supported'
+
+      module_function
+
+      def enter(client)
+        open = Thread.current[:tarantool_transactions] ||= {}
+        raise TransactionError, NESTED if open.key?(client)
+
+        open[client] = true
+
+        begin
+          yield
+        ensure
+          open.delete(client)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+module Tarantool
+  class Client
+    module Transport
+      # One multiplexed IPROTO connection. Any number of threads or fibers may
+      # perform requests concurrently; a reader thread routes responses by sync.
+      # @api private
+      class Connection
+        attr_reader :greeting, :server_features
+        attr_writer :event_handler, :disconnect_handler
+
+        def initialize(config)
+          @config = config
+          @pending = PendingRequests.new
+        end
+
+        def connect
+          establish
+
+          self
+        rescue StandardError
+          close
+          raise
+        end
+
+        # A request sent with no time left could still run on the server while the caller gets TimeoutError.
+        def perform(request, timeout:, stream_id: nil, schema_version: nil, on_push: nil)
+          deadline = Deadline.after(timeout)
+          raise TimeoutError, "no response within #{timeout}s" if Deadline.remaining(deadline)&.zero?
+
+          sync, future = @pending.register
+          frame = Protocol::Codec.encode(request, sync:, stream_id:, schema_version:)
+          response = exchange(frame, future, deadline, timeout, &on_push)
+          raise ServerError.from_response(response) if response.error?
+
+          response
+        ensure
+          @pending.delete(sync) if sync
+        end
+
+        # For requests the server never answers (WATCH, UNWATCH): there is no sync to wait on.
+        def notify(request, timeout:)
+          write(Protocol::Codec.encode(request, sync: 0), Deadline.after(timeout))
+        end
+
+        def close
+          @pending.fail_all(ClientClosedError.new("connection to #{@config.address} closed"))
+          @socket&.close
+          ThreadJoin.join(@reader)
+
+          nil
+        end
+
+        def closed?
+          !@pending.failure.nil?
+        end
+
+        private
+
+        def establish
+          deadline = Deadline.after(@config.connect_timeout)
+          @socket = open_socket(deadline)
+          @writer = FrameWriter.new(@socket)
+          @greeting = read_greeting(deadline)
+          start_reader
+
+          @server_features = Handshake.perform(self, @config, deadline)
+        rescue IOError, SystemCallError, SocketError, TimeoutError, ServerError => e
+          raise ConnectionError, "cannot connect to #{@config.address}: #{e.message}"
+        end
+
+        def open_socket(deadline)
+          return UNIXSocket.new(@config.path) if @config.path
+
+          Socket.tcp(@config.host, @config.port, connect_timeout: Deadline.remaining(deadline)).tap do |socket|
+            socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+          end
+        end
+
+        def read_greeting(deadline)
+          Protocol::Greeting.parse(TimedRead.read_exactly(@socket, Protocol::Constants::GREETING_SIZE, deadline))
+        end
+
+        def start_reader
+          @reader = Thread.new { read_loop }
+
+          @reader.name = "tarantool-reader #{@config.address}"
+        end
+
+        def read_loop
+          loop { route(Protocol::Codec.read_response(@socket, max_frame_size: @config.max_frame_size)) }
+        rescue IOError, SystemCallError, ProtocolError => e
+          reason = e.message
+        rescue StandardError, SystemStackError => e
+          reason = "#{e.class}: #{e.message}"
+        ensure
+          break_connection("connection to #{@config.address} lost: #{reason || 'reader stopped'}")
+        end
+
+        # Events carry the sync of whichever WATCH triggered them, so they are routed by type.
+        def route(response)
+          return @pending.push(response.sync, response.data.first) if response.push?
+          return @event_handler&.call(response.event_key, response.event_data) if response.event?
+
+          @pending.resolve(response.sync, response)
+        end
+
+        # A write that runs out of time, waiting for the lock or for the socket, is reported like a missing reply.
+        def exchange(frame, future, deadline, timeout, &)
+          write(frame, deadline)
+
+          future.value(Deadline.remaining(deadline), &)
+        rescue TimeoutError
+          raise TimeoutError, "no response within #{timeout}s"
+        end
+
+        # A partially written frame corrupts the stream, so any interruption after the
+        # first byte (deadline, IO error, Thread#raise, Timeout) kills the connection.
+        def write(frame, deadline)
+          @writer.write(frame, deadline) { break_connection("write to #{@config.address} did not complete") }
+        rescue IOError, SystemCallError => e
+          failure = @pending.failure
+          raise failure.exception(failure.message) if failure
+
+          raise ConnectionError, "write to #{@config.address} failed: #{e.message}"
+        end
+
+        # The handler hears only of a loss: close records ClientClosedError first, so it stays silent.
+        def break_connection(message)
+          lost = @pending.fail_all(ConnectionError.new(message))
+          @socket&.close
+
+          @disconnect_handler&.call if lost
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # Monotonic-clock deadlines. A nil timeout gives a nil deadline, which never expires.
+      # @api private
+      module Deadline
+        module_function
+
+        def after(timeout) = timeout && (now + timeout)
+        def remaining(deadline) = deadline && [deadline - now, 0].max
+        def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # Serializes whole-frame writes to a socket; both the wait for the lock and the write are bounded by the deadline.
+      # Yields when a write is interrupted after part of the frame went out, because
+      # the stream is corrupt from then on.
+      # @api private
+      class FrameWriter
+        def initialize(socket)
+          @socket = socket
+          @lock = TimedLock.new
+        end
+
+        # Async interrupts (Thread#raise, Timeout) are held until the blocking wait, so they
+        # never land between a write and the update of the unsent remainder.
+        def write(frame, deadline)
+          @lock.synchronize(deadline) do
+            rest = frame
+            Thread.handle_interrupt(Object => :on_blocking) do
+              rest = write_some(rest, deadline) until rest.empty?
+            end
+          ensure
+            yield if rest && !rest.empty? && rest.bytesize < frame.bytesize
+          end
+        end
+
+        private
+
+        def write_some(frame, deadline)
+          written = @socket.write_nonblock(frame, exception: false)
+          return frame.byteslice(written..) unless written == :wait_writable
+          raise TimeoutError, 'socket write timed out' unless @socket.wait_writable(Deadline.remaining(deadline))
+
+          frame
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # @api private
+    module Transport
+      # Result slot for one in-flight request, also carrying its pushed messages. Thread::Queue#pop
+      # yields to the Fiber Scheduler when one is active, so waiting never blocks other fibers.
+      # @api private
+      class Future
+        Push = Data.define(:message)
+        private_constant :Push
+
+        MAX_UNREAD_PUSHES = 10_000
+        private_constant :MAX_UNREAD_PUSHES
+
+        def initialize
+          @queue = Thread::Queue.new
+          @overflow = false
+        end
+
+        def resolve(value)
+          @queue.push(value)
+        end
+
+        def reject(error)
+          @queue.push(error)
+        end
+
+        def push(message)
+          return if @overflow
+
+          if @queue.size >= MAX_UNREAD_PUSHES
+            @overflow = true
+            @queue.push(ProtocolError.new('too many unread push messages'))
+            return
+          end
+
+          @queue.push(Push.new(message))
+        end
+
+        # Yields each pushed message, in the waiting thread, until the final value arrives.
+        def value(timeout)
+          deadline = Deadline.after(timeout)
+
+          loop do
+            result = @queue.pop(timeout: Deadline.remaining(deadline))
+            raise TimeoutError, "no response within #{timeout}s" if result.nil?
+            # One error object is shared by all failed futures; each waiter raises its own copy
+            # so concurrent raises don't race on it.
+            raise result.exception(result.message) if result.is_a?(Exception)
+            return result unless result.is_a?(Push)
+
+            yield result.message if block_given?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # IPROTO_ID feature exchange, then chap-sha1 AUTH for a named user. Returns the server features.
+      # @api private
+      module Handshake
+        module_function
+
+        def perform(connection, config, deadline)
+          id = Protocol::Requests::Id.new(
+            version: Protocol::Constants::PROTOCOL_VERSION, features: Protocol::Constants::CLIENT_FEATURES
+          )
+          response = connection.perform(id, timeout: Deadline.remaining(deadline))
+          authenticate(connection, config, deadline) if config.user && config.user != 'guest'
+
+          response.body.fetch(Protocol::Constants::FEATURES, [])
+        end
+
+        def authenticate(connection, config, deadline)
+          scramble = Protocol::Auth::ChapSha1.scramble(config.password.to_s, connection.greeting.salt)
+          request = Protocol::Requests::Auth.new(
+            user: config.user, mechanism: Protocol::Auth::ChapSha1::MECHANISM, scramble:
+          )
+
+          connection.perform(request, timeout: Deadline.remaining(deadline))
+        rescue ServerError => e
+          raise AuthenticationError.new(e.message, code: e.code)
+        end
+
+        private_class_method :authenticate
+      end
+    end
+  end
+end