tarantool-client 0.1.0

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    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.
+      # @api private
+      class Link
+        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)
+          @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)
+        end
+
+        def connect
+          install(open_connection)
+          connected = true
+
+          self
+        ensure
+          close unless connected
+        end
+
+        def perform(request, timeout:, **)
+          deadline = Deadline.after(timeout)
+
+          current(deadline).perform(request, timeout: Deadline.remaining(deadline), **)
+        end
+
+        def notify(request, timeout:)
+          deadline = Deadline.after(timeout)
+
+          current(deadline).notify(request, timeout: Deadline.remaining(deadline))
+        end
+
+        # For requests that must stay on one connection: a stream, or a request resolved by name.
+        def connection(deadline = nil) = current(deadline)
+
+        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.
+        def close
+          reconnector, attempt = @state.close
+          attempt&.close
+          begin
+            ThreadJoin.join(reconnector)
+          ensure
+            @state.connection&.close
+          end
+
+          nil
+        end
+
+        private
+
+        def current(deadline)
+          @state.current([deadline, Deadline.after(@config.connect_timeout)].compact.min)
+        end
+
+        def open_connection
+          connection = Connection.new(@config)
+          connection.event_handler = @event_handler
+          connection.disconnect_handler = -> { lost(connection) }
+          @state.attempting(connection)
+          connection.connect
+          @on_connect.call(connection)
+          opened = true
+
+          connection
+        ensure
+          connection&.close unless opened
+        end
+
+        # A connection that broke before it became current was ignored by #lost, hence the last check. It runs
+        # even when on_ready raises, which it likely does on such a connection.
+        def install(connection)
+          return connection.close unless @state.install(connection)
+
+          @on_ready.call(connection)
+        ensure
+          lost(connection) if connection.closed?
+        end
+
+        def lost(connection)
+          return unless @config.reconnect
+
+          @state.start_reconnect(connection) do |previous|
+            Thread.new { reconnect(previous) }.tap { |thread| thread.name = "tarantool-reconnect #{@config.address}" }
+          end
+        rescue ThreadError => e
+          @state.give_up(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)
+          ThreadJoin.join(previous)
+          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}"))
+        end
+
+        def reconnect_with_backoff
+          attempt = 0
+
+          while @state.pause(@backoff.delay(attempt))
+            result = attempt_connect
+            return run_hook('on_ready') { install(result) } if result.is_a?(Connection)
+
+            attempt += 1
+            return give_up(attempt, result) if attempt >= @config.reconnect_attempts
+          end
+        end
+
+        def attempt_connect
+          open_connection
+        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
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # The current connection of a Link and its state under one lock. Waiters wake on every state change.
+      # @api private
+      class LinkState
+        attr_reader :connection
+
+        def initialize(address, reconnect:)
+          @address = address
+          @reconnect = reconnect
+          @lock = Mutex.new
+          @changed = ConditionVariable.new
+          @state = :connecting
+        end
+
+        def connected?
+          @lock.synchronize { @state == :ready && !@connection.closed? }
+        end
+
+        # Records the connection being opened so that close can abort it; raises once the link is closed.
+        def attempting(connection)
+          @lock.synchronize do
+            raise @error.exception(@error.message) if @state == :closed
+
+            @attempt = connection
+          end
+        end
+
+        # Returns false when the link was closed meanwhile.
+        def install(connection)
+          @lock.synchronize do
+            next false if @state == :closed
+
+            @connection = connection
+            @attempt = nil
+            @state = :ready
+            @changed.broadcast
+            true
+          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.
+        def start_reconnect(connection)
+          @lock.synchronize do
+            next unless @state == :ready && @connection.equal?(connection)
+
+            @reconnector = yield @reconnector
+            @state = :reconnecting
+            @changed.broadcast
+          end
+        end
+
+        # Returns the reconnect thread and the connection it is opening, for the caller to abort and join.
+        def close
+          @lock.synchronize do
+            @error = ClientClosedError.new("connection to #{@address} closed")
+            unless @state == :closed
+              @state = :closed
+              @changed.broadcast
+            end
+            [@reconnector, @attempt]
+          end
+        end
+
+        def give_up(error)
+          @lock.synchronize do
+            next if @state == :closed
+
+            @state = :closed
+            @error = error
+            @changed.broadcast
+          end
+        end
+
+        def current(wait_until)
+          @lock.synchronize do
+            loop do
+              return @connection if usable?
+              raise @error.exception(@error.message) if @state == :closed
+
+              remaining = Deadline.remaining(wait_until)
+              raise ConnectionError, "not connected to #{@address}" if remaining&.zero?
+
+              @changed.wait(@lock, remaining)
+            end
+          end
+        end
+
+        # Returns false once closed; close cuts the sleep short.
+        def pause(delay)
+          wake_at = Deadline.after(delay)
+
+          @lock.synchronize do
+            until @state == :closed || (remaining = Deadline.remaining(wake_at)).zero?
+              @changed.wait(@lock, remaining)
+            end
+            @state != :closed
+          end
+        end
+
+        private
+
+        # A connection fails its requests before its disconnect handler starts the reconnect; with reconnect
+        # on, a request in that gap waits for the next connection instead of failing on the dead one.
+        def usable?
+          @state == :ready && !(@reconnect && @connection.closed?)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # Thread-safe table of in-flight requests keyed by IPROTO sync.
+      # @api private
+      class PendingRequests
+        def initialize
+          @lock = Mutex.new
+          @futures = {}
+          @last_sync = 0
+          @failure = nil
+        end
+
+        def register
+          @lock.synchronize do
+            raise @failure.exception(@failure.message) if @failure
+
+            sync = @last_sync += 1
+            [sync, @futures[sync] = Future.new]
+          end
+        end
+
+        def resolve(sync, response)
+          delete(sync)&.resolve(response)
+        end
+
+        def push(sync, message)
+          @lock.synchronize { @futures[sync] }&.push(message)
+        end
+
+        def delete(sync)
+          @lock.synchronize { @futures.delete(sync) }
+        end
+
+        def failure
+          @lock.synchronize { @failure }
+        end
+
+        # Returns whether this call recorded the failure; later calls keep the first one.
+        def fail_all(error)
+          first, failure, futures = @lock.synchronize do
+            first = @failure.nil?
+            @failure ||= error
+            [first, @failure, @futures.values.tap { @futures.clear }]
+          end
+          futures.each { |future| future.reject(failure) }
+
+          first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # Thread-safe allocator of unique, non-zero IPROTO stream ids.
+      # @api private
+      class StreamIds
+        def initialize
+          @lock = Mutex.new
+          @last_id = 0
+        end
+
+        def next
+          @lock.synchronize { @last_id += 1 }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # Mutual exclusion whose wait is bounded by a deadline, which Mutex#synchronize can't do. Not reentrant.
+      # @api private
+      class TimedLock
+        def initialize
+          @mutex = Mutex.new
+          @released = ConditionVariable.new
+          @locked = false
+        end
+
+        # Async interrupts are held outside blocking waits, so none can land between taking the lock
+        # and entering the block, where the lock would never be released.
+        def synchronize(deadline, &block)
+          Thread.handle_interrupt(Object => :on_blocking) do
+            acquire(deadline)
+            begin
+              Thread.handle_interrupt(Object => :immediate, &block)
+            ensure
+              release
+            end
+          end
+        end
+
+        private
+
+        def acquire(deadline)
+          @mutex.synchronize do
+            while @locked
+              remaining = Deadline.remaining(deadline)
+              raise TimeoutError, 'lock wait timed out' if remaining&.zero?
+
+              @released.wait(@mutex, remaining)
+            end
+            @locked = true
+          end
+        end
+
+        def release
+          Thread.handle_interrupt(Object => :never) do
+            @mutex.synchronize do
+              @locked = false
+              @released.signal
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    module Transport
+      # Reads under one deadline for the whole read. IO#timeout bounds each read instead, so a peer
+      # sending a byte at a time could stretch it to size times the timeout.
+      # @api private
+      module TimedRead
+        module_function
+
+        def read_exactly(io, size, deadline)
+          data = String.new(capacity: size, encoding: Encoding::BINARY)
+          while data.bytesize < size
+            chunk = io.read_nonblock(size - data.bytesize, exception: false)
+            raise EOFError, 'connection closed by server' if chunk.nil?
+
+            chunk == :wait_readable ? wait_readable(io, deadline) : data << chunk
+          end
+
+          data
+        end
+
+        def wait_readable(io, deadline)
+          raise TimeoutError, 'read timed out' unless io.wait_readable(Deadline.remaining(deadline))
+        end
+        private_class_method :wait_readable
+      end
+    end
+  end
+end

