xitdb 0.1.0

data/lib/xitdb/database.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require_relative "conversion"
+
+# Persistent collections with immutable snapshots and explicit transactions.
+module XitDB
+  # Owns the profile, history, and transactions of a public database.
+  class Database
+    attr_reader :core, :profile
+
+    def self.hasher(value)
+      if value.is_a?(Core::Hasher)
+        raise ProfileMismatchError, "rb01 is reserved for XitDB::Ruby" if value.id == "rb01"
+
+        return value
+      end
+      case value
+      when :sha1 then Core::Hasher.sha1
+      when :sha256 then Core::Hasher.sha256
+      when :sha384 then Core::Hasher.sha384
+      when :sha512 then Core::Hasher.sha512
+      else
+        raise ArgumentError, "hash must be a builtin algorithm or Core::Hasher"
+      end
+    end
+
+    def self.open(path, readonly: false, hash: nil, lock_timeout: 5.0)
+      selected = hasher(hash) unless hash.nil?
+      # @type var options: { ?hash_id: String, ?hash_size: Integer }
+      options = selected ? { hash_id: selected.id, hash_size: selected.size } : {}
+      store, created = open_store(path, readonly: readonly)
+      begin
+        core = Core::Database.new(store: store, initialize_empty: created, lock_timeout: lock_timeout, **options)
+        raise ProfileMismatchError, "Ruby profile file requires XitDB::Ruby.open" if core.header.hash_id == "rb01"
+
+        selected ||= header_hasher(core.header)
+        database = new(core: core, profile: Profiles::Portable.new(hasher: selected), readonly: readonly)
+      rescue Exception # rubocop:disable Lint/RescueException -- Close owned storage on Interrupt and SystemExit.
+        store.send(:close_unreturned)
+        raise
+      end
+      return database unless block_given?
+
+      begin
+        yield database
+      ensure
+        database.close
+      end
+    end
+
+    def self.header_hasher(header)
+      case [header.hash_id, header.hash_size]
+      when ["sha1", 20] then Core::Hasher.sha1
+      when ["sha2", 32] then Core::Hasher.sha256
+      when ["sha2", 48] then Core::Hasher.sha384
+      when ["sha2", 64] then Core::Hasher.sha512
+      else raise ProfileMismatchError, "unknown hash identifier or size; supply an explicit hash configuration"
+      end
+    end
+    private_class_method :header_hasher
+
+    def self.open_store(path, readonly:)
+      return [Core::FileStore.open(path, readonly: true), false] if readonly
+
+      begin
+        [Core::FileStore.open(path, exclusive: true), true]
+      rescue Errno::EEXIST
+        [Core::FileStore.open(path, create: false), false]
+      end
+    end
+    private_class_method :open_store
+
+    def self.memory(hash: :sha1)
+      selected = hasher(hash)
+      database = new(core: Core::Database.memory(hash_id: selected.id, hash_size: selected.size),
+                     profile: Profiles::Portable.new(hasher: selected))
+      return database unless block_given?
+
+      begin
+        yield database
+      ensure
+        database.close
+      end
+    end
+
+    def initialize(core:, profile:, readonly: false)
+      @core = core
+      @profile = profile
+      @readonly = readonly
+      snapshot
+    end
+
+    def transaction(&block)
+      raise ArgumentError, "transaction requires a block" unless block_given?
+      raise ReadOnlyError, "database is read-only" if @readonly
+
+      core.with_operation { perform_transaction(&block) }
+    end
+
+    def perform_transaction
+      committed = core.transaction do |history_cursor|
+        array = history_array(history_cursor)
+        empty = array.size.zero? # rubocop:disable Style/ZeroLengthPredicate -- Core arrays expose size, not empty?.
+        slot = empty ? Core::Slot.new : (array.get(-1) || raise(CorruptionError, "missing history root"))
+        context = Context.new(database: self, root: slot, bound: history_cursor.bound,
+                              transaction: history_cursor.transaction)
+        validate_root(slot, context) unless empty
+        root = context.view(slot, path: [], kind: :map)
+        yield root
+        if context.changed?
+          array.append(context.root)
+        else
+          context.writable_transaction.cancel_publication
+        end
+      end
+      snapshot_from_cursor(committed)
+    end
+    private :perform_transaction
+
+    def snapshot(revision: nil)
+      core.with_operation do
+        if revision
+          raise TypeError, "revision must be an XitDB::Revision" unless revision.is_a?(Revision)
+
+          return revision.resolve(self)
+        end
+        snapshot_from_cursor(core.root_cursor)
+      end
+    end
+
+    def history
+      core.check_open!
+      History.new(self)
+    end
+
+    def revert(value)
+      core.with_operation { perform_revert(value) }
+    end
+
+    def perform_revert(value)
+      target = if value.is_a?(Snapshot)
+                 unless value.context.database.core.header.file_id == core.header.file_id
+                   raise ForeignRevisionError, "snapshot belongs to another database"
+                 end
+
+                 value.revision ? snapshot(revision: value.revision) : value
+               elsif value.is_a?(Revision)
+                 snapshot(revision: value)
+               else
+                 raise TypeError, "revert requires a Snapshot or Revision"
+               end
+      raise ReadOnlyError, "database is read-only" if @readonly
+
+      committed = core.transaction do |cursor|
+        # Validate again under the writer lock in case the file was restored.
+        selected = target.revision ? snapshot(revision: target.revision) : target
+        slot = selected.slot
+        if slot.empty?
+          context = Context.new(database: self, root: slot, bound: cursor.bound, transaction: cursor.transaction)
+          slot = profile.encode({}, context: context, path: [])
+        end
+        history_array(cursor).append(slot)
+      end
+      snapshot_from_cursor(committed)
+    end
+    private :perform_revert
+
+    def close
+      core.close
+    end
+
+    def compact(to:)
+      compacted = core.compact(to: to)
+      begin
+        selected_profile = profile
+        copied_profile = if defined?(Profiles::Ruby) && selected_profile.is_a?(Profiles::Ruby)
+                           Profiles::Ruby.new(codecs: selected_profile.codecs)
+                         else
+                           Profiles::Portable.new(hasher: profile.hasher)
+                         end
+        self.class.new(core: compacted, profile: copied_profile)
+      rescue Exception # rubocop:disable Lint/RescueException -- Close owned storage on Interrupt and SystemExit.
+        compacted.send(:close_unreturned)
+        raise
+      end
+    end
+
+    def closed?
+      core.closed?
+    end
+
+    def convert(to:, profile:, history: :all, transform: nil)
+      raise ArgumentError, "history must be :all or :latest" unless %i[all latest].include?(history)
+      raise TypeError, "transform must respond to call" unless transform.nil? || transform.respond_to?(:call)
+
+      require_relative "ruby"
+      target_profile = conversion_profile(profile)
+      core.with_operation do
+        captured = core.root_cursor
+        histories = history_array(captured)
+        store = Core::FileStore.open(to)
+        completed = published = false
+        # @type var target_core: Core::Database?
+        target_core = nil
+        begin
+          raise ArgumentError, "conversion target is the source file" if store.storage_identity == core.storage_identity
+
+          created_core = Core::Database.new(store: store, hash_id: target_profile.hasher.id,
+                                            hash_size: target_profile.hasher.size, require_empty: true)
+          target_core = created_core
+          target = Database.new(core: created_core, profile: target_profile)
+          copy_history(target, store, captured, histories, history, transform)
+          published = true
+          completed = true
+          target
+        ensure
+          unless completed
+            target_core&.send(:restore_empty_target) unless published
+            store.send(:close_unreturned)
+          end
+        end
+      end
+    end
+
+    # Conventional history is shared by profiles; logical roots use the profile seam.
+    def history_array(cursor)
+      unless cursor.slot.empty? || cursor.slot.tag == :array_list
+        raise ProfileMismatchError, "public databases require a top-level history array"
+      end
+
+      Core::ArrayList.new(cursor)
+    end
+
+    def snapshot_from_history(cursor, index, revision: nil)
+      core.with_operation do
+        slot = history_array(cursor).get(index)
+        raise IndexError, "history index outside history" unless slot
+        raise ProfileMismatchError, "history entry must contain a root map" if slot.empty?
+
+        context = Context.new(database: self, root: slot, bound: cursor.bound)
+        validate_root(slot, context)
+        revision ||= revision_for(cursor, index)
+        Snapshot.new(context: context, revision: revision)
+      end
+    end
+
+    private
+
+    def conversion_profile(selected)
+      source_profile = profile
+      case selected
+      when :portable
+        Profiles::Portable.new(hasher: source_profile.instance_of?(Profiles::Portable) ? source_profile.hasher : Core::Hasher.sha1)
+      when :ruby
+        Profiles::Ruby.new(codecs: source_profile.is_a?(Profiles::Ruby) ? source_profile.codecs : [])
+      else
+        if selected.instance_of?(Profiles::Portable)
+          Profiles::Portable.new(hasher: selected.hasher)
+        elsif selected.instance_of?(Profiles::Ruby)
+          Profiles::Ruby.new(codecs: selected.codecs)
+        else
+          raise ArgumentError, "profile must be :portable, :ruby, or a supported profile instance"
+        end
+      end
+    end
+
+    def copy_history(target, store, captured, histories, history, transform)
+      target_core = target.core
+      target_core.transaction do |cursor|
+        current_header = Core::Header.parse(store.read_at(0, Core::Header::SIZE))
+        unchanged = current_header.file_id == target_core.header.file_id && cursor.bound == Core::Database::MINIMUM_SIZE
+        raise ArgumentError, "conversion target changed before copying" unless unchanged && cursor.slot.empty?
+
+        if histories.size.zero? # rubocop:disable Style/ZeroLengthPredicate -- Core arrays expose size, not empty?.
+          transaction = cursor.transaction || raise(ReadOnlyError, "conversion requires a transaction")
+          transaction.cancel_publication
+          next
+        end
+        output = Core::ArrayList.new(cursor)
+        first = history == :latest ? histories.size - 1 : 0
+        (first...histories.size).each do |index|
+          source = snapshot_from_history(captured, index).context
+          destination = Context.new(database: target, root: Core::Slot.new,
+                                    bound: cursor.bound, transaction: cursor.transaction)
+          transaction = destination.writable_transaction
+          transaction.with_logical_mutation do
+            output.append(Conversion.new(source, destination, transform: transform).copy(source.root))
+            transaction.freeze
+          end
+        end
+      end
+    end
+
+    def validate_root(slot, context)
+      adapter = profile.container(slot, context: context, path: []) unless slot.empty?
+      return if adapter && %i[map sorted_map].include?(adapter.kind)
+
+      raise ProfileMismatchError, "history entry must contain a root map"
+    end
+
+    def snapshot_from_cursor(cursor)
+      count = history_array(cursor).size
+      return snapshot_from_history(cursor, count - 1) unless count.zero?
+
+      Snapshot.new(context: Context.new(database: self, root: Core::Slot.new, bound: cursor.bound), revision: nil)
+    end
+
+    def revision_for(cursor, index)
+      position = cursor.bound - Core::Database::TRAILER_SIZE
+      checksum = core.read_at(position + 17, 8, bound: cursor.bound).unpack1("Q>")
+      raise CorruptionError, "invalid history checksum" unless checksum.is_a?(Integer)
+
+      Revision.new(file_id: core.header.file_id, trailer_position: position, checksum: checksum, index: index)
+    end
+  end
+
+  def self.open(path, readonly: false, hash: nil, lock_timeout: 5.0, &block)
+    if block
+      Database.open(path, readonly: readonly, hash: hash, lock_timeout: lock_timeout, &block)
+    else
+      Database.open(path, readonly: readonly, hash: hash, lock_timeout: lock_timeout)
+    end
+  end
+
+  def self.memory(hash: :sha1, &block)
+    if block
+      Database.memory(hash: hash, &block)
+    else
+      Database.memory(hash: hash)
+    end
+  end
+end

