xitdb 0.1.0

data/lib/xitdb/views/base.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module XitDB
+  module Views
+    # Distinguishes omitted arguments from stored nil values.
+    class MissingArgument
+      def initialize
+        freeze
+      end
+    end
+
+    # Tracks a collection location and its owning snapshot or transaction.
+    class Base
+      include Enumerable
+
+      LONG_MAX = (1 << (([0].pack("l!").bytesize * 8) - 1)) - 1
+      private_constant :LONG_MAX
+
+      attr_reader :context, :path, :kind
+
+      def initialize(context:, path:, kind:)
+        @context = context
+        @path = path.map { |selector| selector.is_a?(String) ? selector.dup.freeze : selector }.freeze
+        @kind = kind
+        @location = context.observe(@path)
+      end
+
+      def check!
+        context.check!
+        return unless @location&.expired
+
+        raise ExpiredViewError, "view ancestor was replaced"
+      end
+
+      def slot
+        context.read do
+          check!
+          context.resolve(path)
+        end
+      end
+
+      def adapter
+        context.collection(slot, path: path)
+      end
+
+      def size
+        context.read { adapter.size }
+      end
+
+      def empty?
+        size.zero?
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        each_entries(-> { adapter.each_entry }) do |*entry|
+          if %i[map sorted_map].include?(kind)
+            yield entry[0], entry[1]
+          else
+            yield entry[0]
+          end
+        end
+      end
+
+      def slot_for_assignment(**)
+        slot
+      end
+
+      def to_ruby
+        context.read { ValueWalker.materialize(self) }
+      end
+
+      def ==(other)
+        context.read do
+          case other
+          when Base then other = other.to_ruby
+          end
+          to_ruby == other
+        end
+      end
+
+      def inspect
+        location = path.first(4).map { |selector| selector.is_a?(String) ? selector.byteslice(0, 32) : selector }
+        suffix = path.size > 4 ? "..." : ""
+        "#<#{self.class} profile=#{context.profile.class.name} path=#{location.inspect}#{suffix}>"
+      end
+
+      def open_bytes(key)
+        raise ArgumentError, "open_bytes requires a block" unless block_given?
+
+        # @type var reader: Streams::Reader?
+        reader = nil
+        registration = nil
+        reader = context.read do
+          selector = stream_selector(key)
+          if %i[array linked_array].include?(kind) && !integer_argument(selector).between?(0, size - 1)
+            raise KeyError, "byte value not found"
+          end
+
+          registration = context.register_stream(entry_path(selector), write: false)
+          stored = adapter.lookup(selector)
+          raise KeyError, "byte value not found" unless stored
+
+          Streams::Reader.new(context, stored)
+        end
+        yield reader
+      ensure
+        reader&.expire!
+        context.release_stream(registration) if registration
+      end
+
+      def write_bytes(key)
+        raise ArgumentError, "write_bytes requires a block" unless block_given?
+
+        check!
+        context.writable!
+        selector = stream_selector(key)
+        if %i[array linked_array].include?(kind)
+          selector = integer_argument(selector)
+          raise IndexError, "array index outside list" if selector.negative?
+
+          validate_growth(selector + 1)
+        end
+        context.check_stream_mutation!(path, **stream_mutation(selector))
+        Tempfile.create("xitdb-bytes", binmode: true) do |spool|
+          writer = Streams::Writer.new(context, spool)
+          registration = context.register_stream(entry_path(selector), write: true)
+          begin
+            result = yield writer
+          ensure
+            writer.expire!
+            context.release_stream(registration)
+          end
+          present = !adapter.lookup(selector).nil?
+          edit(**stream_mutation(selector)) do |collection|
+            spool.rewind
+            stored = Core::Bytes.copy(spool, size: spool.size, database: context.database.core,
+                                             transaction: context.writable_transaction)
+            if %i[array linked_array].include?(kind)
+              position = integer_argument(selector)
+              collection.assign(collection.size, Core::Slot.null) while collection.size < position
+            end
+            collection.assign(selector, stored)
+          end
+          context.replace_location(entry_path(selector))
+          context.change_membership(path) unless present
+          result
+        end
+      end
+
+      protected
+
+      def clear_entries?
+        collection = adapter
+        needed = if defined?(Ruby::Containers) && collection.is_a?(Ruby::Containers)
+                   collection.clear_needed?
+                 else
+                   !collection.empty?
+                 end
+        return false unless needed
+
+        edit do |current|
+          if defined?(Ruby::Containers) && current.is_a?(Ruby::Containers)
+            current.clear
+          else
+            current.each_entry { |selector, _| current.delete(selector) }
+          end
+        end
+        true
+      end
+
+      def edit(**options)
+        context.mutate(path, **options) do |cursor|
+          collection = context.collection(cursor.slot, path: path)
+          yield collection
+          cursor.replace(collection.slot)
+        end
+      end
+
+      def stream_selector(key)
+        check!
+        case kind
+        when :map, :sorted_map
+          collection = adapter
+          if defined?(Ruby::Containers) && collection.is_a?(Ruby::Containers)
+            collection.selector_identity(key)
+          else
+            context.profile.key_bytes(key)
+          end
+          case key
+          when String, Time then key.dup.freeze
+          else key
+          end
+        when :array, :linked_array then normalize_index(key)
+        else raise TypeError, "byte streams require a map or array view"
+        end
+      end
+
+      def stream_mutation(selector)
+        if %i[array linked_array].include?(kind)
+          position = integer_argument(selector)
+          { positions: [size, position].min..position }
+        else
+          { targets: [entry_path(selector)] }
+        end
+      end
+
+      def integer_argument(value)
+        result = ::Integer.try_convert(value) || raise(TypeError, "no implicit conversion into Integer")
+        raise RangeError, "integer too big to convert into long" unless result.between?(-LONG_MAX - 1, LONG_MAX)
+
+        result
+      end
+
+      def captured_context(readonly: false)
+        stored = slot
+        context.transaction&.freeze
+        Context.new(database: context.database, root: stored, bound: context.read_bound,
+                    transaction: context.transaction, readonly: readonly, reference_proof: context.reference_proof)
+      end
+
+      def entry_path(selector)
+        path + [selector]
+      end
+
+      def each_entries(entries, selectors_only: false)
+        # @type var iterator: Enumerator[entry, adapter]?
+        iterator = nil
+        generation = nil
+        exhausted = false
+        while true # rubocop:disable Style/InfiniteLoop -- Consumer StopIteration must propagate.
+          values = context.read do
+            check!
+            unless iterator
+              iterator = entries.call
+              generation = @location&.membership
+            end
+            if @location&.membership != generation
+              raise ConcurrentModificationError, "collection membership changed during iteration"
+            end
+
+            begin
+              active_iterator = iterator || raise(ConcurrentModificationError, "missing collection iterator")
+              selector, stored = active_iterator.next
+            rescue StopIteration
+              exhausted = true
+              next
+            end
+            decode_entry(selector, stored, selectors_only: selectors_only == true)
+          end
+          break if exhausted
+
+          yield(*values)
+        end
+        self
+      end
+
+      def decode_entry(selector, stored, selectors_only:)
+        return [selector] if selectors_only || %i[set sorted_set].include?(kind)
+
+        # Transaction entries resolve again so replacement values stay live.
+        if context.transaction
+          stored = adapter.lookup(selector) || raise(ExpiredViewError, "view location no longer exists")
+        end
+        value = context.profile.decode(stored, context: context, path: entry_path(selector))
+        %i[map sorted_map].include?(kind) ? [selector, value] : [value]
+      end
+    end
+  end
+end