data/lib/tarantool/client/uuid.rb

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

data/lib/tarantool/client/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    VERSION = '0.1.0'
+  end
+end

data/lib/tarantool/client/watcher.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Subscription returned by Client#watch.
+    class Watcher
+      attr_reader :key
+
+      def initialize(key, watchers, callback)
+        @key = key
+        @watchers = watchers
+        @callback = callback
+        @active = true
+        @notified = false
+      end
+
+      def unwatch
+        @active = false
+        @watchers.remove(self)
+
+        nil
+      end
+
+      # @api private
+      def notified? = @notified
+
+      # @api private
+      def notify(value)
+        return unless @active
+
+        @notified = true
+
+        CallbackGuard.run("tarantool watcher #{key.inspect}") { @callback.call(key, value) }
+      end
+    end
+  end
+end

data/lib/tarantool/client/watchers/dispatcher.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    class Watchers
+      # Runs jobs in order on one thread, started by the first job and again by the first one after it died.
+      # Close drops the jobs still queued.
+      # @api private
+      class Dispatcher
+        def initialize
+          @lock = Mutex.new
+          @jobs = Thread::Queue.new
+        end
+
+        def push(&job)
+          @lock.synchronize do
+            @thread = Thread.new { run }.tap { |thread| thread.name = 'tarantool-watchers' } unless @thread&.alive?
+          end
+
+          @jobs.push(job)
+        end
+
+        def close
+          @jobs.clear
+          @jobs.close
+
+          ThreadJoin.join(@thread)
+        end
+
+        private
+
+        def run
+          while (job = @jobs.pop)
+            job.call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/watchers.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Watchers of one client over IPROTO_WATCH. The server tracks keys, not watchers: WATCH goes
+    # out for the first watcher of a key and UNWATCH after the last. Callbacks run on one
+    # dispatcher thread so they never stall the reader; the ack (WATCH again) follows them, letting
+    # the server coalesce changes made meanwhile. Watched keys outlive the socket so a reconnect
+    # can subscribe to them again. A key has at most one event queued: a newer value replaces the
+    # pending one, as the server itself only promises the latest.
+    # @api private
+    class Watchers
+      def initialize(link, timeout:)
+        @link = link
+        @timeout = timeout
+        @lock = Mutex.new
+        @watchers = {}
+        @values = {}
+        @pending = {}
+        @dispatcher = Dispatcher.new
+      end
+
+      def add(key, callback)
+        watcher = Watcher.new(key, self, callback)
+        @lock.synchronize do
+          send_request(Protocol::Requests::Watch.new(key:)) unless @watchers.key?(key)
+          (@watchers[key] ||= []) << watcher
+        end
+        @dispatcher.push { catch_up(watcher) }
+
+        watcher
+      end
+
+      # Errors are swallowed: the watcher is already gone locally, and a server-side subscription left
+      # behind by an unsent UNWATCH yields at most one event, which is ignored and never acked.
+      def remove(watcher)
+        @lock.synchronize do
+          watchers = @watchers[watcher.key]
+          next unless watchers&.delete(watcher) && watchers.empty?
+
+          @watchers.delete(watcher.key)
+          @values.delete(watcher.key)
+          @pending.delete(watcher.key)
+          send_request(Protocol::Requests::Unwatch.new(key: watcher.key))
+        end
+      rescue Error
+        nil
+      end
+
+      def dispatch(key, value)
+        @lock.synchronize do
+          next unless @watchers.key?(key)
+
+          queued = @pending.key?(key)
+          @pending[key] = value
+          @dispatcher.push { deliver(key) } unless queued
+        end
+      end
+
+      # Runs the block on the dispatcher after the events queued so far.
+      def defer(&job)
+        @dispatcher.push { CallbackGuard.run('tarantool watchers: deferred job', &job) }
+      end
+
+      # A new session has no subscriptions. WATCH also makes the server send each key's current value,
+      # so watchers learn what changed while the client was away. A failed key does not skip the rest.
+      def resubscribe(connection)
+        @lock.synchronize do
+          @watchers.each_key do |key|
+            connection.notify(Protocol::Requests::Watch.new(key:), timeout: @timeout)
+          rescue Error
+            nil
+          end
+        end
+      end
+
+      # Registrations survive a fork; values and the dispatcher are per process and come back after resubscribe.
+      def restart_after_fork(new_link)
+        @link = new_link
+        @values = {}
+        @pending = {}
+        @dispatcher = Dispatcher.new
+      end
+
+      def close
+        @dispatcher.close
+        @lock.synchronize do
+          @watchers.clear
+          @values.clear
+          @pending.clear
+        end
+      end
+
+      private
+
+      def deliver(key)
+        watchers, value = take_pending(key)
+        return unless watchers
+
+        watchers.each { |watcher| watcher.notify(value) }
+
+        acknowledge(key)
+      end
+
+      # A job can outlive its event: the key may have been unwatched, and watched again, since it was queued.
+      def take_pending(key)
+        @lock.synchronize do
+          next unless @pending.key?(key)
+
+          value = @values[key] = @pending.delete(key)
+          [@watchers[key].dup, value]
+        end
+      end
+
+      # The server sends a key's value once per WATCH, so a watcher joining a watched key
+      # gets the cached one, unless an event queued before this job already reached it.
+      def catch_up(watcher)
+        known, value = @lock.synchronize { [@values.key?(watcher.key), @values[watcher.key]] }
+
+        watcher.notify(value) if known && !watcher.notified?
+      end
+
+      # Failure means the connection is gone, and the subscription with it.
+      def acknowledge(key)
+        @lock.synchronize do
+          send_request(Protocol::Requests::Watch.new(key:)) if @watchers.key?(key)
+        end
+      rescue Error
+        nil
+      end
+
+      def send_request(request)
+        @link.notify(request, timeout: @timeout)
+      end
+    end
+  end
+end