data/lib/xitdb/declarations.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Persistent collections with immutable snapshots and explicit transactions.
+module XitDB
+  # Explicit unsigned storage for an integer.
+  class UInt
+    attr_reader :value
+
+    def initialize(value)
+      @value = Core::Format.integer(value, 0..Core::Format::UINT64_MAX)
+      freeze
+    end
+  end
+
+  # Describes the storage layout of a new empty collection.
+  class CollectionDeclaration
+    KINDS = %i[hash_map counted_hash_map hash_set counted_hash_set array_list linked_array_list sorted_map
+               sorted_set].freeze
+
+    attr_reader :kind, :key_kind
+
+    def initialize(kind, key: nil)
+      raise ArgumentError, "unknown collection kind" unless KINDS.include?(kind)
+      if !nil.equal?(key) && (!%i[sorted_map sorted_set].include?(kind) || !%i[string integer float time].include?(key))
+        raise ArgumentError, "sorted key kind must be :string, :integer, :float, or :time"
+      end
+
+      @kind = kind
+      @key_kind = key
+      freeze
+    end
+
+    def counted?
+      %i[counted_hash_map counted_hash_set].include?(kind)
+    end
+  end
+
+  def self.uint(value)
+    UInt.new(value)
+  end
+
+  def self.bytes(bytes, format_tag: nil)
+    Core::ByteValue.new(bytes, format_tag: format_tag)
+  end
+
+  def self.map(counted: false)
+    raise ArgumentError, "counted must be true or false" unless counted.equal?(true) || counted.equal?(false)
+
+    CollectionDeclaration.new(counted ? :counted_hash_map : :hash_map)
+  end
+
+  def self.set(counted: false)
+    raise ArgumentError, "counted must be true or false" unless counted.equal?(true) || counted.equal?(false)
+
+    CollectionDeclaration.new(counted ? :counted_hash_set : :hash_set)
+  end
+
+  def self.array
+    CollectionDeclaration.new(:array_list)
+  end
+
+  def self.linked_array
+    CollectionDeclaration.new(:linked_array_list)
+  end
+
+  def self.sorted_map(key: nil)
+    CollectionDeclaration.new(:sorted_map, key: key)
+  end
+
+  def self.sorted_set(key: nil)
+    CollectionDeclaration.new(:sorted_set, key: key)
+  end
+end

