xitdb 0.1.0

data/lib/xitdb/streams.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module XitDB
+  module Streams
+    # Restricts stream access to the lifetime of its owning block.
+    class Handle
+      def initialize(context)
+        @context = context
+        @active = true
+      end
+
+      def expire!
+        @active = false
+      end
+
+      private
+
+      def check!
+        raise ExpiredViewError, "byte stream block has ended" unless @active
+
+        @context.check!
+      end
+
+      def integer(value)
+        result = Integer.try_convert(value) || raise(TypeError, "expected an Integer")
+        limit = (1 << ((0.size * 8) - 1)) - 1
+        raise RangeError, "integer too big to convert into long" unless result.between?(-limit - 1, limit)
+
+        result
+      end
+    end
+
+    # Reads a captured byte value with bounded storage reads.
+    class Reader < Handle
+      def initialize(context, slot)
+        super(context)
+        unless %i[bytes short_bytes].include?(slot.tag) && !slot.full
+          raise InvalidValueError, "stream requires untagged bytes"
+        end
+
+        @source = Core::Bytes.open(context.database.core, slot, bound: context.read_bound)
+        @size = @source.size
+        @pos = 0
+      end
+
+      def read(length = nil, output = nil)
+        check!
+        @context.read do
+          check!
+          count = length.nil? ? [@size - @pos, 0].max : integer(length)
+          raise ArgumentError, "negative length" if count.negative?
+
+          buffer = if output.nil?
+                     +"".b
+                   else
+                     String.try_convert(output) || raise(TypeError, "expected a String buffer")
+                   end
+          buffer.replace("".b)
+          return nil if !length.nil? && count.positive? && @pos >= @size
+
+          remaining = count.clamp(0, [@size - @pos, 0].max)
+          while remaining.positive?
+            size = [remaining, Core::Bytes::CHUNK_SIZE].min
+            buffer << @source.read(@pos, size)
+            @pos += size
+            remaining -= size
+          end
+          buffer
+        end
+      end
+
+      def readpartial(length, output = nil)
+        check!
+        read(integer(length), output) || raise(EOFError, "end of byte stream")
+      end
+
+      def seek(offset, whence = IO::SEEK_SET)
+        check!
+        offset = integer(offset)
+        whence = case whence
+                 when :SET then IO::SEEK_SET
+                 when :CUR then IO::SEEK_CUR
+                 when :END then IO::SEEK_END
+                 else whence
+                 end
+        base = case integer(whence)
+               when IO::SEEK_SET then 0
+               when IO::SEEK_CUR then @pos
+               when IO::SEEK_END then @size
+               else raise Errno::EINVAL, "invalid seek origin"
+               end
+        position = base + offset
+        raise Errno::EINVAL, "negative seek position" if position.negative?
+
+        @pos = integer(position)
+        0
+      end
+
+      def rewind
+        seek(0)
+      end
+
+      def pos
+        check!
+        @pos
+      end
+
+      def size
+        check!
+        @size
+      end
+
+      def eof?
+        check!
+        @pos >= @size
+      end
+    end
+
+    # Spools bytes before the enclosing assignment is published.
+    class Writer < Handle
+      def initialize(context, spool)
+        super(context)
+        @spool = spool
+      end
+
+      def write(value)
+        check!
+        bytes = value.to_s
+        raise TypeError, "to_s must return a String" unless bytes.is_a?(String)
+
+        position = 0
+        while position < bytes.bytesize
+          check!
+          chunk = bytes.byteslice(position, Core::Bytes::CHUNK_SIZE) || raise(EOFError, "byte source ended")
+          position += @spool.write(chunk)
+        end
+        position
+      end
+
+      def pos
+        check!
+        @spool.pos
+      end
+    end
+  end
+end