data/lib/xitdb/views/linked_array.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module XitDB
+  module Views
+    # Provides array operations backed by the linked positional tree.
+    class LinkedArray < Array
+      def split(index)
+        context.read do
+          index = integer_argument(index)
+          index += size if index.negative?
+          raise IndexError, "array split outside list" unless index.between?(0, size)
+
+          [self[0, index], self[index, size - index]]
+        end
+      end
+    end
+  end
+end

data/lib/xitdb/views/map.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module XitDB
+  module Views
+    # Provides key-based reads and writes for persistent maps.
+    class Map < Base
+      UNSET = MissingArgument.new.freeze
+      private_constant :UNSET
+
+      def [](key)
+        context.read do
+          stored = adapter.lookup(key)
+          context.profile.decode(stored, context: context, path: path + [key]) if stored
+        end
+      end
+
+      def fetch(key, default = UNSET)
+        found, value = context.read do
+          present = key?(key)
+          [present, present ? self[key] : nil]
+        end
+        return value if found
+        return yield key if block_given?
+
+        case default
+        when MissingArgument then nil
+        else return default
+        end
+
+        raise KeyError, "key not found: #{key.inspect}"
+      end
+
+      def dig(*keys)
+        context.read { dig_value(keys) }
+      end
+
+      def dig_value(keys)
+        raise ArgumentError, "at least one key is required" if keys.empty?
+
+        # @type var value: top
+        value = self
+        keys.each_with_index do |key, index|
+          case value
+          when nil then return nil
+          when Map then value = value[key]
+          when Array then value = value[integer_argument(key)]
+          when Object
+            raise TypeError, "#{value.class} does not have #dig method" unless value.respond_to?(:dig)
+
+            return Object.instance_method(:public_method).bind_call(value, :dig).call(*keys.drop(index))
+          else
+            raise TypeError, "value does not have #dig method"
+          end
+        end
+        value
+      end
+      private :dig_value
+
+      def key?(key)
+        context.read { !adapter.lookup(key).nil? }
+      end
+
+      def each_key(&block)
+        return enum_for(:each_key) unless block
+
+        each_entries(-> { adapter.each_entry }, selectors_only: true, &block)
+        self
+      end
+
+      def each_value
+        return enum_for(:each_value) unless block_given?
+
+        each { |_key, value| yield value }
+        self
+      end
+
+      def keys
+        context.read { each_key.to_a }
+      end
+
+      def values
+        context.read { each_value.to_a }
+      end
+
+      def []=(key, value)
+        check!
+        context.writable!
+        present = key?(key)
+        context.mutate(path, targets: [path + [key]]) do |cursor|
+          encoded = context.profile.encode(value, context: context, path: path + [key])
+          collection = context.collection(cursor.slot, path: path)
+          collection.assign(key, encoded)
+          cursor.replace(collection.slot)
+        end
+        context.replace_location(path + [key])
+        context.change_membership(path) unless present
+        value
+      end
+
+      def delete(key)
+        check!
+        context.writable!
+        return block_given? ? yield(key) : nil unless key?(key)
+
+        context.check_stream_mutation!(path, targets: [path + [key]])
+
+        value = nil
+        context.mutate(path, targets: [path + [key]]) do |cursor|
+          # Capture before deletion, with loaders inside the mutation checkpoint.
+          stored = adapter.lookup(key) || raise(KeyError, "key no longer exists")
+          context.writable_transaction.freeze
+          captured = Context.new(database: context.database, root: stored, bound: context.read_bound,
+                                 transaction: context.transaction)
+          value = context.profile.decode(stored, context: captured, path: [])
+          collection = context.collection(cursor.slot, path: path)
+          collection.delete(key)
+          cursor.replace(collection.slot)
+        end
+        context.replace_location(path + [key])
+        context.change_membership(path)
+        value
+      end
+
+      def clear
+        check!
+        context.writable!
+        return self unless clear_entries?
+
+        context.invalidate_children(path)
+        context.change_membership(path)
+        self
+      end
+
+      def merge!(hash)
+        check!
+        context.writable!
+        raise TypeError, "merge! requires a Hash" unless Object.instance_method(:instance_of?).bind_call(hash, Hash)
+
+        # @type var replaced: ::Array[selector]
+        replaced = []
+        added = false
+        targets = Hash.instance_method(:keys).bind_call(hash).map { |key| path + [key] }
+        context.mutate(path, targets: targets) do |cursor|
+          encoded = context.profile.encode(hash, context: context, path: path)
+          input = context.collection(encoded, path: path)
+          next if input.empty?
+
+          collection = context.collection(cursor.slot, path: path)
+          input.each_entry do |selector, stored|
+            added = true unless collection.lookup(selector)
+            collection.assign(selector, stored)
+            replaced << selector
+          end
+          cursor.replace(collection.slot)
+        end
+        replaced.each { |selector| context.replace_location(path + [selector]) }
+        context.change_membership(path) if added
+        self
+      end
+    end
+  end
+end