data/lib/xitdb/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module XitDB
+  # Base class for database errors.
+  class Error < StandardError; end
+  # An unsupported on-disk format version.
+  class FormatVersionError < Error; end
+  # Invalid structural data in the database file.
+  class CorruptionError < Error; end
+  # A database opened with an incompatible value profile.
+  class ProfileMismatchError < Error; end
+  # An operation outside the allowed transaction state.
+  class TransactionStateError < Error; end
+  # An operation on a closed database.
+  class ClosedError < Error; end
+  # A view whose transaction or location has expired.
+  class ExpiredViewError < Error; end
+  # A revision from another database.
+  class ForeignRevisionError < Error; end
+  # A mutation through a read-only handle.
+  class ReadOnlyError < Error; end
+  # A mutation that conflicts with an active iterator or stream.
+  class ConcurrentModificationError < Error; end
+  # A database lock that could not be acquired.
+  class BusyError < Error; end
+  # A custom value codec failed.
+  class CodecError < Error; end
+  # Invalid or conflicting codec registrations.
+  class CodecConfigurationError < CodecError; end
+
+  # An invalid value with an owned, immutable diagnostic path.
+  class ValueError < Error
+    attr_reader :path
+
+    def initialize(message = nil, path: [])
+      @path = copy_path(path)
+      super(message)
+    end
+
+    private
+
+    def copy_path(value)
+      case value
+      when Array then Array.instance_method(:map).bind_call(value) { |part| copy_path(part) }.freeze
+      when Hash then Hash.instance_method(:to_h).bind_call(value) do |key, part|
+        [copy_path(key), copy_path(part)]
+      end.freeze
+      when String then String.new(value).freeze
+      when NilClass, TrueClass, FalseClass, Integer, Float, Symbol then value
+      else
+        klass = Object.instance_method(:class).bind_call(value)
+        name = Module.instance_method(:name).bind_call(klass) || "anonymous class"
+        "#<unsupported #{name}>".freeze
+      end
+    end
+  end
+
+  # A malformed encoded value.
+  class InvalidValueError < ValueError; end
+  # A value that the selected profile cannot store.
+  class UnsupportedValueError < ValueError; end
+  # An unsupported scalar encoding or version.
+  class UnsupportedEncodingError < ValueError; end
+  # A recursive input that cannot be stored as a value.
+  class CyclicValueError < ValueError; end
+  # A view or value owned by another database.
+  class ForeignValueError < ValueError; end
+  # Distinct keys with identical encoded representations.
+  class KeyCollisionError < ValueError; end
+
+  # A failed commit with its observed durability outcome.
+  class CommitError < Error
+    attr_reader :outcome
+
+    def initialize(message = nil, outcome:)
+      unless %i[not_committed committed unknown].include?(outcome)
+        raise ArgumentError, "invalid commit outcome: #{outcome.inspect}"
+      end
+
+      @outcome = outcome
+      super(message)
+    end
+  end
+end

