ruby-object-framework 1.0.0

data/lib/object_framework/persistence/query.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module Persistence
+    Criterion = Data.define(:field, :operator, :value)
+
+    class Query
+      OPERATORS = %i[eq ne gt gte lt lte in].freeze
+      attr_reader :table, :criteria, :ordering, :row_limit, :row_offset
+
+      def self.identifier(name)
+        raise ConfigurationError, "Invalid storage identifier: #{name.inspect}" unless /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(name.to_s)
+        name.to_sym
+      end
+
+      def initialize(table: nil, criteria: [], ordering: [], row_limit: nil, row_offset: 0)
+        @table = self.class.identifier(table) if table
+        @criteria, @ordering = criteria.freeze, ordering.freeze
+        @row_limit, @row_offset = row_limit, row_offset
+        freeze
+      end
+
+      def for_table(table)
+        copy(table:)
+      end
+
+      def where(**attributes)
+        attributes.reduce(self) { |query, (field, value)| query.compare(field, :eq, value) }
+      end
+
+      def compare(field, operator, value)
+        raise ConfigurationError, "Unsupported query operator" unless OPERATORS.include?(operator)
+        raise ConfigurationError, "IN requires an array" if operator == :in && !value.is_a?(Array)
+        criterion = Criterion.new(field: self.class.identifier(field), operator:, value: Values.detach(value))
+        copy(criteria: criteria + [criterion])
+      end
+
+      def order(field, direction = :asc)
+        raise ConfigurationError, "Invalid ordering direction" unless %i[asc desc].include?(direction)
+        copy(ordering: ordering + [[self.class.identifier(field), direction].freeze])
+      end
+
+      def limit(count)
+        copy(row_limit: nonnegative(count))
+      end
+
+      def offset(count)
+        copy(row_offset: nonnegative(count))
+      end
+
+      def apply(rows)
+        selected = rows.select { |row| criteria.all? { |criterion| matches?(row, criterion) } }
+        ordering = @ordering.any? { |field, _| field == :id } ? @ordering : @ordering + [[:id, :asc]]
+        selected.sort! do |left, right|
+          ordering.each do |field, direction|
+            a, b = left[field], right[field]
+            comparison = if a.nil? then b.nil? ? 0 : -1 elsif b.nil? then 1 else a <=> b end
+            raise InvalidInput, "Incomparable query values" unless comparison
+            break(direction == :desc ? -comparison : comparison) unless comparison.zero?
+          end.then { |result| result.is_a?(Integer) ? result : 0 }
+        end
+        selected = selected.drop(row_offset)
+        row_limit ? selected.take(row_limit) : selected
+      end
+
+      private
+
+      def copy(**changes)
+        self.class.new(**{ table:, criteria:, ordering:, row_limit:, row_offset: }.merge(changes))
+      end
+
+      def nonnegative(count)
+        raise ConfigurationError, "Expected a nonnegative integer" unless count.is_a?(Integer) && count >= 0
+        count
+      end
+
+      def matches?(row, criterion)
+        actual, expected = row[criterion.field], criterion.value
+        case criterion.operator
+        when :eq then actual == expected
+        when :ne then !actual.nil? && actual != expected
+        when :in then criterion.value.include?(actual)
+        else
+          return false if actual.nil? || expected.nil?
+          comparison = actual <=> expected
+          return false unless comparison
+          case criterion.operator
+          when :gt then comparison > 0
+          when :gte then comparison >= 0
+          when :lt then comparison < 0
+          when :lte then comparison <= 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/object_framework/persistence/session.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module Persistence
+    class IdentityMap
+      def initialize
+        @entities = {}
+      end
+
+      def find(type, id); @entities[[type, id]]; end
+
+      def add(type, id, entity)
+        existing = find(type, id)
+        raise Duplicate, "Identity already belongs to another object" if existing && !existing.equal?(entity)
+        @entities[[type, Values.detach(id)]] = entity
+      end
+
+      def remove(type, id); @entities.delete([type, id]); end
+      def clear; @entities.clear; end
+    end
+
+    Entry = Struct.new(:entity, :identity, :mapping, :baseline, :state, :loaded, keyword_init: true)
+
+    class UnitOfWork
+      def initialize(transaction:)
+        @transaction, @entries = transaction, {}.compare_by_identity
+      end
+
+      def entry(entity); @entries.fetch(entity); end
+      def tracked?(entity); @entries.key?(entity); end
+
+      def track(entity, mapping:, baseline:, state: :clean)
+        @entries[entity] ||= Entry.new(entity:, identity: Values.detach(mapping.identity.reader.call(entity)), mapping:, baseline:, state:, loaded: [])
+      end
+
+      def remove(entity)
+        entry = @entries.fetch(entity) { raise InvalidInput, "Entity is not managed by this session" }
+        if entry.state == :new
+          @entries.delete(entity)
+        else
+          entry.state = :deleted
+        end
+      end
+
+      def flush
+        @entries.values.each do |entry|
+          entity, mapping = entry.entity, entry.mapping
+          id = mapping.identity.reader.call(entity)
+          raise InvalidInput, "Managed identity cannot change" unless entry.identity == id
+          if entry.state == :deleted
+            @transaction.delete(mapping.table, id)
+            @entries.delete(entity)
+            next
+          end
+          row = mapping.dump(entity, baseline: entry.baseline, loaded: entry.loaded)
+          if entry.state == :new
+            @transaction.insert(mapping.table, row)
+          elsif row != entry.baseline
+            @transaction.update(mapping.table, id, row)
+          end
+          entry.baseline, entry.state = row, :clean
+        end
+      end
+
+      def clear; @entries.clear; end
+    end
+
+    class Session
+      attr_reader :transaction
+
+      def initialize(transaction:, mappings:)
+        @transaction, @mappings = transaction, mappings
+        @identities, @work = IdentityMap.new, UnitOfWork.new(transaction:)
+        @closed, @removed = false, {}
+      end
+
+      def add(entity)
+        active!
+        mapping = @mappings.fetch(entity.class)
+        unless mapping.identity.reader.call(entity)
+          mapping.identity.writer.call(entity, SecureRandom.uuid)
+        end
+        if @removed.key?([entity.class, mapping.identity.reader.call(entity)])
+          raise InvalidInput, "Removed entities cannot be registered again"
+        end
+        @identities.add(entity.class, mapping.identity.reader.call(entity), entity)
+        @work.track(entity, mapping:, baseline: nil, state: :new)
+        entity
+      end
+
+      def find(type, id, load: [])
+        active!
+        raise NotFound, "Entity was removed" if @removed.key?([type, id])
+        entity = @identities.find(type, id)
+        unless entity
+          mapping = @mappings.fetch(type)
+          row = transaction.find(mapping.table, id)
+          raise NotFound, "Entity not found" unless row
+          entity = attach(mapping, row)
+        end
+        load_associations(entity, load)
+        entity
+      end
+
+      def query(type, query = Query.new, load: [])
+        active!
+        mapping = @mappings.fetch(type)
+        transaction.query(query.for_table(mapping.table)).reject { |row| @removed.key?([type, row[:id]]) }.map do |row|
+          entity = @identities.find(type, row[:id]) || attach(mapping, row)
+          load_associations(entity, load)
+          entity
+        end
+      end
+
+      def remove(entity)
+        active!
+        id = @work.entry(entity).identity
+        @work.remove(entity)
+        @removed[[entity.class, id]] = true
+        @identities.remove(entity.class, id)
+      end
+
+      def flush
+        active!
+        @work.flush
+      end
+
+      def close
+        @closed = true
+        @identities.clear
+        @work.clear
+        @removed.clear
+      end
+
+      private
+
+      def active!
+        raise ClosedSession, "Session is closed" if @closed
+        raise ClosedSession, "Session transaction is no longer active" unless transaction.state == :active
+      end
+
+      def attach(mapping, row)
+        entity = mapping.hydrate(row)
+        @identities.add(mapping.entity_class, row[:id], entity)
+        @work.track(entity, mapping:, baseline: row)
+        entity
+      end
+
+      def load_associations(entity, plan)
+        entry = @work.entry(entity)
+        plan.each do |item|
+          name, nested = item.is_a?(Hash) ? item.first : [item, []]
+          association = entry.mapping.associations.find { |candidate| candidate.name == name }
+          raise ConfigurationError, "Unknown association: #{name}" unless association
+          unless entry.loaded.include?(name)
+            entry.loaded << name
+            value = if association.kind == :belongs_to
+              id = entry.baseline&.fetch(association.foreign_key, nil)
+              find(association.target, id) if id
+            else
+              id = entry.mapping.identity.reader.call(entity)
+              query(association.target, Query.new.where(**{ association.foreign_key => id }))
+            end
+            association.writer.call(entity, value)
+          end
+          value = association.reader.call(entity)
+          children = association.kind == :has_many ? value : [value].compact
+          children.each { |child| load_associations(child, nested) } unless nested.empty?
+        end
+      end
+    end
+  end
+end

