tarantool-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c88acf7dfc96a8094a2c1562b7d98c86ae22670dc1cc853f69b8324df14bada
+  data.tar.gz: c46e62c20535c8733329f6ec9db242d5a1ab9b5bd0cf0b0205c330ac80961538
+SHA512:
+  metadata.gz: 44fe72a002d29b8565fa35dcc812dfeaebcc6e8eb67a7993a275deab03136f628f235ffb345eb3df1a31ef41f9e5cedd144b27aa1a9ef53d46e54c931a3a7cf9
+  data.tar.gz: 424b07a9cd9d143c153303f07aa5986270ea0f2b1fc3acbe1c88230dff7f99d135824ad3a27676adff696cf8d5850e4b18c8486bd087d7f72aeff41d0c149027

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- IPROTO client for Tarantool 2.11+ and 3.x: CRUD by space and index name, call, eval.
+- SQL: `execute`, `prepare`.
+- Interactive transactions over streams.
+- `box.session.push` messages and watchers.
+- Background reconnect with exponential backoff and full jitter.
+- `Pool` with `:rw`, `:ro`, `:prefer_ro`, `:prefer_rw` and `:any` modes driven by `box.status`.
+- `space_info`: space format and index parts from the schema cache.
+- `select(after:)` keyset pagination.
+- `max_frame_size` configuration option (default 64 MB) caps response frame size; frames exceeding it raise `ProtocolError` and break the connection.
+- Per-request unread push messages capped at 10 000; exceeding the cap fails the request with `ProtocolError` without breaking the connection.
+- Fork safety: `Client` and `Pool` reinitialize transparently in a child process on first use; streams created before `fork` raise `ConnectionError` in the child.
+- `MP_ERROR` values nested deeper than 16 levels raise `ProtocolError` and break the connection instead of overflowing the stack.
+- A malformed decimal (more than 38 digits or a scale outside Tarantool's exponent range) raises `ProtocolError` and breaks the connection; the message carries only the payload size.
+- `connect_timeout` bounds the whole greeting read, not each byte of it.
+- Watcher events are coalesced: events for unwatched keys are dropped and a key keeps only its latest pending value.
+- A watcher callback raising any non-fatal exception is reported and no longer stops the dispatcher.
+- `close` no longer re-raises an exception that killed an internal thread; a `Pool` reset after `fork` survives inherited threads that died.
+- `Configuration#to_h` keeps the password, so `Tarantool::Client.new(**client.config.to_h)` works; `inspect`, `to_s` and `pp` still mask it.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starlexxx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,222 @@
+# tarantool-client
+
+Ruby client for [Tarantool](https://www.tarantool.io) 2.11+ and 3.x over the binary IPROTO protocol.
+
+- One connection serves any number of threads or fibers at once; responses are matched by sync.
+- Works under a Fiber Scheduler (e.g. `async`) without depending on it.
+- Reconnects in the background with exponential backoff.
+- A pool routes requests by instance role (`box.status`).
+- Single runtime dependency: `msgpack`.
+
+## Installation
+
+Requirements: Ruby >= 3.2, Tarantool 2.11+ or 3.x.
+
+```ruby
+gem 'tarantool-client'
+```
+
+```ruby
+require 'tarantool/client'
+```
+
+## Connecting
+
+```ruby
+client = Tarantool::Client.new('tcp://app:secret@localhost:3301', connect_timeout: 1, request_timeout: 5)
+client.ping           # => true
+client.server_version # => "3.2.0"
+client.config         # => the resolved Configuration
+client.close
+```
+
+URIs: `tcp://user:password@host:port`, `host:port`, `unix:/path/to/socket`. Keyword options win over the URI.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `user`, `password` | `nil` | chap-sha1 authentication; no user means guest |
+| `connect_timeout` | `3` | seconds for connect and handshake, and for a request to wait for a reconnect |
+| `request_timeout` | `10` | default timeout of every request; each call accepts `timeout:` |
+| `reconnect` | `true` | reconnect in the background after the connection is lost |
+| `reconnect_attempts` | `Float::INFINITY` | failed attempts before the client gives up |
+| `reconnect_delay` | `0.1` | base delay of the exponential backoff |
+| `reconnect_max_delay` | `5` | cap of the backoff delay |
+| `max_frame_size` | `67108864` (64 MB) | maximum allowed response frame size in bytes; larger frames raise `ProtocolError` and break the connection |
+
+Tarantool Community Edition has no TLS support. Authentication uses chap-sha1; the password is never sent in clear. `client.inspect` leaves the password out, and `Configuration#inspect`, `#to_s` and `pp` replace it with `[FILTERED]`. `Configuration#to_h` keeps it, so `Tarantool::Client.new(**client.config.to_h)` connects with the same credentials; don't log it.
+
+## Data
+
+Spaces and indexes accept names (Symbol or String) or numeric ids.
+
+```ruby
+client.select(:users, [42])
+client.select(:users, ['a@b.c'], index: :email, limit: 10, offset: 0, iterator: :ge)
+client.insert(:users, [42, 'a@b.c', 0])
+client.replace(:users, [42, 'x@y.z', 0])
+client.update(:users, [42], [['=', 1, 'new@b.c']])
+client.upsert(:users, [42, 'a@b.c', 0], [['+', 2, 1]])
+client.delete(:users, [42])
+```
+
+IPROTO update operations use 0-based field numbers: field 0 is the first field, field 1 the second, and so on.
+
+Names are resolved through a schema cache loaded from `_vspace` and `_vindex`. A request resolved by name carries the schema version. If the schema changed meanwhile, the server rejects the request without running it; the client then reloads the schema once and retries within the same timeout.
+
+`after:` continues a `select` past a tuple (keyset pagination, `IPROTO_AFTER_TUPLE`). It works on TREE indexes, including non-unique ones and `:lt`/`:le` (descending); a HASH index raises `ServerError` (code 112).
+
+```ruby
+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)
+```
+
+`space_info` returns the format and indexes from the same schema cache; an unknown name costs one reload. Inside a transaction it reads the schema the transaction started with; on a `Pool` it accepts `mode:`.
+
+```ruby
+info = client.space_info(:users)
+info.fields.map(&:name)              # => ["id", "email", "age"]
+info.primary_index.parts.map(&:name) # => ["id"]
+info.indexes['age'].unique           # => false
+```
+
+## Lua
+
+```ruby
+client.call('api.get_user', [42])
+client.eval('return ...', [1, 2])
+client.call('long_job', [], on_push: ->(message) { puts message }) # box.session.push messages
+```
+
+`api.get_user` and `long_job` stand for Lua functions you define on the server; `call` needs `execute` on them.
+
+## SQL
+
+```ruby
+result = client.execute('SELECT * FROM "users" WHERE "id" = ?', [42])
+result.rows      # => [[42, "a@b.c", 0]]
+result.columns   # => ["id", "email", "visits"]
+result.row_count # DML only
+
+statement = client.prepare('SELECT * FROM "users" WHERE "id" = ?')
+statement.execute([42])
+statement.close
+```
+
+Tarantool 2.x uppercases unquoted identifiers, so `FROM users` fails with "Space 'USERS' does not exist" on 2.11; quote both table and column names to work on both versions. `SqlResult` is not `Enumerable`; iterate rows with `result.rows.each`.
+
+## Transactions
+
+Interactive transactions run on their own IPROTO stream and need `memtx_use_mvcc_engine = true` on the server.
+
+```ruby
+client.transaction(isolation: :read_committed, timeout: 5) do |tx|
+  tx.insert(:users, [43, 'b@c.d', 0])
+  tx.update(:users, [42], [['+', 2, 1]])
+end
+```
+
+The block argument is a `Tarantool::Client::Stream` and supports the same data operations as `Client`. The block's value is returned after COMMIT. Any other exit from the block rolls the transaction back. Isolation levels: `:default`, `:read_committed`, `:read_confirmed`, `:best_effort`, `:linearizable`. A nested `transaction` raises `TransactionError`, and so does a schema change during the transaction (retry the whole transaction).
+
+## Watchers
+
+```ruby
+watcher = client.watch('box.status') { |key, value| puts value['is_ro'] }
+watcher.unwatch
+```
+
+The block gets the current value first (`nil` if the key was never broadcast), then every change. Blocks run on one dispatcher thread per client; exceptions are reported with `warn`.
+
+## Reconnect
+
+- When the connection is lost, every request waiting for a reply fails with `ConnectionError`. Requests are never retried automatically.
+- A background thread reconnects with exponential backoff and full jitter. Rejected credentials count as a failed attempt.
+- Requests issued meanwhile wait for the new connection up to `connect_timeout` (and never past their own timeout), then raise `ConnectionError`.
+- After reconnecting, the client performs the handshake and loads the schema of the new instance before any request can use it. It then subscribes the watchers again, and each watcher gets the current value.
+- A transaction cannot survive a reconnect: the server rolls it back, and the next call in the block raises `TransactionError`.
+- Prepared statements belong to the old session and are gone.
+- After `reconnect_attempts` failures the client stops, and every request raises `ConnectionError`. With `reconnect: false`, requests after a loss raise `ConnectionError` right away.
+
+## Pool
+
+```ruby
+pool = Tarantool::Client::Pool.new(%w[tcp://db1:3301 tcp://db2:3301], user: 'app', password: 'secret')
+pool.select(:users, [42], mode: :prefer_ro)
+pool.insert(:users, [44, 'c@d.e', 0], mode: :rw)
+pool.transaction { |tx| tx.delete(:users, [44]) } # always on a writable instance
+pool.close
+```
+
+`watch`, `server_version`, and `connected?` are available on `Client` only, not on `Pool`. Every other operation accepts `mode:`:
+
+| Mode | Instances |
+|---|---|
+| `:any` (default) | every instance whose role is known |
+| `:rw` | writable ones |
+| `:ro` | read-only ones |
+| `:prefer_ro` | read-only ones, writable if none |
+| `:prefer_rw` | writable ones, read-only if none |
+
+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.
+
+## 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.
+
+Streams (interactive transactions) cannot cross a fork boundary. Using a stream that was created before `fork` in a child raises `ConnectionError`.
+
+No configuration is needed; the detection is a single PID comparison on every request.
+
+## Errors
+
+```
+Tarantool::Error
+├── ConnectionError            # refused, lost or broken connection; low-level errors are in #cause
+│   └── ClientClosedError
+├── TimeoutError
+├── AuthenticationError        # #code
+├── ProtocolError
+├── SchemaError                # unknown space or index name
+├── ServerError                # #code, #error_stack, #schema_version
+├── TransactionError
+└── NoAvailableInstanceError
+```
+
+The error classes are flat under `Tarantool::`, e.g. `Tarantool::ServerError`, not `Tarantool::Client::ServerError`.
+tarantool-crud and tarantool-model errors also descend from `Tarantool::Error`.
+
+`box.error` objects inside returned data decode into `Tarantool::Client::BoxError`.
+
+## Development
+
+```sh
+bundle install                          # from the repo root; the gem has no Gemfile of its own
+cd tarantool-client
+bundle exec rspec                       # unit specs
+docker compose -f docker-compose.yml up -d --wait
+INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3301 bundle exec rspec   # 2.11; 3302 for 3.x
+bundle exec rubocop
+```
+
+Reconnect and pool specs restart their own pair of instances:
+
+```sh
+docker compose -p tarantool-failover -f docker-compose.yml --profile failover up -d --wait failover-a failover-b
+TARANTOOL_FAILOVER_URIS=tcp://app:secret@localhost:3311,tcp://app:secret@localhost:3312 \
+TARANTOOL_FAILOVER_CONTAINERS=tarantool-failover-failover-a-1,tarantool-failover-failover-b-1 \
+bundle exec rspec --tag failover
+```
+
+Using podman instead of docker: prefix the `bundle exec rspec --tag failover` command above with `CONTAINER_CLI=podman`; the reconnect spec uses it to restart containers (default `docker`).
+
+## Public API
+
+`Tarantool::Client`, `Tarantool::Client::Pool`, `Tarantool::Client::Stream` (yielded by `transaction`),
+`Watcher` (returned by `watch`), `SqlResult`, `PreparedStatement`, `SpaceInfo`, `IndexInfo`, `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
+and may change in any release.
+
+## License
+
+MIT

data/lib/tarantool/client/backoff.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Exponential backoff with full jitter: the delay before attempt n is uniformly random in
+    # [0, min(max, base * 2**n)), so clients that lost the same server don't reconnect in lockstep.
+    # @api private
+    class Backoff
+      # Keeps 2**n small for endless retries; the cap is reached long before.
+      MAX_EXPONENT = 32
+
+      def initialize(base:, max:, random: Random.new)
+        @base = base
+        @max = max
+        @random = random
+      end
+
+      def delay(attempt)
+        @random.rand * [@max, @base * (2**[attempt, MAX_EXPONENT].min)].min
+      end
+    end
+  end
+end

data/lib/tarantool/client/box_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # A box.error object returned as data (MP_ERROR extension), with its cause chain.
+    BoxError = Data.define(:type, :message, :code, :file, :line, :errno, :fields, :cause) do
+      def self.from_stack(entries)
+        entries.reverse_each.reduce(nil) do |cause, entry|
+          attributes = entry.transform_keys(Protocol::Constants::ERROR_FIELDS)
+          new(**Protocol::Constants::ERROR_FIELDS.values.to_h { |field| [field, attributes[field]] }, cause:)
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/client/callback_guard.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Runs user code on the shared watcher dispatcher, which must outlive whatever that code raises. Exit and
+    # signals go to the main thread, where they would have ended the process without the dispatcher;
+    # NoMemoryError still ends the worker, and the next job starts a new one.
+    # @api private
+    module CallbackGuard
+      module_function
+
+      def run(description)
+        yield
+      rescue SystemExit, SignalException => e
+        Thread.main.raise(e)
+      rescue NoMemoryError
+        raise
+      rescue Exception => e
+        warn("#{description} failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/tarantool/client/configuration.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Tarantool
+  class Client
+    # Immutable connection settings built from a URI and keyword options; options win.
+    Configuration = Data.define(
+      :host, :port, :path, :user, :password, :connect_timeout, :request_timeout,
+      :reconnect, :reconnect_attempts, :reconnect_delay, :reconnect_max_delay,
+      :max_frame_size
+    ) do
+      def self.build(uri = nil, **options)
+        new(**defaults, **parse_uri(uri), **options)
+      end
+
+      def self.defaults
+        {
+          host: 'localhost', port: 3301, path: nil, user: nil, password: nil, connect_timeout: 3, request_timeout: 10,
+          reconnect: true, reconnect_attempts: Float::INFINITY, reconnect_delay: 0.1, reconnect_max_delay: 5,
+          max_frame_size: 64 * 1024 * 1024
+        }
+      end
+
+      def self.parse_uri(uri)
+        return {} if uri.nil?
+        return parse_unix_uri(uri) if uri.match?(%r{\Aunix/?:})
+
+        parse_tcp_uri(uri)
+      end
+
+      def self.parse_unix_uri(uri)
+        match = %r{\Aunix/?:(?://(?=/))?(.+)\z}.match(uri)
+        path = match && match[1]
+        raise ArgumentError, 'invalid Tarantool URI' if path.nil? || path.match?(%r{\A/*\z})
+
+        { path: path }
+      end
+
+      def self.parse_tcp_uri(uri)
+        parsed = URI.parse(uri.include?('://') ? uri : "tcp://#{uri}")
+        user = parsed.user == '' ? nil : parsed.user
+
+        {
+          host: parsed.hostname,
+          port: parsed.port,
+          user: user && URI.decode_uri_component(user),
+          password: parsed.password && URI.decode_uri_component(parsed.password)
+        }.compact
+      rescue URI::InvalidURIError
+        raise ArgumentError, 'invalid Tarantool URI'
+      end
+      private_class_method :defaults, :parse_uri, :parse_unix_uri, :parse_tcp_uri
+
+      def address
+        return path if path
+
+        host.include?(':') ? "[#{host}]:#{port}" : "#{host}:#{port}"
+      end
+
+      def inspect
+        fields = to_h.merge(password: password && '[FILTERED]').map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+
+        "#<data #{self.class.name} #{fields}>"
+      end
+      alias_method :to_s, :inspect
+
+      def pretty_print(printer) = printer.text(inspect)
+    end
+  end
+end

data/lib/tarantool/client/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Tarantool
+  # Base class for every error raised by tarantool-ruby gems.
+  class Error < StandardError; end
+
+  # Socket-level failure: refused, lost or broken connection.
+  class ConnectionError < Error; end
+
+  # Request issued after the connection was closed by the client.
+  class ClientClosedError < ConnectionError; end
+
+  # No response within the request timeout.
+  class TimeoutError < Error; end
+
+  # Server rejected the credentials.
+  class AuthenticationError < Error
+    attr_reader :code
+
+    def initialize(message = nil, code: nil)
+      super(message)
+      @code = code
+    end
+  end
+
+  # Malformed or unexpected data from the server.
+  class ProtocolError < Error; end
+
+  # Space or index name cannot be resolved.
+  class SchemaError < Error; end
+
+  # Transaction misuse or a transaction that can no longer proceed.
+  class TransactionError < Error; end
+
+  # No pool instance can serve a request in the requested mode.
+  class NoAvailableInstanceError < Error; end
+
+  # Error returned by the server for a request.
+  class ServerError < Error
+    attr_reader :code, :error_stack, :schema_version
+
+    def self.from_response(response)
+      new(
+        response.error_message,
+        code: response.error_code, error_stack: response.error_stack, schema_version: response.schema_version
+      )
+    end
+
+    def initialize(message, code:, error_stack: [], schema_version: nil)
+      super(message)
+      @code = code
+      @error_stack = error_stack
+      @schema_version = schema_version
+    end
+  end
+end

data/lib/tarantool/client/fork_safety.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # A client created before fork reopens its link in the child on first use: the parent's reader, reconnect
+    # and dispatcher threads don't exist there. Closing the inherited socket in the child sends nothing.
+    # @api private
+    module ForkSafety
+      private
+
+      def ensure_fork_safe
+        return if @pid == Process.pid
+
+        @reinit_lock.synchronize { reopen_after_fork unless @pid == Process.pid }
+      end
+
+      def reopen_after_fork
+        close_inherited_link
+        open_link
+      end
+
+      # Joining a thread that died with an exception re-raises it; nothing from the parent may stop the reopen.
+      def close_inherited_link
+        @link.close
+      rescue StandardError
+        nil
+      end
+
+      # Watcher registrations outlive a fork; on_ready resubscribes them on the new link.
+      def open_link
+        @link = Transport::Link.new(@config, **link_hooks)
+        @watchers&.restart_after_fork(@link)
+        @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
+      end
+    end
+  end
+end

data/lib/tarantool/client/index_info.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # One index of a space as listed in _vindex.
+    IndexInfo = Data.define(:id, :name, :type, :unique, :parts) do
+      def self.from_tuple(tuple, fields)
+        _space_id, id, name, type, opts, parts = tuple
+
+        new(
+          id:, name:, type:, unique: (opts || {}).fetch('unique', true),
+          parts: (parts || []).map { |raw| IndexInfo::Part.from_raw(raw, fields) }
+        )
+      end
+    end
+
+    # `fieldno` is 0-based; `name` comes from the space format and is nil for a field beyond it.
+    IndexInfo::Part = Data.define(:fieldno, :name, :type, :is_nullable, :path) do
+      # _vindex keeps parts either as [fieldno, type] or as a map with nullability and a JSON path.
+      def self.from_raw(raw, fields)
+        fieldno, type, is_nullable, path = raw.is_a?(Hash) ? raw.values_at('field', 'type', 'is_nullable', 'path') : raw
+
+        new(fieldno:, name: fields[fieldno]&.name, type:, is_nullable: is_nullable || false, path:)
+      end
+    end
+  end
+end

data/lib/tarantool/client/interval.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # A Tarantool datetime.interval; adjust is :none, :excess or :last.
+    Interval = Data.define(:year, :month, :week, :day, :hour, :min, :sec, :nsec, :adjust) do
+      def initialize(year: 0, month: 0, week: 0, day: 0, hour: 0, min: 0, sec: 0, nsec: 0, adjust: :none)
+        units = { year:, month:, week:, day:, hour:, min:, sec:, nsec: }
+        validate_units(units)
+        super
+      end
+
+      private
+
+      def validate_units(units)
+        offenders = units.reject { |_name, value| value.is_a?(Integer) }
+        return if offenders.empty?
+
+        details = offenders.map { |name, value| "#{name}=#{value.inspect}" }.join(', ')
+
+        raise ArgumentError, "interval units must be integers: #{details}"
+      end
+    end
+  end
+end

data/lib/tarantool/client/operations.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Tarantool
+  class Client
+    # Data operations, call, eval and SQL. Includers implement `perform(request, timeout:, on_push: nil)`,
+    # `perform_on_space(space, index, timeout:) { |space_id, index_id| request }`, which returns the response to
+    # the request built by the block, and `lookup_space(space, timeout)`, which returns its SpaceInfo.
+    # @api private
+    module Operations
+      def ping(timeout: nil)
+        perform(Protocol::Requests::Ping.new, timeout:)
+
+        true
+      end
+
+      def space_info(space, timeout: nil)
+        lookup_space(space, timeout)
+      end
+
+      def select(space, key = [], index: 0, limit: Protocol::Constants::MAX_LIMIT, offset: 0, iterator: :eq,
+                 after: nil, timeout: nil)
+        perform_on_space(space, index, timeout:) do |space_id, index_id|
+          Protocol::Requests::Select.new(space_id:, index_id:, key: key_tuple(key), limit:, offset:, iterator:, after:)
+        end.data
+      end
+
+      def insert(space, tuple, timeout: nil)
+        perform_on_space(space, 0, timeout:) do |space_id|
+          Protocol::Requests::Insert.new(space_id:, tuple:)
+        end.data.first
+      end
+
+      def replace(space, tuple, timeout: nil)
+        perform_on_space(space, 0, timeout:) do |space_id|
+          Protocol::Requests::Replace.new(space_id:, tuple:)
+        end.data.first
+      end
+
+      def update(space, key, operations, index: 0, timeout: nil)
+        perform_on_space(space, index, timeout:) do |space_id, index_id|
+          Protocol::Requests::Update.new(space_id:, index_id:, key: key_tuple(key), operations:)
+        end.data.first
+      end
+
+      def upsert(space, tuple, operations, timeout: nil)
+        perform_on_space(space, 0, timeout:) do |space_id|
+          Protocol::Requests::Upsert.new(space_id:, tuple:, operations:)
+        end
+
+        nil
+      end
+
+      def delete(space, key, index: 0, timeout: nil)
+        perform_on_space(space, index, timeout:) do |space_id, index_id|
+          Protocol::Requests::Delete.new(space_id:, index_id:, key: key_tuple(key))
+        end.data.first
+      end
+
+      # on_push runs in the calling thread for each box.session.push message; an exception
+      # raised by it abandons the call.
+      def call(function_name, arguments = [], timeout: nil, on_push: nil)
+        perform(Protocol::Requests::Call.new(function_name:, arguments:), timeout:, on_push:).data
+      end
+
+      def eval(expression, arguments = [], timeout: nil)
+        perform(Protocol::Requests::Eval.new(expression:, arguments:), timeout:).data
+      end
+
+      def execute(sql, bindings = [], timeout: nil)
+        statement = sql.is_a?(PreparedStatement) ? sql.id : sql
+
+        SqlResult.from_response(perform(Protocol::Requests::Execute.new(statement:, bindings:), timeout:))
+      end
+
+      # A prepared statement belongs to the session, so a reconnect discards it.
+      def prepare(sql, timeout: nil)
+        response = perform(Protocol::Requests::Prepare.new(statement: sql), timeout:)
+
+        PreparedStatement.new(response.body.fetch(Protocol::Constants::STMT_ID), method(:perform))
+      end
+
+      private
+
+      def key_tuple(key)
+        key.is_a?(Array) ? key : [key]
+      end
+    end
+  end
+end