data/lib/xitdb/history.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module XitDB
+  # Enumerates the committed snapshots of a database.
+  class History
+    include Enumerable
+
+    def initialize(database)
+      @database = database
+    end
+
+    def [](index)
+      @database.core.with_operation do
+        cursor = @database.core.root_cursor
+        count = @database.history_array(cursor).size
+        raise TypeError, "history index must be an Integer" unless index.is_a?(Integer)
+
+        index += count if index.negative?
+        return nil unless index >= 0 && index < count
+
+        @database.snapshot_from_history(cursor, index)
+      end
+    end
+
+    def fetch(index)
+      self[index] || raise(IndexError, "history index outside history")
+    end
+
+    def size
+      @database.core.with_operation { @database.history_array(@database.core.root_cursor).size }
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      # @type var cursor: Core::Cursor?
+      cursor = nil
+      count = 0
+      index = 0
+      while cursor.nil? || index < count
+        snapshot = @database.core.with_operation do
+          captured = cursor
+          unless captured
+            captured = @database.core.root_cursor
+            cursor = captured
+            count = @database.history_array(captured).size
+          end
+          @database.snapshot_from_history(captured, index) if index < count
+        end
+        break unless snapshot
+
+        yield snapshot
+        index += 1
+      end
+      self
+    end
+  end
+end

