torque-postgresql 4.0.0 → 4.1.0

data/lib/torque/postgresql/attributes/lquery.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      # A pattern that matches label paths, as described by the +lquery+ data
+      # type. It is only ever built from Ruby and never parsed back from its
+      # text form, so each entry of the given list becomes one item
+      class LQuery
+        MARKERS = /[*|!{}@%]/
+        QUANTIFIER = /\{(?:\d+|\d*,\d*)\}/
+        LABEL = /[[:alnum:]_-]+/
+        ALTERNATIVE = /#{LABEL}[@*%]{0,3}/
+        ITEM = /\A!?#{ALTERNATIVE}(?:\|#{ALTERNATIVE})*#{QUANTIFIER}?\z/
+        STAR_ITEM = /\A\*#{QUANTIFIER}?\z/
+
+        class << self
+          def [](*items)
+            new(items)
+          end
+
+          # Values coming from the database are valid by construction
+          def load(value)
+            new(value, normalize: false)
+          end
+
+          # Whether the given value asks for a pattern instead of a plain path,
+          # which is what makes a condition use +~+ instead of +=+
+          def marker?(value)
+            Array.wrap(value).any? { |item| item_marker?(item) }
+          end
+
+          private
+
+            def item_marker?(item)
+              return marker?(LTree.compatible(item)) if LTree.compatible?(item)
+
+              case item
+              when ::Symbol then item == :any
+              when ::Range, ::Array, LQuery then true
+              when ::String then item.match?(MARKERS)
+              else false
+              end
+            end
+        end
+
+        attr_reader :items
+
+        def initialize(items, normalize: true)
+          items = normalize ? expand(items) : Array.wrap(items)
+          @items = normalize ? items.map { |item| compile(item) } : items.map(&:to_s)
+        end
+
+        def to_s
+          items.join('.')
+        end
+
+        def ==(other)
+          other.is_a?(LQuery) && to_s == other.to_s
+        end
+        alias eql? ==
+
+        def hash
+          to_s.hash
+        end
+
+        private
+
+          # An object that describes itself as a path contributes every one of
+          # its labels as an item, rather than a single one
+          def expand(value)
+            return expand(LTree.compatible(value)) if LTree.compatible?(value)
+
+            value = value.split('.') if value.is_a?(::String)
+            Array.wrap(value).flat_map { |item| expand_item(item) }
+          end
+
+          def expand_item(item)
+            return expand(LTree.compatible(item)) if LTree.compatible?(item)
+
+            [item]
+          end
+
+          def compile(item)
+            case item
+            when ::Range then compile_range(item)
+            when ::Array then compile_alternatives(item)
+            when ::Symbol then item == :any ? '*' : compile_item(item)
+            when ::String, ::Numeric, ::ActiveRecord::Base then compile_item(item)
+            else
+              raise ArgumentError, <<~MSG.squish
+                Unable to use #{item.inspect} as an lquery item. Items are labels,
+                a Range for a quantified star, or an Array of alternatives.
+              MSG
+            end
+          end
+
+          # A Range is always a quantifier over the star, since a star on its own
+          # already means any number of labels
+          def compile_range(range)
+            min = range.begin
+            max = range.end
+            max -= 1 if max && range.exclude_end?
+
+            invalid = min&.negative? || max&.negative? || (min && max && max < min)
+            raise ArgumentError, <<~MSG.squish if invalid
+              #{range.inspect} is not a valid quantifier for an lquery star.
+            MSG
+
+            return '*' if min.nil? && max.nil?
+            return "*{#{min}}" if min == max
+            return "*{#{min},}" if max.nil?
+            return "*{,#{max}}" if min.nil?
+            "*{#{min},#{max}}"
+          end
+
+          def compile_alternatives(list)
+            raise ArgumentError, <<~MSG.squish if list.empty?
+              An lquery alternation needs at least one label.
+            MSG
+
+            alternatives = list.map { |entry| compile_alternative(entry) }
+            alternatives.join('|')
+          end
+
+          def compile_alternative(entry)
+            alternative = sanitize_labels(assert_plain!(entry))
+
+            raise ArgumentError, <<~MSG.squish unless alternative.match?(/\A#{ALTERNATIVE}\z/)
+              #{entry.inspect} is not a valid lquery alternative. Alternatives are
+              single labels, optionally followed by the #{'@*%'.inspect} modifiers.
+            MSG
+
+            alternative
+          end
+
+          def compile_item(entry)
+            text = assert_plain!(entry)
+            return text if text.match?(STAR_ITEM)
+
+            head, quantifier = split_quantifier(text)
+            item = sanitize_labels(head) + quantifier
+
+            raise ArgumentError, <<~MSG.squish unless item.match?(ITEM)
+              #{entry.inspect} is not a valid lquery item. An item is a label with
+              the optional #{'@*%'.inspect} modifiers, optionally negated with "!",
+              alternated with "|" and quantified with "{n,m}".
+            MSG
+
+            item
+          end
+
+          def assert_plain!(entry)
+            entry = LTree.resolve_record(entry)
+            plain = entry.is_a?(::String) || entry.is_a?(::Symbol) || entry.is_a?(::Numeric)
+            raise ArgumentError, <<~MSG.squish unless plain
+              Unable to use #{entry.inspect} as part of an lquery item.
+            MSG
+
+            entry.to_s
+          end
+
+          # Only the labels are normalized, so that a replacement never rewrites
+          # the structure of the pattern nor the digits of a quantifier
+          def sanitize_labels(text)
+            text.gsub(LABEL) { |label| LTree.sanitize(label) }
+          end
+
+          def split_quantifier(text)
+            match = text.match(/#{QUANTIFIER}\z/)
+            return [text, ''] if match.nil?
+
+            [match.pre_match, match[0]]
+          end
+      end
+    end
+
+    LQuery = Attributes::LQuery
+  end
+end

data/lib/torque/postgresql/attributes/ltree.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      # A label path, as stored by the +ltree+ data type. It is an Array of
+      # labels, so it flows through Ruby like any other list, which also means
+      # that an +ltree[]+ column simply becomes an Array of these
+      class LTree < Array
+        LABEL = /\A[[:alnum:]_-]+\z/
+
+        alias depth size
+
+        class << self
+          def [](*labels)
+            new(labels)
+          end
+
+          # Values coming from the database are valid by construction, so they
+          # skip both the normalization and the validation
+          def load(value)
+            new(value.to_s.split('.'), normalize: false)
+          end
+
+          # Whether the object knows how to describe itself as a path, which is
+          # what allows any class to be used where a path is expected
+          def compatible?(value)
+            method = PostgreSQL.config.ltree.compatible_method
+            method.present? && value.respond_to?(method)
+          end
+
+          # The path that the object describes for itself
+          def compatible(value)
+            method = PostgreSQL.config.ltree.compatible_method
+            value.public_send(method) if compatible?(value)
+          end
+
+          # A record stands for its primary key, which is what makes a path
+          # built out of other records work the same way as one built out of
+          # labels
+          def resolve_record(value)
+            return value unless value.is_a?(::ActiveRecord::Base)
+
+            id = value.id
+            raise ArgumentError, <<~MSG.squish if id.nil?
+              Unable to use #{value.class.name} as a label because its
+              #{value.class.primary_key} is still empty.
+            MSG
+
+            raise ArgumentError, <<~MSG.squish if id.is_a?(::Array)
+              Unable to use #{value.class.name} as a label because it has a
+              composite primary key, which cannot be a single label.
+            MSG
+
+            id
+          end
+
+          # Apply the configured replacements, so callers can feed a source that
+          # does not satisfy PostgreSQL's rules for a label on its own
+          def sanitize(value)
+            replacements = PostgreSQL.config.ltree.sanitize
+            return value if replacements.blank?
+
+            value.gsub(Regexp.union(replacements.keys), replacements)
+          end
+        end
+
+        def initialize(labels = nil, normalize: true)
+          super()
+          concat(normalize ? normalized(labels) : Array.wrap(labels))
+        end
+
+        def to_s
+          join('.')
+        end
+
+        def root?
+          size <= 1
+        end
+
+        def root
+          self.class.new(first, normalize: false)
+        end
+
+        # A path with a single label has no parent, and neither does an empty one
+        def parent
+          self.class.new(self[0..-2], normalize: false) unless root?
+        end
+
+        def /(other)
+          self.class.new(to_a + self.class.new(other), normalize: false)
+        end
+
+        alias_method :+, :/
+
+        # Same as the +@>+ operator, which includes the path itself
+        def ancestor_of?(other)
+          other = self.class.new(other)
+          size <= other.size && other.first(size) == to_a
+        end
+        alias covers? ancestor_of?
+
+        # Same as the +<@+ operator, which includes the path itself
+        def descendant_of?(other)
+          self.class.new(other).ancestor_of?(self)
+        end
+        alias covered_by? descendant_of?
+
+        # The longest common ancestor, which never includes the last label of
+        # any of the paths, exactly like PostgreSQL's own +lca+
+        def lca(*others)
+          paths = [self, *others].map { |path| self.class.new(path)[0..-2].to_a }
+          result = paths.shift || []
+          paths.each { |path| result = common_prefix(result, path) }
+          self.class.new(result, normalize: false)
+        end
+
+        # The position where the given subpath starts, or -1 when it is not
+        # present. Named apart from +index+ so that Array's own contract, of
+        # returning +nil+ when the element is missing, stays intact
+        def index_of(subpath, offset = 0)
+          subpath = self.class.new(subpath)
+          offset += size if offset.negative?
+          return -1 if subpath.empty? || offset.negative?
+
+          range = offset..(size - subpath.size)
+          position = range.find { |i| self[i, subpath.size] == subpath.to_a }
+          position || -1
+        end
+
+        private
+
+          def normalized(labels)
+            entries = Array.wrap(labels).flat_map { |value| split_labels(value) }
+            entries.each { |label| assert_valid_label!(label) }
+          end
+
+          def split_labels(value)
+            return normalized(self.class.compatible(value)) if self.class.compatible?(value)
+
+            value = self.class.resolve_record(value)
+            plain = value.is_a?(::String) || value.is_a?(::Symbol) || value.is_a?(::Numeric)
+            raise ArgumentError, <<~MSG.squish unless plain
+              Unable to use #{value.inspect} as part of an ltree path. A path is a
+              plain sequence of labels, so it accepts neither the alternatives nor
+              the quantifiers that only make sense on an lquery.
+            MSG
+
+            self.class.sanitize(value.to_s).split('.')
+          end
+
+          def assert_valid_label!(label)
+            raise ArgumentError, <<~MSG.squish unless label.match?(LABEL)
+              #{label.inspect} is not a valid ltree label. Labels are limited to
+              letters, numbers, underscores and dashes.
+            MSG
+          end
+
+          def common_prefix(one, other)
+            limit = [one.size, other.size].min
+            size = (0...limit).find { |i| one[i] != other[i] }
+            one.first(size || limit)
+          end
+      end
+    end
+
+    LTree = Attributes::LTree
+  end
+end

data/lib/torque/postgresql/attributes/simple_enum.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      # Brings Rails' own +enum+ to classes that are not backed by a table, which
+      # means everything that depends on a record being persisted, or on a
+      # relation, is left out. Only the +value?+ methods are generated
+      module SimpleEnum
+        extend ActiveSupport::Concern
+
+        # Replaces the module that Rails uses to generate the methods of an
+        # enum, so that only the ones that make sense here are defined
+        class Methods < Module
+          def initialize(klass)
+            @klass = klass
+          end
+
+          private
+
+            attr_reader :klass
+
+            def define_enum_methods(name, value_method_name, value, _scopes, instance_methods)
+              return unless instance_methods
+
+              klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
+              define_method("#{value_method_name}?") do
+                @attributes[name].value_for_database == value
+              end
+            end
+        end
+
+        included do
+          class_attribute :defined_enums, instance_writer: false, default: {}
+        end
+
+        class_methods do
+          include ActiveRecord::Enum
+
+          # Scopes require a relation, so they are never an option here
+          def enum(name, values = nil, **options)
+            super(name, values, **options, scopes: false)
+          end
+
+          private
+
+            def _enum_methods_module
+              @_enum_methods_module ||= begin
+                mod = Methods.new(self)
+                include mod
+                mod
+              end
+            end
+
+            # There are no dangerous class methods to check against, since enums
+            # never define one, and anything that the base class already
+            # provides is off limits
+            def detect_enum_conflict!(enum_name, method_name, klass_method = false)
+              return if klass_method
+              return unless Base.method_defined?(method_name) ||
+                Base.private_method_defined?(method_name)
+
+              raise ArgumentError, <<~MSG.squish
+                You tried to define an enum named "#{enum_name}" on #{name}, but
+                it generates a method "#{method_name}" that is already defined.
+              MSG
+            end
+        end
+      end
+    end
+  end
+end

data/lib/torque/postgresql/attributes/struct.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      class Struct < Base
+        # ActiveModel keeps a sentinel object as the original value of a
+        # property that was never written to, which leaks into +changes+ and
+        # into anything built on top of it, so it reads as nil instead
+        class Uninitialized < ActiveModel::Attribute.const_get(:Uninitialized)
+          def original_value
+          end
+        end
+
+        class << self
+          attr_writer :strict
+
+          # Whether properties that are not declared by the class are rejected
+          def strict?
+            return !!@strict if defined?(@strict)
+            return !!superclass.strict? if superclass.respond_to?(:strict?)
+
+            PostgreSQL.config.struct.default_strict
+          end
+
+          # Declared properties without a default are uninitialized, so that
+          # they are absent from the document until they are written to
+          def _default_attributes
+            @_struct_default_attributes ||= super.map do |attribute|
+              next attribute if attribute.is_a?(ActiveModel::Attribute::UserProvidedDefault)
+              Uninitialized.new(attribute.name, attribute.type)
+            end
+          end
+
+          # Provide a method on the given class to setup which columns are
+          # backed by a struct class
+          def include_on(klass, method_name = nil)
+            method_name ||= PostgreSQL.config.struct.base_method
+            klass.define_singleton_method(method_name) do |column, struct_klass, **options|
+              Struct.build_on(self, column, struct_klass, **options)
+            rescue Interrupt
+              # Not able to build the attribute, maybe pending migrations
+            end
+          end
+
+          # Setup the struct column on the given model, adding the proper
+          # attribute type, default, validation, and delegations
+          def build_on(model, column, klass, default: nil, array: nil, delegate: nil, backfill: nil, strict: nil)
+            return unless model.table_exists?
+
+            column = column.to_s
+            has_encryption = model.respond_to?(:encrypted_attributes) &&
+              model.encrypted_attributes&.include?(column.to_sym)
+
+            raise ArgumentError, <<~MSG.squish if has_encryption
+              Unable to setup the struct column "#{column}" on #{model.name}
+              because the column is encrypted. Encryption is supported on
+              individual struct attributes instead.
+            MSG
+
+            info = model.columns_hash[column]
+            return if info.nil?
+
+            raise ArgumentError, <<~MSG.squish unless %i[json jsonb].include?(info.type)
+              Unable to setup the struct column "#{column}" on #{model.name}
+              because #{info.sql_type} columns cannot hold a document.
+            MSG
+
+            klass = klass.constantize if klass.is_a?(String) || klass.is_a?(Symbol)
+            klass.strict = !!strict if !strict.nil? && klass.respond_to?(:strict=)
+
+            type =
+              if array
+                Adapter::OID::StructList.new(klass, type: info.type, backfill: backfill)
+              else
+                Adapter::OID::Struct.new(klass, type: info.type, backfill: backfill)
+              end
+
+            type = Adapter::OID::StructSet.new(type) if info.array?
+
+            # Defaults that can be composed from the record have to be resolved
+            # on it, all the others are plain attribute defaults
+            if default.is_a?(Proc) || default.is_a?(Symbol)
+              model.attribute(column, type)
+              resolve_default_on(model, column, default)
+            else
+              model.attribute(column, type, default: -> { default&.deep_dup || type.blank_document })
+            end
+
+            Array.wrap(delegate).flat_map do |property|
+              [property, "#{property}="]
+            end.then do |delegations|
+              model.delegate(*delegations, to: column) if delegations.any?
+            end
+
+            model.validates(column, nested: true, allow_blank: true)
+          end
+
+          private
+
+            def reset_default_attributes!
+              @_struct_default_attributes = nil
+              super
+            end
+
+            # Write the default on the record, as soon as it is initialized, so
+            # that it can be composed from the record and properly stored
+            def resolve_default_on(model, column, default)
+              model.after_initialize do
+                next unless new_record?
+                next unless read_attribute_before_type_cast(column).nil?
+                next if attribute_changed?(column)
+
+                value = default.is_a?(Proc) ? instance_exec(&default) : public_send(default)
+                write_attribute(column, value)
+              end
+            end
+        end
+
+        # Properties that are not declared by the class are kept as they are,
+        # without any type, which is only allowed when the class is not strict
+        def attribute_writer_missing(name, value)
+          return super if self.class.strict?
+
+          name = name.to_s
+          attribute = @attributes[name] if @attributes.key?(name)
+          attribute ||= ActiveModel::Attribute.from_database(name, nil, ActiveModel::Type.default_value)
+          @attributes[name] = attribute.with_value_from_user(value)
+        end
+      end
+    end
+
+    Struct = Attributes::Struct
+  end
+end

data/lib/torque/postgresql/base.rb

@@ -17,9 +17,24 @@ module Torque
       end
 
       class_methods do
-        delegate :distinct_on, :with, :itself_only, :cast_records, :join_series,
+        delegate :distinct_on, :with, :itself_only, :expand_records, :join_series,
           :buckets, to: :all
 
+        # Composite values are objects that can be invalid on their own, so the
+        # attributes backed by one are validated alongside the record
+        def load_schema!
+          super
+          return unless PostgreSQL.config.composite.enabled &&
+            Adapter::OID.const_defined?(:Composite)
+
+          attribute_types.each do |name, type|
+            next if Adapter::OID::Composite.from(type).nil?
+            next if _validators[name.to_sym].any?(Validations::NestedValidator)
+
+            validates(name, nested: true)
+          end
+        end
+
         # Make sure that table name is an instance of TableName class
         def reset_table_name
           return super unless PostgreSQL.config.schemas.enabled
@@ -27,24 +42,12 @@ module Torque
         end
 
         # Whenever the base model is inherited, add a list of auxiliary
-        # statements like the one that loads inherited records' relname
+        # statements
         def inherited(subclass)
           super
 
           subclass.class_attribute(:auxiliary_statements_list)
           subclass.auxiliary_statements_list = {}
-
-          record_class = ActiveRecord::Relation._record_class_attribute
-
-          # Define the dynamic attribute that returns the same information as
-          # the one provided by the auxiliary statement
-          subclass.dynamic_attribute(record_class) do
-            klass = self.class
-            next klass.table_name unless klass.physically_inheritances?
-
-            query = klass.unscoped.where(subclass.primary_key => id)
-            query.pluck(klass.arel_table['tableoid'].pg_cast('regclass')).first
-          end
         end
 
         # Specifies a one-to-many association. The following methods for