tarantool-model 0.1.0 → 0.3.0

data/lib/tarantool/model/testing/memory_storage/declaration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # One space in tarantool-schema's ensure_space shape, checked and turned into the SpaceInfo that
+        # Storage::Box::Layout reads. Types are checked here but values are not type-checked.
+        # @api private
+        class Declaration
+          SPACE_KEYS = %i[engine format indexes].freeze
+          FIELD_KEYS = %i[name type is_nullable].freeze
+          TYPES = %w[unsigned string integer number double boolean decimal uuid datetime interval varbinary scalar
+                     array map any].freeze
+
+          attr_reader :space_info, :sequence
+
+          def initialize(name, schema)
+            owner = "space #{name}"
+            Keys.check!(schema, SPACE_KEYS, owner)
+            fields = Keys.fetch!(schema, :format, owner).map { |entry| field(entry, owner) }
+            Keys.distinct!(fields.map(&:name), owner)
+            indexes = index_declarations(Keys.fetch!(schema, :indexes, owner), fields, owner)
+            @space_info = build_space_info(name, fields, indexes)
+            @sequence = indexes.first.sequence
+          end
+
+          private
+
+          def build_space_info(name, fields, indexes)
+            Tarantool::Client::SpaceInfo.new(
+              id: 0, name: name.to_s, fields:, indexes: indexes.to_h { |index| [index.info.name, index.info] }
+            )
+          end
+
+          def field(entry, owner)
+            Keys.check!(entry, FIELD_KEYS, "#{owner} field")
+            name = Keys.fetch!(entry, :name, "#{owner} field").to_s
+            type = Keys.one_of!(entry.fetch(:type, 'any'), TYPES, "#{owner} field #{name}")
+
+            Tarantool::Client::SpaceInfo::Field.new(name:, type:, is_nullable: entry.fetch(:is_nullable, false))
+          end
+
+          def index_declarations(entries, fields, owner)
+            raise ArgumentError, "#{owner} has no indexes" if entries.empty?
+
+            entries.each_with_index.map { |entry, id| IndexDeclaration.new(entry, id:, fields:, owner:) }
+                   .tap { |indexes| Keys.distinct!(indexes.map { |index| index.info.name }, owner) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/index_declaration.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # One index of a space declaration; the first index of a space is the primary one.
+        # @api private
+        class IndexDeclaration
+          KEYS = %i[name parts unique type sequence].freeze
+          PART_KEYS = %i[field type is_nullable path].freeze
+          TYPES = %w[tree hash].freeze
+          SEQUENCE_TYPES = %w[unsigned integer].freeze
+
+          attr_reader :info, :sequence
+
+          def initialize(entry, id:, fields:, owner:)
+            Keys.check!(entry, KEYS, "#{owner} index")
+            @owner = "#{owner} index #{Keys.fetch!(entry, :name, "#{owner} index")}"
+            @fields = fields
+            @info = Tarantool::Client::IndexInfo.new(
+              id:, name: entry[:name].to_s, type: Keys.one_of!(entry.fetch(:type, 'tree'), TYPES, @owner),
+              unique: entry.fetch(:unique, true), parts: parts(Keys.fetch!(entry, :parts, @owner))
+            )
+            check_unique!
+            check_nullable!
+            @sequence = sequence?(entry.fetch(:sequence, false))
+          end
+
+          private
+
+          def parts(entries)
+            raise ArgumentError, "#{@owner} has no parts" if entries.empty?
+
+            entries.map { |entry| part(entry.is_a?(Hash) ? entry : { field: entry }) }
+          end
+
+          def part(entry)
+            Keys.check!(entry, PART_KEYS, "#{@owner} part")
+            raise ArgumentError, "#{@owner}: path parts are not supported" if entry[:path]
+
+            name = Keys.fetch!(entry, :field, "#{@owner} part").to_s
+            fieldno = @fields.index { |field| field.name == name }
+            raise ArgumentError, "#{@owner} has no field #{name}" unless fieldno
+
+            field = @fields[fieldno]
+            type = Keys.one_of!(entry.fetch(:type, field.type), Declaration::TYPES, "#{@owner} part #{name}")
+
+            Tarantool::Client::IndexInfo::Part.new(
+              fieldno:, name:, type:, is_nullable: entry.fetch(:is_nullable, field.is_nullable), path: nil
+            )
+          end
+
+          def check_unique!
+            return if @info.unique
+
+            raise ArgumentError, "#{@owner}: a primary index must be unique" if @info.id.zero?
+            raise ArgumentError, "#{@owner}: a hash index must be unique" if @info.type == 'hash'
+          end
+
+          def check_nullable!
+            return unless @info.parts.any?(&:is_nullable)
+
+            raise ArgumentError, "#{@owner}: a primary index can not contain nullable parts" if @info.id.zero?
+            raise ArgumentError, "#{@owner}: a hash index does not support nullable parts" if @info.type == 'hash'
+          end
+
+          def sequence?(requested)
+            return false unless requested
+            return true if @info.id.zero? && @info.parts.size == 1 && SEQUENCE_TYPES.include?(@info.parts.first.type)
+
+            raise ArgumentError, "#{@owner}: a sequence needs a primary index with one unsigned or integer part"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/keys.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # Shape checks shared by the declaration classes; a bad declaration raises ArgumentError naming its owner.
+        # @api private
+        module Keys
+          module_function
+
+          def check!(declaration, allowed, owner)
+            raise ArgumentError, "#{owner} must be a Hash, got #{declaration.inspect}" unless declaration.is_a?(Hash)
+
+            unknown = declaration.keys - allowed
+            raise ArgumentError, "#{owner} has unknown keys #{unknown.join(', ')}" if unknown.any?
+          end
+
+          def fetch!(declaration, key, owner)
+            declaration.fetch(key) { raise ArgumentError, "#{owner} has no #{key}" }
+          end
+
+          def one_of!(value, allowed, owner)
+            name = value.to_s
+            raise ArgumentError, "#{owner} has unknown type #{value.inspect}" unless allowed.include?(name)
+
+            name
+          end
+
+          def distinct!(names, owner)
+            duplicates = names.tally.select { |_name, count| count > 1 }.keys
+            raise ArgumentError, "#{owner} has duplicate names #{duplicates.join(', ')}" if duplicates.any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/operations.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # Update operators the model sends: '=' from save, '+' and '-' from the counters. Returns a new tuple.
+        # @api private
+        class Operations
+          ARITHMETIC = %w[+ -].freeze
+
+          def initialize(space_info)
+            @names = space_info.fields.map(&:name)
+          end
+
+          def apply(tuple, operations)
+            operations.each_with_object(tuple.dup) do |(operator, name, value), result|
+              fieldno = @names.index(name.to_s) || raise(Violation.unknown_field(name))
+              result[fieldno] = value_after(operator.to_s, name, result[fieldno], value)
+            end
+          end
+
+          private
+
+          def value_after(operator, name, current, value)
+            return value if operator == '='
+            unless ARITHMETIC.include?(operator)
+              raise NotSupportedError, "MemoryStorage has no #{operator} update operator"
+            end
+            raise Violation.operand(operator, name) unless current.is_a?(Numeric) && value.is_a?(Numeric)
+
+            current.public_send(operator, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/order.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # Tree index order of keys of equal length: nil first, as MP_NIL, then false before true, then Ruby's
+        # <=>. Values Ruby cannot compare, such as mixed types in a scalar field, raise ArgumentError.
+        # @api private
+        module Order
+          module_function
+
+          def compare(left, right)
+            left.zip(right).each do |a, b|
+              result = value(a, b)
+              return result unless result.zero?
+            end
+
+            0
+          end
+
+          def value(left, right)
+            return nil_rank(left) <=> nil_rank(right) if left.nil? || right.nil?
+            return as_int(left) <=> as_int(right) if boolean?(left) && boolean?(right)
+
+            (left <=> right) || raise(ArgumentError, "MemoryStorage cannot order #{left.inspect} and #{right.inspect}")
+          end
+
+          def nil_rank(value)
+            value.nil? ? 0 : 1
+          end
+
+          def boolean?(value)
+            [true, false].include?(value)
+          end
+
+          def as_int(value)
+            value ? 1 : 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/scan.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # Tuples one select or count sees through an index: ordered by the index key, then the primary key (le and
+        # lt walk backwards), filtered by the key prefix condition, then continued strictly past `after`.
+        # @api private
+        class Scan
+          MATCHES = {
+            eq: :zero?.to_proc, ge: ->(result) { result >= 0 }, gt: :positive?.to_proc,
+            le: ->(result) { result <= 0 }, lt: :negative?.to_proc, all: ->(_result) { true }
+          }.freeze
+          DESCENDING = %i[le lt].freeze
+          HASH_ITERATORS = %i[eq gt all].freeze
+
+          def initialize(space_info, index)
+            @space_info = space_info
+            @index = index
+            @primary = space_info.primary_index
+          end
+
+          def call(tuples, key:, iterator:, after:)
+            match = matcher(iterator)
+            raise Violation.key_part_count(@index.parts.size, key.size) if key.size > @index.parts.size
+
+            check_hash!(key, iterator, after)
+            sign = sign_for(iterator)
+            found = matching(sorted(tuples, sign), key, match)
+
+            after ? strictly_after(found, after, sign) : found
+          end
+
+          private
+
+          # memtx starts a tree :all at the key, like :ge; a hash :all ignores the key.
+          def matcher(iterator)
+            return MATCHES[:ge] if iterator == :all && @index.type == 'tree'
+
+            MATCHES.fetch(iterator) { raise ArgumentError, "unsupported iterator #{iterator.inspect}" }
+          end
+
+          def sign_for(iterator)
+            DESCENDING.include?(iterator) ? -1 : 1
+          end
+
+          def matching(tuples, key, match)
+            tuples.select { |tuple| key.empty? || match.call(compare_key(tuple, key)) }
+          end
+
+          def strictly_after(tuples, after, sign)
+            tuples.select { |tuple| Order.compare(position(tuple), position(after)) * sign == 1 }
+          end
+
+          def sorted(tuples, sign)
+            tuples.sort { |left, right| Order.compare(position(left), position(right)) * sign }
+          end
+
+          def compare_key(tuple, key)
+            Order.compare(@index.parts.first(key.size).map { |part| tuple[part.fieldno] }, key)
+          end
+
+          def position(tuple)
+            (@index.parts + @primary.parts).map { |part| tuple[part.fieldno] }
+          end
+
+          def check_hash!(key, iterator, after)
+            return unless @index.type == 'hash'
+            raise Violation.partial_hash_key(@index.parts.size, key.size) if partial?(key)
+            raise Violation.iterator(@index.name, @space_info.name) unless HASH_ITERATORS.include?(iterator)
+            raise Violation.pagination(@index.name, @space_info.name) if after
+          end
+
+          def partial?(key)
+            !key.empty? && key.size != @index.parts.size
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/sequence.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # The sequence of a primary key field: fills nil from 1 and moves past explicit Integer values. Never
+        # restored by a rollback, as in Tarantool.
+        # @api private
+        class Sequence
+          def initialize(fieldno)
+            @fieldno = fieldno
+            @counter = 0
+          end
+
+          def fill(tuple)
+            value = tuple[@fieldno]
+            if value.nil?
+              tuple[@fieldno] = @counter += 1
+            elsif value.is_a?(Integer)
+              @counter = [@counter, value].max
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/space.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # Rows of one space keyed by primary key, with the checks Tarantool makes on write. Values are deep-copied
+        # in and out, and a stored tuple is never changed in place, so a snapshot is a shallow copy of the rows.
+        # @api private
+        class Space
+          attr_reader :info, :layout
+
+          def initialize(info, sequence:)
+            @info = info
+            @layout = Storage::Box::Layout.new(info)
+            @primary = info.primary_index
+            @sequence = Sequence.new(@primary.parts.first.fieldno) if sequence
+            @required = required_fieldnos
+            @rows = {}
+          end
+
+          # Storage::Box gets by a select with limit 1, so a partial key gives its first match.
+          def get(key)
+            return scan(index: nil, key:, iterator: :eq, after: nil).first unless key.size == @primary.parts.size
+
+            copy(@rows[copy(key)])
+          end
+
+          def insert(tuple)
+            tuple = copy(tuple)
+            @sequence&.fill(tuple)
+
+            store(tuple, replacing: nil)
+          end
+
+          def update(key, operations)
+            key = exact(key)
+            current = @rows[key]
+            return unless current
+
+            updated = Operations.new(@info).apply(current, copy(operations))
+            raise Violation.primary_key_update(@info.name) unless key_of(updated, @primary) == key
+
+            store(updated, replacing: key)
+          end
+
+          def delete(key)
+            copy(@rows.delete(exact(key)))
+          end
+
+          def scan(index:, key:, iterator:, after:)
+            Scan.new(@info, index_info(index)).call(@rows.values, key: copy(key), iterator:, after: copy(after))
+                .map { |tuple| copy(tuple) }
+          end
+
+          def index?(name)
+            name.nil? || name.is_a?(Integer) || @info.indexes.key?(name.to_s)
+          end
+
+          def snapshot
+            @rows.dup
+          end
+
+          def restore(rows)
+            @rows = rows
+          end
+
+          private
+
+          def index_info(name)
+            return @primary if name.nil?
+
+            found = name.is_a?(Integer) ? @info.indexes.each_value.find { |index| index.id == name } : by_name(name)
+            found || raise(Violation.unknown_index(name, @info.name))
+          end
+
+          def by_name(name)
+            @info.indexes[name.to_s]
+          end
+
+          def store(tuple, replacing:)
+            check_nils(tuple)
+            check_unique(tuple, replacing)
+            @rows.delete(replacing) if replacing
+            @rows[key_of(tuple, @primary)] = tuple
+
+            copy(tuple)
+          end
+
+          def check_nils(tuple)
+            @required.each do |fieldno|
+              raise Violation.nil_field(fieldno, @info.fields[fieldno]) if tuple[fieldno].nil?
+            end
+          end
+
+          def check_unique(tuple, replacing)
+            @info.indexes.each_value.select(&:unique).each do |index|
+              key = key_of(tuple, index)
+              next if key.include?(nil)
+
+              _, old = @rows.find { |row_key, row| row_key != replacing && key_of(row, index) == key }
+              next unless old
+
+              raise RecordNotUnique, duplicate_key_message(index, old, tuple)
+            end
+          end
+
+          def duplicate_key_message(index, old, tuple)
+            "Duplicate key exists in unique index \"#{index.name}\" in space \"#{@info.name}\" with old tuple - " \
+              "#{old.inspect} and new tuple - #{tuple.inspect}"
+          end
+
+          def required_fieldnos
+            strict_parts = @info.indexes.each_value.flat_map(&:parts).reject(&:is_nullable).map(&:fieldno)
+
+            @info.fields.each_index.select do |fieldno|
+              field = @info.fields[fieldno]
+              strict_parts.include?(fieldno) || !(field.is_nullable || field.type == 'any')
+            end
+          end
+
+          def exact(key)
+            raise Violation.exact_match(@primary.parts.size, key.size) unless key.size == @primary.parts.size
+
+            copy(key)
+          end
+
+          def key_of(tuple, index)
+            index.parts.map { |part| tuple[part.fieldno] }
+          end
+
+          # Codec is @api private in tarantool-client, but released together with tarantool-model in this
+          # monorepo; only the wire round trip turns Symbols into Strings and rejects values Tarantool can't store.
+          def copy(value)
+            value && Client::Protocol::Codec::FACTORY.load(Client::Protocol::Codec::FACTORY.dump(value))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage/violation.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      class MemoryStorage
+        # What the server would reject, with its error code and text. Never leaves MemoryStorage: the mode turns it
+        # into the error class the application sees in production. `kind` is :space, :index, :nil_field or :server.
+        # @api private
+        class Violation < StandardError
+          attr_reader :kind, :code, :subject
+
+          def self.nil_field(fieldno, field)
+            new("Tuple field #{fieldno + 1} (#{field.name}) type does not match one required by operation: " \
+                "expected #{field.type}, got nil", kind: :nil_field, code: 23, subject: field.name)
+          end
+
+          def self.primary_key_update(space)
+            new("Attempt to modify a tuple field which is part of primary index in space '#{space}'", code: 94)
+          end
+
+          def self.operand(operator, name)
+            new("Argument type in operation '#{operator}' on field '#{name}' does not match field type: " \
+                'expected a number', code: 26)
+          end
+
+          def self.unknown_field(name)
+            new("Field '#{name}' was not found in the tuple", code: 201)
+          end
+
+          def self.key_part_count(max, got)
+            new("Invalid key part count (expected [0..#{max}], got #{got})", code: 31)
+          end
+
+          def self.exact_match(expected, got)
+            new("Invalid key part count in an exact match (expected #{expected}, got #{got})", code: 19)
+          end
+
+          def self.partial_hash_key(expected, got)
+            new("HASH index  does not support selects via a partial key (expected #{expected} parts, got #{got}). " \
+                'Please Consider changing index type to TREE.', code: 136)
+          end
+
+          def self.iterator(index, space)
+            new("Index '#{index}' (HASH) of space '#{space}' (memtx) does not support requested iterator type",
+                code: 112)
+          end
+
+          def self.pagination(index, space)
+            new("Index '#{index}' (HASH) of space '#{space}' (memtx) does not support pagination", code: 112)
+          end
+
+          def self.unknown_space(name)
+            new("space '#{name}' not found", kind: :space, subject: name)
+          end
+
+          def self.unknown_index(index, space)
+            new("index '#{index}' not found in space #{space}", kind: :index, subject: index)
+          end
+
+          def initialize(message, kind: :server, code: nil, subject: nil)
+            super(message)
+            @kind = kind
+            @code = code
+            @subject = subject
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tarantool/model/testing/memory_storage.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module Model
+    module Testing
+      # In-memory storage for application tests, without a Tarantool server. Spaces are declared in
+      # tarantool-schema's ensure_space shape. `behaves_like: :box` keeps the Storage::Box contract, `:crud` the
+      # Storage::Crud one: what the server would reject is raised with the classes and codes the application sees
+      # in production. The README lists what it does not model.
+      class MemoryStorage
+        MODES = { box: BoxMode, crud: CrudMode }.freeze
+        private_constant :MODES
+
+        def self.from_definition(definition, **)
+          new(definition.to_h, **)
+        end
+
+        def initialize(spaces, behaves_like: :box)
+          @mode = MODES.fetch(behaves_like) do
+            raise ArgumentError, "behaves_like must be one of #{MODES.keys.join(', ')}, got #{behaves_like.inspect}"
+          end.new
+          Keys.distinct!(spaces.keys.map(&:to_s), 'MemoryStorage')
+          @spaces = spaces.to_h { |name, schema| [name.to_s, build_space(name, schema)] }
+        end
+
+        def verify(space, attributes:, primary_key:)
+          @mode.verify(attributes:, primary_key:) { perform(space, :get, &:itself) }
+        end
+
+        def get(space, key)
+          single(space, :get) { |table| @mode.get(table, key) }
+        end
+
+        def insert(space, attributes)
+          single(space, :insert) { |table| table.insert(@mode.to_tuple(table, attributes)) }
+        end
+
+        def update(space, key, operations)
+          single(space, :update) { |table| table.update(key, operations) }
+        end
+
+        def delete(space, key)
+          single(space, :delete) { |table| table.delete(key) }
+        end
+
+        def select(space, index:, key:, iterator:, limit:, after:)
+          perform(space, :select) do |table|
+            tuples = @mode.scan(table, index:, key:, iterator:, after:)
+
+            (limit ? tuples.first(limit) : tuples).map { |tuple| @mode.row(table, tuple, single: false) }
+          end
+        end
+
+        def count(space, index:, key:, iterator:)
+          @mode.count!
+
+          perform(space, :count) { |table| @mode.scan(table, index:, key:, iterator:, after: nil).size }
+        end
+
+        def supports_transactions? = @mode.supports_transactions?
+
+        # Writes apply at once; the rows are restored unless the block finishes normally. `isolation:` and
+        # `timeout:` are accepted and ignored. Sequences are not restored, as in Tarantool.
+        def transaction(**, &)
+          @mode.transaction!
+          raise Tarantool::TransactionError, 'nested transactions are not supported' if Transactions.handle(self)
+
+          snapshots = @spaces.transform_values(&:snapshot)
+          committed = false
+          Transactions.open(self, :memory, &).tap { committed = true }
+        ensure
+          snapshots&.each { |name, rows| @spaces.fetch(name).restore(rows) } unless committed
+        end
+
+        private
+
+        def perform(space, operation)
+          yield @spaces.fetch(space.to_s) { raise Violation.unknown_space(space) }
+        rescue Violation => e
+          raise @mode.error(e, operation)
+        end
+
+        def single(space, operation)
+          perform(space, operation) do |table|
+            tuple = yield table
+
+            tuple && @mode.row(table, tuple, single: true)
+          end
+        end
+
+        def build_space(name, schema)
+          declaration = Declaration.new(name, schema)
+
+          Space.new(declaration.space_info, sequence: declaration.sequence && @mode.sequences?)
+        end
+      end
+    end
+  end
+end