data/lib/xitdb/input_guard.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module XitDB
+  # Rejects objects with altered method behavior before encoding them.
+  module InputGuard
+    def self.check!(value, path: [])
+      unless Object.instance_method(:is_a?).bind_call(value, Object)
+        raise UnsupportedValueError.new("unsupported Ruby object", path: path)
+      end
+
+      unless Object.instance_method(:singleton_methods).bind_call(value).empty?
+        raise UnsupportedValueError.new("singleton behavior is unsupported", path: path)
+      end
+
+      klass = Object.instance_method(:class).bind_call(value)
+      # @type var methods: ::Array[native_visibility_pair]
+      methods = [%i[public_instance_methods public_methods], %i[protected_instance_methods protected_methods],
+                 %i[private_instance_methods private_methods]]
+      methods.each do |instance_methods, object_methods|
+        expected = Module.instance_method(instance_methods).bind_call(klass)
+        actual = Object.instance_method(object_methods).bind_call(value)
+        unless (expected - actual).empty? && (actual - expected).empty?
+          raise UnsupportedValueError.new("singleton behavior or method removal is unsupported", path: path)
+        end
+      end
+      # Private singleton overrides are absent from #singleton_methods. Inspect
+      # their owners without creating a singleton class on chilled Strings.
+      Object.instance_method(:private_methods).bind_call(value, false).each do |name|
+        owner = Object.instance_method(:method).bind_call(value, name).owner
+        expected = Module.instance_method(:instance_method).bind_call(klass, name).owner
+        unless BasicObject.instance_method(:equal?).bind_call(owner, expected)
+          raise UnsupportedValueError.new("singleton behavior is unsupported", path: path)
+        end
+      end
+    end
+  end
+end