data/lib/xitdb/views/set.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module XitDB
+  module Views
+    # Provides membership reads and writes for persistent sets.
+    class Set < Base
+      def include?(value)
+        context.read { !adapter.lookup(value).nil? }
+      end
+
+      def add(value)
+        check!
+        context.writable!
+        return self if include?(value)
+
+        edit { |collection| collection.assign(value, Core::Slot.new) }
+        context.change_membership(path)
+        self
+      end
+
+      def delete(value)
+        check!
+        context.writable!
+        return self unless include?(value)
+
+        edit { |collection| collection.delete(value) }
+        context.change_membership(path)
+        self
+      end
+
+      def clear
+        check!
+        context.writable!
+        return self unless clear_entries?
+
+        context.change_membership(path)
+        self
+      end
+    end
+  end
+end

data/lib/xitdb/views/sorted.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module XitDB
+  module Views
+    # Adds ordered iteration and pagination to sorted collection views.
+    module Sorted
+      def rank(key)
+        context.read { adapter.rank(key) }
+      end
+
+      def from(key)
+        return enum_for(:from, key) unless block_given?
+
+        each_entries(-> { adapter.each_from(key) }) { |*entry| yield(*entry) }
+        self
+      end
+
+      def from_index(index)
+        return enum_for(:from_index, index) unless block_given?
+
+        each_entries(-> { adapter.each_from_index(integer_argument(index)) }) { |*entry| yield(*entry) }
+        self
+      end
+
+      def page(offset:, limit:)
+        check!
+        offset = integer_argument(offset)
+        limit = integer_argument(limit)
+        raise ArgumentError, "negative page limit" if limit.negative?
+        return enum_for(:page, offset: offset, limit: limit) unless block_given?
+        return self if limit.zero?
+
+        remaining = limit
+        from_index(offset) do |*entry|
+          yield(*entry)
+          remaining -= 1
+          break if remaining.zero?
+        end
+        self
+      end
+    end
+
+    # A map whose keys have a stable storage order.
+    class SortedMap < Map
+      include Sorted
+
+      def merge!(hash)
+        return super unless defined?(Profiles::Ruby) && context.profile.is_a?(Profiles::Ruby)
+
+        check!
+        context.writable!
+        raise TypeError, "merge! requires a Hash" unless Object.instance_method(:instance_of?).bind_call(hash, Hash)
+
+        # @type var replaced: ::Array[selector]
+        replaced = []
+        added = false
+        targets = Hash.instance_method(:keys).bind_call(hash).map { |key| path + [key] }
+        edit(targets: targets) do |collection|
+          context.profile.input_kind(hash, path: path)
+          hash.each_pair do |key, value|
+            added = true unless collection.lookup(key)
+            stored = context.profile.encode(value, context: context, path: path + [key])
+            collection.assign(key, stored)
+            replaced << key
+          end
+        end
+        replaced.each { |key| context.replace_location(path + [key]) }
+        context.change_membership(path) if added
+        self
+      end
+    end
+
+    class SortedSet < Set
+      include Sorted
+    end
+  end
+end