data/lib/object_framework/persistence/transaction.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module Persistence
+    class ClosedTransaction < StandardError; end
+    class ReadOnlyTransaction < StandardError; end
+
+    class Transaction
+      attr_reader :state, :mode
+
+      def initialize(mode:)
+        raise ConfigurationError, "Invalid transaction mode" unless %i[read write].include?(mode)
+        @mode, @state, @closed = mode, :active, false
+      end
+
+      def rollback
+        active!
+        rollback_storage
+        @state = :rolled_back
+      end
+
+      def close
+        return if @closed
+        begin
+          rollback if @state == :active
+        ensure
+          @closed = true
+          close_storage
+        end
+      end
+
+      private
+
+      def active!
+        raise ClosedTransaction, "Transaction is no longer active" if @closed || @state != :active
+      end
+
+      def writable!
+        active!
+        raise ReadOnlyTransaction, "Cannot modify a read transaction" unless mode == :write
+      end
+
+      def row_value(row, id: row[:id])
+        raise InvalidInput, "A row identity is required" unless id.is_a?(String) && !id.empty?
+        raise InvalidInput, "Row identity cannot change" unless row[:id] == id
+        row.each_key { |field| Query.identifier(field) }
+        Values.detach(row)
+      end
+
+      def rollback_storage; end
+      def close_storage; end
+    end
+  end
+end