data/lib/xitdb/value_walker.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative "input_guard"
+
+module XitDB
+  # Encodes and materializes nested values without recursive tree traversal.
+  module ValueWalker
+    # Frames retain only the current ancestors and their incremental iterators.
+    def self.encode(value, context:, path:)
+      # @type var active: ::Hash[Integer, bool]
+      active = {}
+      # @type var stack: ::Array[encoding_frame]
+      stack = []
+      # @type var current: [top, path]?
+      current = [value, path]
+      # @type var result: Core::Slot?
+      result = nil
+      while true # rubocop:disable Style/InfiniteLoop -- Codec StopIteration must propagate.
+        if current
+          result = begin_encoding(current[0], current[1], context, active, stack)
+          current = nil
+        end
+        if result
+          break if stack.empty?
+
+          assign_encoding_parent(stack, result)
+        end
+        frame = stack.last || raise(CorruptionError, "missing encoding frame")
+        entry = next_input(frame)
+        if entry
+          selector, child = entry
+          frame[4] = selector
+          current = [child, frame[1] + [selector]]
+        else
+          result = finish_encoding(frame, active, stack)
+          break if stack.empty?
+
+          result = nil
+        end
+      end
+      result || raise(CorruptionError, "encoding produced no value")
+    end
+
+    def self.materialize(view)
+      view.check!
+      context = view.context
+      # @type var active: ::Hash[[Symbol, Integer], bool]
+      active = {}
+      # @type var stack: ::Array[materialization_frame]
+      stack = []
+      # @type var current: [Core::Slot, path]?
+      current = [view.slot, view.path]
+      # @type var selected: adapter | Views::Slice::Selection | nil
+      selected = view.adapter
+      # @type var materialized: materialized?
+      materialized = nil
+      while true # rubocop:disable Style/InfiniteLoop -- Codec StopIteration must propagate.
+        if current
+          begin_materialization(current[0], current[1], selected, context, active, stack)
+          current = nil
+          selected = nil
+        end
+        frame = stack.last || raise(CorruptionError, "missing materialization frame")
+        entry = next_stored_entry(frame)
+        if entry
+          current = materialized_child(frame, entry)
+        else
+          materialized = finish_materialization(frame, active, stack)
+          break if stack.empty?
+        end
+      end
+      materialized || raise(CorruptionError, "materialization produced no value")
+    end
+
+    def self.begin_encoding(input, location, context, active, stack)
+      InputGuard.check!(input, path: location)
+      case input
+      when Views::Base then encode_view(input, context, location)
+      else
+        profile = context.profile
+        kind = profile.input_kind(input, path: location)
+        return encode_scalar(input, context, location) unless kind
+
+        identity = BasicObject.instance_method(:__id__).bind_call(input)
+        raise CyclicValueError.new("cyclic value at #{location.inspect}", path: location) if active[identity]
+
+        active[identity] = true
+        adapter = profile.empty_container(kind, context: context, path: location)
+        stack << [input, location, adapter, profile.input_entries(input, path: location), nil]
+        nil
+      end
+    end
+
+    def self.encode_view(input, context, location)
+      input.check!
+      unless input.context.reference_compatible?(context)
+        raise ForeignValueError.new("view belongs to another store or file generation", path: location)
+      end
+
+      context.writable_transaction.freeze
+      assigned = input.slot_for_assignment(context: context, path: location)
+      assigned.empty? ? encode({}, context: context, path: location) : assigned
+    end
+
+    def self.encode_scalar(input, context, location)
+      context.profile.encode_scalar(input, core: context.database.core)
+    rescue ValueError => e
+      raise e.class.new("#{e.message} at #{location.inspect}", path: location), cause: e
+    end
+
+    def self.assign_encoding_parent(stack, stored)
+      frame = stack.last || raise(CorruptionError, "missing encoding frame")
+      frame[2].assign(frame[4], stored)
+    end
+
+    def self.finish_encoding(frame, active, stack)
+      stored = frame[2].slot
+      active.delete(BasicObject.instance_method(:__id__).bind_call(frame[0]))
+      stack.pop
+      assign_encoding_parent(stack, stored) unless stack.empty?
+      stored
+    end
+
+    def self.next_input(frame)
+      frame[3].next
+    rescue StopIteration
+      nil
+    end
+
+    def self.begin_materialization(slot, path, selected, context, active, stack)
+      adapter = selected || context.profile.container(slot, context: context, path: path)
+      unless adapter
+        result = context.profile.decode(slot, context: context, path: path, immutable: false)
+        frame = stack.last || raise(CorruptionError, "missing materialization frame")
+        insert(frame, result)
+        return
+      end
+
+      # @type var identity: [Symbol, Integer]
+      identity = [slot.tag, slot.value]
+      raise CyclicValueError.new("cyclic stored value", path: path) if active[identity]
+
+      active[identity] = true
+      # @type var output: materialized
+      output = case adapter.kind
+               when :map, :sorted_map then {}
+               when :set, :sorted_set then Set.new
+               else []
+               end
+      stack << [identity, path, adapter.each_entry, output, nil]
+    end
+
+    def self.next_stored_entry(frame)
+      frame[2].next
+    rescue StopIteration
+      nil
+    end
+
+    def self.materialized_child(frame, entry)
+      selector, child = entry
+      frame[4] = selector.is_a?(String) ? selector.dup : selector
+      if frame[3].is_a?(Set)
+        frame[3].add(frame[4])
+        nil
+      else
+        [child, frame[1] + [selector]]
+      end
+    end
+
+    def self.finish_materialization(frame, active, stack)
+      active.delete(frame[0])
+      stack.pop
+      output = frame[3]
+      unless stack.empty?
+        parent = stack.last || raise(CorruptionError, "missing materialization parent")
+        insert(parent, output)
+      end
+      output
+    end
+
+    def self.insert(frame, value)
+      output = frame[3]
+      case output
+      when Hash then output[frame[4]] = value
+      when Array then output << value
+      end
+    end
+    private_class_method :insert, :begin_encoding, :encode_view, :encode_scalar, :assign_encoding_parent,
+                         :finish_encoding, :next_input, :begin_materialization, :next_stored_entry,
+                         :materialized_child, :finish_materialization
+  end
+end