data/lib/xitdb.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "xitdb/version"
+require_relative "xitdb/errors"
+require_relative "xitdb/core"
+require_relative "xitdb/declarations"
+require_relative "xitdb/profiles/portable"
+require_relative "xitdb/context"
+require_relative "xitdb/value_walker"
+require_relative "xitdb/streams"
+require_relative "xitdb/views/base"
+require_relative "xitdb/views/map"
+require_relative "xitdb/views/array"
+require_relative "xitdb/views/linked_array"
+require_relative "xitdb/views/set"
+require_relative "xitdb/views/sorted"
+require_relative "xitdb/revision"
+require_relative "xitdb/snapshot"
+require_relative "xitdb/history"
+require_relative "xitdb/database"

data/sig/base.rbs

@@ -0,0 +1,76 @@
+module XitDB
+  VERSION: String
+
+  type diagnostic_value = nil | bool | Integer | Float | Symbol | String | Array[diagnostic_value] | Hash[diagnostic_value, diagnostic_value]
+
+  class Error < StandardError
+  end
+
+  class FormatVersionError < Error
+  end
+
+  class CorruptionError < Error
+  end
+
+  class ProfileMismatchError < Error
+  end
+
+  class TransactionStateError < Error
+  end
+
+  class ClosedError < Error
+  end
+
+  class ExpiredViewError < Error
+  end
+
+  class ForeignRevisionError < Error
+  end
+
+  class ReadOnlyError < Error
+  end
+
+  class ConcurrentModificationError < Error
+  end
+
+  class BusyError < Error
+  end
+
+  class CodecError < Error
+  end
+
+  class CodecConfigurationError < CodecError
+  end
+
+  class ValueError < Error
+    @path: diagnostic_value
+    attr_reader path: diagnostic_value
+    def initialize: (?String? message, ?path: top) -> void
+    private
+    def copy_path: (top value) -> diagnostic_value
+  end
+
+  class InvalidValueError < ValueError
+  end
+
+  class UnsupportedValueError < ValueError
+  end
+
+  class UnsupportedEncodingError < ValueError
+  end
+
+  class CyclicValueError < ValueError
+  end
+
+  class ForeignValueError < ValueError
+  end
+
+  class KeyCollisionError < ValueError
+  end
+
+  class CommitError < Error
+    @outcome: :not_committed | :committed | :unknown
+    attr_reader outcome: :not_committed | :committed | :unknown
+    def initialize: (?String? message, outcome: :not_committed | :committed | :unknown) -> void
+  end
+end