data/lib/object_framework/protobuf.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module Protobuf
+    SCALARS = {
+      int32: 0, int64: 0, uint32: 0, uint64: 0, sint32: 0, sint64: 0, bool: 0,
+      fixed64: 1, sfixed64: 1, double: 1, string: 2, bytes: 2,
+      fixed32: 5, sfixed32: 5, float: 5
+    }.freeze
+
+    def self.name(value)
+      raise ConfigurationError, "Invalid protobuf name" unless /\A[A-Za-z_][A-Za-z_0-9]*\z/.match?(value.to_s)
+      value.to_s.dup.freeze
+    end
+
+    module Wire
+      def self.varint(value)
+        raise InvalidInput, "Varint is out of range" unless value.is_a?(Integer) && value.between?(0, 2**64 - 1)
+        bytes = +"".b
+        while value >= 128
+          bytes << ((value & 127) | 128)
+          value >>= 7
+        end
+        bytes << value
+      end
+
+      class Cursor
+        attr_reader :position
+        def initialize(bytes); @bytes, @position = bytes.b, 0; end
+        def done?; @position == @bytes.bytesize; end
+
+        def take(count)
+          raise InvalidInput, "Truncated protobuf field" if count.negative? || @position + count > @bytes.bytesize
+          result = @bytes.byteslice(@position, count)
+          @position += count
+          result
+        end
+
+        def varint
+          result = 0
+          10.times do |index|
+            byte = take(1).getbyte(0)
+            raise InvalidInput, "Varint overflow" if index == 9 && byte > 1
+            result |= (byte & 127) << (index * 7)
+            return result if byte < 128
+          end
+          raise InvalidInput, "Varint overflow"
+        end
+
+        def skip(wire)
+          case wire
+          when 0 then varint
+          when 1 then take(8)
+          when 2 then take(varint)
+          when 5 then take(4)
+          else raise InvalidInput, "Unsupported protobuf wire type"
+          end
+        end
+      end
+    end
+
+    class Enum
+      attr_reader :name, :values
+      def initialize(name, **values)
+        @name, @values = Protobuf.name(name), values.dup.freeze
+        raise ConfigurationError, "A proto3 enum must begin with zero" unless values.values.first == 0
+        raise ConfigurationError, "Duplicate enum value" unless values.values.uniq.size == values.size
+        values.each { |key, value| Protobuf.name(key); raise ConfigurationError, "Invalid enum value" unless value.is_a?(Integer) && value.between?(-(2**31), 2**31 - 1) }
+        freeze
+      end
+
+      def definition
+        "enum #{name} {\n" + values.map { |key, value| "  #{key} = #{value};\n" }.join + "}\n"
+      end
+    end
+
+    Field = Data.define(:name, :number, :type, :repeated, :packed)
+
+    class Message
+      attr_reader :name, :fields
+
+      def initialize(name, &declaration)
+        @name, @fields = Protobuf.name(name), []
+        instance_eval(&declaration) if declaration
+        @numbers = fields.to_h { |field| [field.number, field] }.freeze
+        @fields.freeze
+        freeze
+      end
+
+      def field(name, number, type, repeated: false, packed: true)
+        name = Protobuf.name(name).to_sym
+        unless number.is_a?(Integer) && number.between?(1, 2**29 - 1) && !number.between?(19_000, 19_999)
+          raise ConfigurationError, "Invalid protobuf field number"
+        end
+        raise ConfigurationError, "Duplicate protobuf field" if fields.any? { |field| field.name == name || field.number == number }
+        raise ConfigurationError, "Unknown protobuf type" unless SCALARS.key?(type) || type.is_a?(Message) || type.is_a?(Enum)
+        @fields << Field.new(name:, number:, type:, repeated:, packed:)
+      end
+
+      def encode(values = nil, depth: 0, **attributes)
+        raise InvalidInput, "Protobuf nesting limit exceeded" if depth >= 64
+        raise InvalidInput, "Pass message values once" if values && !attributes.empty?
+        values ||= attributes
+        values = values.to_h if values.is_a?(Data)
+        raise InvalidInput, "Expected protobuf message values" unless values.is_a?(Hash)
+        values = values.transform_keys { |key| key.to_s.to_sym }
+        raise InvalidInput, "Unknown protobuf field" unless (values.keys - fields.map(&:name)).empty?
+        fields.each_with_object(+"".b) do |field, output|
+          next unless values.key?(field.name)
+          value = values[field.name]
+          if field.repeated
+            raise InvalidInput, "Repeated fields require arrays" unless value.is_a?(Array)
+            if packable?(field) && field.packed && !value.empty?
+              payload = value.map { |item| encode_value(field.type, item, depth:) }.join.b
+              output << Wire.varint((field.number << 3) | 2) << Wire.varint(payload.bytesize) << payload
+            else
+              value.each { |item| output << encode_field(field, item, depth:) }
+            end
+          elsif !default?(field.type, value)
+            output << encode_field(field, value, depth:)
+          end
+        end
+      end
+
+      def decode(bytes, depth: 0, initial: nil)
+        raise InvalidInput, "Protobuf nesting limit exceeded" if depth >= 64
+        cursor = Wire::Cursor.new(bytes)
+        result = initial ? Values.mutable_copy(initial) : fields.to_h { |field| [field.name, default_value(field)] }
+        until cursor.done?
+          tag = cursor.varint
+          number, wire = tag >> 3, tag & 7
+          raise InvalidInput, "Invalid protobuf field tag" unless number.between?(1, 2**29 - 1)
+          field = @numbers[number]
+          if field && field.repeated && packable?(field) && wire == 2
+            packed = Wire::Cursor.new(cursor.take(cursor.varint))
+            result[field.name] << decode_value(field.type, packed, depth:) until packed.done?
+          elsif field && wire == wire_type(field.type)
+            value = decode_value(field.type, cursor, depth:, initial: field.type.is_a?(Message) && !field.repeated ? result[field.name] : nil)
+            field.repeated ? result[field.name] << value : result[field.name] = value
+          else
+            cursor.skip(wire)
+          end
+        end
+        Values.detach(result)
+      end
+
+      def dependencies
+        fields.map(&:type).select { |type| type.is_a?(Message) || type.is_a?(Enum) }
+      end
+
+      def definition
+        "message #{name} {\n" + fields.map do |field|
+          type = field.type.respond_to?(:name) ? field.type.name : field.type.to_s
+          option = field.repeated && packable?(field) && !field.packed ? " [packed = false]" : ""
+          "  #{field.repeated ? 'repeated ' : ''}#{type} #{field.name} = #{field.number}#{option};\n"
+        end.join + "}\n"
+      end
+
+      private
+
+      def wire_type(type)
+        return 2 if type.is_a?(Message)
+        return 0 if type.is_a?(Enum)
+        SCALARS.fetch(type)
+      end
+
+      def packable?(field); wire_type(field.type) != 2; end
+
+      def default_value(field)
+        return [] if field.repeated
+        return nil if field.type.is_a?(Message)
+        return 0 if field.type.is_a?(Enum)
+        case field.type
+        when :string then ""
+        when :bytes then "".b
+        when :bool then false
+        when :float, :double then 0.0
+        else 0
+        end
+      end
+
+      def default?(type, value)
+        return value.nil? if type.is_a?(Message)
+        return value.is_a?(Integer) && value.zero? if type.is_a?(Enum)
+        case type
+        when :string, :bytes then value == ""
+        when :bool then value == false
+        when :float, :double then value == 0 && !value.to_s.start_with?("-")
+        else value.is_a?(Integer) && value.zero?
+        end
+      end
+
+      def encode_field(field, value, depth:)
+        payload = encode_value(field.type, value, depth:)
+        tag = Wire.varint((field.number << 3) | wire_type(field.type))
+        wire_type(field.type) == 2 ? tag + Wire.varint(payload.bytesize) + payload : tag + payload
+      end
+
+      def bounded(value, bits:, signed:)
+        minimum, maximum = signed ? [-(2**(bits - 1)), 2**(bits - 1) - 1] : [0, 2**bits - 1]
+        raise InvalidInput, "Protobuf integer is out of range" unless value.is_a?(Integer) && value.between?(minimum, maximum)
+        value
+      end
+
+      def encode_value(type, value, depth:)
+        return type.encode(value, depth: depth + 1) if type.is_a?(Message)
+        if type.is_a?(Enum)
+          value = type.values.fetch(value) { raise InvalidInput, "Unknown enum symbol" } if value.is_a?(Symbol)
+          return Wire.varint(bounded(value, bits: 32, signed: true) & (2**64 - 1))
+        end
+        case type
+        when :string, :bytes
+          raise InvalidInput, "Expected a protobuf string" unless value.is_a?(String)
+          raise InvalidInput, "Invalid UTF-8 string" if type == :string && !value.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+          value.b
+        when :bool
+          raise InvalidInput, "Expected a protobuf boolean" unless value == true || value == false
+          Wire.varint(value ? 1 : 0)
+        when :float, :double
+          raise InvalidInput, "Expected a protobuf number" unless value.is_a?(Numeric)
+          [value].pack(type == :float ? "e" : "E")
+        else
+          bits = type.to_s.end_with?("32") ? 32 : 64
+          signed = !%i[uint32 uint64 fixed32 fixed64].include?(type)
+          value = bounded(value, bits:, signed:)
+          case type
+          when :sint32, :sint64 then Wire.varint((value << 1) ^ (value >> (bits - 1)))
+          when :fixed32 then [value].pack("V")
+          when :sfixed32 then [value].pack("l<")
+          when :fixed64 then [value].pack("Q<")
+          when :sfixed64 then [value].pack("q<")
+          else Wire.varint(value & (2**64 - 1))
+          end
+        end
+      end
+
+      def decode_value(type, cursor, depth:, initial: nil)
+        return type.decode(cursor.take(cursor.varint), depth: depth + 1, initial:) if type.is_a?(Message)
+        if type.is_a?(Enum)
+          value = cursor.varint & (2**32 - 1)
+          return value >= 2**31 ? value - 2**32 : value
+        end
+        case type
+        when :string, :bytes
+          value = cursor.take(cursor.varint)
+          if type == :string
+            value.force_encoding(Encoding::UTF_8)
+            raise InvalidInput, "Invalid UTF-8 string" unless value.valid_encoding?
+          end
+          value
+        when :bool then !cursor.varint.zero?
+        when :float then cursor.take(4).unpack1("e")
+        when :double then cursor.take(8).unpack1("E")
+        when :fixed32 then cursor.take(4).unpack1("V")
+        when :sfixed32 then cursor.take(4).unpack1("l<")
+        when :fixed64 then cursor.take(8).unpack1("Q<")
+        when :sfixed64 then cursor.take(8).unpack1("q<")
+        else
+          bits = type.to_s.end_with?("32") ? 32 : 64
+          value = cursor.varint & (2**bits - 1)
+          return (value >> 1) ^ -(value & 1) if %i[sint32 sint64].include?(type)
+          return value - 2**bits if %i[int32 int64].include?(type) && value >= 2**(bits - 1)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/object_framework/sqlite/compiler.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module SQLite
+    class Compiler
+      OPERATORS = { eq: "=", ne: "!=", gt: ">", gte: ">=", lt: "<", lte: "<=" }.freeze
+
+      def initialize(schema:)
+        @schema = schema
+      end
+
+      def query(query)
+        @schema.table(query.table)
+        bindings = []
+        sql = "SELECT * FROM #{@schema.quote(query.table)}"
+        unless query.criteria.empty?
+          sql += " WHERE " + query.criteria.map { |criterion| predicate(query.table, criterion, bindings) }.join(" AND ")
+        end
+        ordering = query.ordering.any? { |field, _| field == :id } ? query.ordering : query.ordering + [[:id, :asc]]
+        sql += " ORDER BY " + ordering.map do |field, direction|
+          @schema.type(query.table, field)
+          "#{@schema.quote(field)} #{direction == :desc ? 'DESC' : 'ASC'}"
+        end.join(", ")
+        if query.row_limit || query.row_offset.positive?
+          sql += " LIMIT ? OFFSET ?"
+          bindings += [query.row_limit || -1, query.row_offset]
+        end
+        [sql, bindings]
+      end
+
+      def encode(table, column, value)
+        type = @schema.type(table, column)
+        return nil if value.nil?
+        valid = case type
+        when :string, :blob then value.is_a?(String)
+        when :integer then value.is_a?(Integer) && value.between?(-(2**63), 2**63 - 1)
+        when :float then value.is_a?(Numeric) && value.to_f.finite?
+        when :boolean then value == true || value == false
+        end
+        raise InvalidInput, "Invalid storage field type" unless valid
+        return value ? 1 : 0 if type == :boolean
+        return ::SQLite3::Blob.new(value) if type == :blob
+        value
+      end
+
+      def decode(table, row)
+        return nil unless row
+        Values.detach(row.to_h do |column, value|
+          type = @schema.type(table, column)
+          [column.to_sym, type == :boolean && !value.nil? ? value != 0 : value]
+        end)
+      end
+
+      private
+
+      def predicate(table, criterion, bindings)
+        field = @schema.quote(criterion.field)
+        @schema.type(table, criterion.field)
+        if criterion.operator == :in
+          values = criterion.value.reject(&:nil?)
+          parts = []
+          unless values.empty?
+            bindings.concat(values.map { |value| encode(table, criterion.field, value) })
+            parts << "#{field} IN (#{(['?'] * values.size).join(', ')})"
+          end
+          parts << "#{field} IS NULL" if criterion.value.include?(nil)
+          return parts.empty? ? "0" : "(#{parts.join(' OR ')})"
+        end
+        if criterion.value.nil? && %i[eq ne].include?(criterion.operator)
+          return "#{field} IS #{criterion.operator == :ne ? 'NOT ' : ''}NULL"
+        end
+        bindings << encode(table, criterion.field, criterion.value)
+        "#{field} #{OPERATORS.fetch(criterion.operator)} ?"
+      end
+    end
+  end
+end