data/lib/xitdb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module XitDB
+  VERSION = "0.1.0"
+end

data/lib/xitdb/views/array.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module XitDB
+  module Views
+    # Provides indexed reads and writes for persistent arrays.
+    class Array < Base
+      UNSET = MissingArgument.new.freeze
+      private_constant :UNSET
+
+      alias length size
+
+      def [](index, count = UNSET)
+        context.read { read_index(index, count) }
+      end
+
+      def read_index(index, count)
+        return read_slice(integer_argument(index), integer_argument(count)) unless count.equal?(UNSET)
+        return read_range(index) if index.is_a?(Range)
+
+        index = normalize_index(index)
+        return nil unless index >= 0 && index < size
+
+        stored = adapter.lookup(index) || raise(IndexError, "array index outside list")
+        context.profile.decode(stored, context: context, path: entry_path(index))
+      end
+      private :read_index
+
+      def read_range(index)
+        start = index.begin.nil? ? 0 : integer_argument(index.begin)
+        finish = index.end.nil? ? size : integer_argument(index.end)
+        start += size if start.negative?
+        return nil if start.negative? || start > size
+
+        finish += size if finish.negative?
+        finish += 1 unless index.exclude_end? || index.end.nil?
+        read_slice(start, [finish - start, 0].max)
+      end
+      private :read_range
+
+      def fetch(index, default = UNSET)
+        found, value = context.read do
+          position = normalize_index(index)
+          present = position >= 0 && position < size
+          [present, present ? self[position] : nil]
+        end
+        return value if found
+        return yield index if block_given?
+
+        case default
+        when MissingArgument then nil
+        else return default
+        end
+
+        raise IndexError, "array index outside list"
+      end
+
+      def first(count = UNSET)
+        context.read do
+          check!
+          return self[0] if count.equal?(UNSET)
+
+          requested = nonnegative_count(count)
+          each.take(requested)
+        end
+      end
+
+      def last(count = UNSET)
+        context.read do
+          return self[-1] if count.equal?(UNSET)
+
+          requested = [nonnegative_count(count), size].min
+          ((size - requested)...size).map { |index| self[index] }
+        end
+      end
+
+      def []=(index, value)
+        check!
+        context.writable!
+        index = normalize_index(index)
+        raise IndexError, "array index outside list" if index.negative?
+
+        validate_growth(index + 1)
+
+        previous_size = size
+        edit(positions: [previous_size, index].min..index) do |collection|
+          stored = context.profile.encode(value, context: context, path: path + [index])
+          collection.assign(collection.size, Core::Slot.null) while collection.size < index
+          collection.assign(index, stored)
+        end
+        context.replace_location(path + [index])
+        context.change_membership(path) if index >= previous_size
+        value
+      end
+
+      def <<(value)
+        push(value)
+      end
+
+      def push(*values)
+        insert(size, *values)
+      end
+
+      # Radix arrays shift the suffix for insertion and deletion. Linked arrays
+      # use their positional tree operations; neither operation decodes values.
+      def insert(index, *values)
+        check!
+        context.writable!
+        index = integer_argument(index)
+        return self if values.empty?
+
+        previous_size = size
+        index += previous_size + 1 if index.negative?
+        raise IndexError, "array index outside list" if index.negative?
+
+        validate_growth([previous_size, index].max + values.size)
+        edit(positions: [previous_size, index].min..) do |collection|
+          encoded = values.each_with_index.map do |value, offset|
+            context.profile.encode(value, context: context, path: path + [index + offset])
+          end
+          collection.assign(collection.size, Core::Slot.null) while collection.size < index
+          encoded.each_with_index { |stored, offset| collection.insert(index + offset, stored) }
+        end
+        invalidate_positions(index)
+        self
+      end
+
+      def delete_at(index)
+        check!
+        context.writable!
+        index = normalize_index(index)
+        previous_size = size
+        return nil unless index >= 0 && index < previous_size
+
+        context.check_stream_mutation!(path, positions: index..)
+
+        value = nil
+        edit(positions: index..) do |collection|
+          captured = captured_context
+          stored = collection.lookup(index) || raise(IndexError, "array index outside list")
+          value = context.profile.decode(stored, context: captured, path: [index])
+          collection.delete(index)
+        end
+        invalidate_positions(index)
+        value
+      end
+
+      def pop(count = UNSET)
+        check!
+        context.writable!
+        return delete_at(-1) if count.equal?(UNSET)
+
+        count = [nonnegative_count(count), size].min
+        return [] if count.zero?
+
+        previous_size = size
+        context.check_stream_mutation!(path, positions: (previous_size - count)..)
+        values = nil
+        edit(positions: (previous_size - count)..) do |collection|
+          captured = captured_context
+          values = ((previous_size - count)...previous_size).map do |index|
+            stored = collection.lookup(index) || raise(IndexError, "array index outside list")
+            context.profile.decode(stored, context: captured, path: [index])
+          end
+          collection.truncate(previous_size - count)
+        end
+        invalidate_positions(previous_size - count)
+        values
+      end
+
+      def concat(*others)
+        check!
+        context.writable!
+        added = false
+        edit(positions: size..) do |collection|
+          inputs = others.map do |other|
+            case other
+            when Array then nil
+            else other = ::Array.try_convert(other) || raise(TypeError, "concat requires an array")
+            end
+            stored = context.profile.encode(other, context: context, path: path)
+            context.collection(stored, path: path)
+          end
+          inputs.each do |input|
+            next if input.empty?
+
+            validate_growth(collection.size + input.size)
+            added = true
+            collection.concat(input)
+          end
+        end
+        context.change_membership(path) if added
+        self
+      end
+
+      def clear
+        check!
+        context.writable!
+        return self if empty?
+
+        edit { |collection| collection.truncate(0) }
+        context.invalidate_children(path)
+        context.change_membership(path)
+        self
+      end
+
+      protected
+
+      def validate_growth(count)
+        raise IndexError, "array size too big" if count > LONG_MAX / 0.size
+      end
+
+      def normalize_index(index)
+        index = integer_argument(index)
+        index.negative? ? index + size : index
+      end
+
+      def nonnegative_count(count)
+        count = integer_argument(count)
+        raise ArgumentError, "negative array size" if count.negative?
+
+        count
+      end
+
+      def read_slice(start, count)
+        start += size if start.negative?
+        return nil if start.negative? || start > size || count.negative?
+
+        count = [count, size - start].min
+        Slice.new(context: captured_context(readonly: true), path: [], kind: kind,
+                  offset: slice_offset + start, count: count)
+      end
+
+      def slice_offset
+        0
+      end
+
+      def invalidate_positions(start)
+        context.invalidate_positions(path, start)
+        context.change_membership(path)
+      end
+    end
+
+    # A captured, read-only range of an array.
+    class Slice < Array
+      def initialize(offset:, count:, **)
+        super(**)
+        @offset = offset
+        @count = count
+      end
+
+      def adapter
+        Selection.new(super, @offset, @count)
+      end
+
+      def slot_for_assignment(context:, path:)
+        context.collection(slot, path: path).slice(@offset, @count)
+      end
+
+      protected
+
+      def slice_offset
+        @offset
+      end
+
+      def entry_path(selector)
+        path + [@offset + selector]
+      end
+
+      # Limits the adapter's visible entries to the captured range.
+      class Selection
+        attr_reader :size
+
+        def initialize(source, offset, count)
+          @source = source
+          @offset = offset
+          @size = count
+        end
+
+        def kind
+          @source.kind
+        end
+
+        def lookup(index)
+          @source.lookup(@offset + index)
+        end
+
+        def each_entry
+          return enum_for(:each_entry) unless block_given?
+          return self if size.zero?
+
+          index = 0
+          @source.each_from_index(@offset) do |_selector, stored|
+            yield index, stored
+            index += 1
+            break if index == size
+          end
+          self
+        end
+      end
+      private_constant :Selection
+    end
+  end
+end