torque-postgresql 4.0.1 → 4.1.1

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative 'simple_enum'
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      # The common ground between the classes that back a column with a set of
+      # typed properties, like structs and composite types. It carries enough of
+      # the ActiveRecord attribute surface for its own features, and for the
+      # ActiveRecord concerns that build on top of it, to work
+      class Base
+        include ActiveModel::Model
+        include ActiveModel::Attributes
+        include ActiveModel::Serialization
+        include ActiveModel::Serializers::JSON
+        include ActiveModel::Dirty
+        include ActiveModel::Validations::Callbacks
+
+        include SimpleEnum
+        include ActiveRecord::Store
+        include(AR810 ? ActiveModel::Attributes::Normalization : ActiveRecord::Normalization)
+        include ActiveRecord::Encryption::EncryptableRecord
+
+        class_attribute :filter_attributes, instance_accessor: false, default: []
+
+        class << self
+          # These classes are not backed by a table, so nothing here has the
+          # extra information that a column would provide
+          def columns_hash
+            {}
+          end
+
+          # Encrypt individual attributes, so their values are stored encrypted
+          # inside the column that holds them
+          def encrypts(*names, **options)
+            names.each do |name|
+              raise ArgumentError, <<~MSG.squish unless attribute_names.include?(name.to_s)
+                Unable to encrypt "#{name}" because it is not a declared
+                attribute of #{self.name}.
+              MSG
+            end
+
+            super
+          end
+
+          def inspection_filter
+            ActiveSupport::ParameterFilter.new(filter_attributes)
+          end
+        end
+
+        def inspect
+          self.class.inspection_filter.filter(to_h).inspect
+        end
+
+        # Plain access to any property, declared or not
+        def [](key)
+          key = key.to_s
+          @attributes.key?(key) ? @attributes.fetch_value(key) : nil
+        end
+
+        def []=(key, value)
+          assign_attributes(key => value)
+        end
+
+        def ==(other)
+          other.class == self.class && other.attributes == attributes
+        end
+        alias eql? ==
+
+        def empty?
+          @attributes.keys.empty?
+        end
+
+        def hash
+          [self.class, attributes].hash
+        end
+
+        def to_h
+          attributes.symbolize_keys
+        end
+
+        def type_for_attribute(name, &block)
+          self.class.type_for_attribute(name, &block)
+        end
+
+        def read_attribute_before_type_cast(name)
+          @attributes[name.to_s].value_before_type_cast
+        end
+
+        def read_attribute_for_database(name)
+          @attributes[name.to_s].value_for_database
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      class Composite < Base
+        class << self
+          attr_writer :type_name
+
+          # Find or create the class that will handle the composite type. It
+          # first checks the irregular types mapping, then the namespace
+          def lookup(name)
+            name = name.to_s.underscore
+            mapping = PostgreSQL.config.composite.irregular_types
+            return resolve(mapping[name].constantize, name) if mapping.key?(name)
+
+            const     = name.camelize
+            namespace = PostgreSQL.config.composite.namespace
+
+            return resolve(namespace.const_get(const), name) if namespace.const_defined?(const)
+            resolve(namespace.const_set(const, Class.new(Composite)), name)
+          end
+
+          def inherited(subclass)
+            super
+            subclass.instance_variable_set(:@load_columns_monitor, ::Monitor.new)
+          end
+
+          # The name of the composite type on the database
+          def type_name
+            @type_name ||= name.demodulize.underscore
+          end
+
+          # The ordered list of columns of the composite type, as a hash of
+          # name and type, loaded in a lazy way
+          def columns
+            load_columns
+            @columns
+          end
+
+          # Load the columns from the database and define any attribute that
+          # was not manually declared
+          def load_columns
+            return if self == Composite || defined?(@columns)
+
+            @load_columns_monitor.synchronize do
+              next if defined?(@columns)
+
+              columns = ActiveRecord::Base.with_connection { |c| c.composite_column_types(type_name) }
+              columns.each do |attr_name, attr_type|
+                attribute(attr_name, attr_type) unless attribute_names.include?(attr_name)
+              end
+
+              @columns = columns
+            end
+          end
+
+          # Drop the loaded columns, so that they are collected again on the
+          # next use, which happens after the type is changed
+          def reset_columns!
+            @load_columns_monitor.synchronize do
+              remove_instance_variable(:@columns) if defined?(@columns)
+            end
+          end
+
+          def new(*args, **xargs, &block)
+            load_columns
+            super
+          end
+
+          # Columns have to be in place before any of them can be decorated
+          def encrypts(*names, **options)
+            load_columns
+            super
+          end
+
+          def enum(*args, **xargs)
+            load_columns
+            super
+          end
+
+          private
+
+            # Make sure that the class knows the name of the type it handles,
+            # since it can be resolved from an irregular mapping
+            def resolve(klass, name)
+              klass.type_name = name
+              klass
+            end
+        end
+      end
+    end
+
+    Composite = Attributes::Composite
+  end
+end

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

@@ -39,11 +39,22 @@ module Torque
             super
           end
 
+          def inherited(subclass)
+            super
+            subclass.instance_variable_set(:@load_values_monitor, ::Monitor.new)
+          end
+
           # Load the list of values in a lazy way
           def values
-            @values ||= self == Enum ? nil : begin
-              connection.enum_values(type_name).freeze
+            return if self == Enum
+            return @values if defined?(@values)
+
+            @load_values_monitor.synchronize do
+              next if defined?(@values)
+              @values = ::ActiveRecord::Base.with_connection { |c| c.enum_values(type_name) }.freeze
             end
+
+            @values
           end
 
           # List of values as symbols
@@ -104,11 +115,6 @@ module Torque
               valid?(method_name) ? new(method_name.to_s) : super
             end
 
-            # Get a connection based on its name
-            def connection
-              ::ActiveRecord::Base.connection
-            end
-
         end
 
         # Override string initializer to check for a valid value

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      # A pattern that matches label paths, as described by the +lquery+ data
+      # type. It holds the pure items of the pattern: labels as Strings, +:any+
+      # for a star, a Range for a quantified star and an Array for a group of
+      # alternatives
+      class LQuery
+        include Enumerable
+
+        MARKERS = /[*|!{}@%]/
+        LEVEL = /\A(?<not>!)?(?<variants>.*?)(?:\{(?<min>\d*)(?<comma>,)?(?<max>\d*)\})?\z/
+        VARIANT = /\A(?<name>.*?)(?<modifiers>[*@%]*)\z/
+
+        attr_reader :items
+
+        delegate :inspect, to: :to_s
+        delegate :each, :size, :empty?, :[], to: :items
+
+        def self.[](*items)
+          new(items)
+        end
+
+        def initialize(value = nil, sanitize: true)
+          @items = type.items_for(value, sanitize: sanitize).freeze
+        end
+
+        def to_s
+          type.serialize(self)
+        end
+
+        def pattern?
+          items.any? { |item| !item.is_a?(::String) || item.match?(MARKERS) }
+        end
+
+        def pattern
+          @pattern ||= compile
+        end
+
+        def match?(path)
+          path = LTree.new(path) unless path.is_a?(LTree)
+          pattern.match?(path.to_s)
+        end
+
+        def =~(path)
+          path = LTree.new(path) unless path.is_a?(LTree)
+          pattern =~ path.to_s
+        end
+
+        def ==(other)
+          other = other.items if other.is_a?(self.class)
+          other.is_a?(::Array) && items == other
+        end
+        alias eql? ==
+
+        def hash
+          items.hash
+        end
+
+        private
+
+          def type
+            Adapter::OID::Lquery.new
+          end
+
+          def compile
+            levels = to_s.split('.', -1).map { |level| compile_level(level) }
+            Regexp.new("\\A#{levels.join}\\z")
+          end
+
+          def compile_level(text)
+            match = text.match(LEVEL)
+            variants = match[:variants]
+            label = variants == '*' ? '[^.]+' : compile_variants(variants.split('|'))
+            label = "(?!#{label}(?:\\.|\\z))[^.]+" if match[:not]
+            "(?:(?:\\A|\\.)#{label})#{quantifier(match)}"
+          end
+
+          def compile_variants(variants)
+            sources = variants.map { |variant| compile_variant(variant) }
+            "(?:#{sources.join('|')})"
+          end
+
+          def compile_variant(text)
+            match = text.match(VARIANT)
+            modifiers = match[:modifiers]
+            prefix = modifiers.include?('*')
+            name = match[:name]
+
+            source = modifiers.include?('%') ? words(name, prefix) : label(name, prefix)
+            modifiers.include?('@') ? "(?i:#{source})" : source
+          end
+
+          def label(name, prefix)
+            "#{Regexp.escape(name)}#{'[^.]*' if prefix}"
+          end
+
+          def words(name, prefix)
+            lookaheads = name.split('_').reject(&:empty?).map do |word|
+              "(?=(?:[^.]*_)?#{Regexp.escape(word)}#{'[^._]*' if prefix}(?:[_.]|\\z))"
+            end
+
+            "#{lookaheads.join}[^.]+"
+          end
+
+          def quantifier(match)
+            return match[:variants] == '*' ? '*' : '' if match[:min].nil?
+
+            min = match[:min].presence || 0
+            max = match[:comma] ? match[:max] : min
+            "{#{min},#{max}}"
+          end
+      end
+    end
+
+    LQuery = Attributes::LQuery
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Torque
+  module PostgreSQL
+    module Attributes
+      # A label path, as stored by the +ltree+ data type. It holds the plain
+      # list of labels, so it enumerates like any other list, and an +ltree[]+
+      # column simply becomes an Array of these
+      class LTree
+        include Enumerable
+
+        attr_reader :items
+
+        delegate :inspect, to: :to_s
+        delegate :each, :size, :empty?, :[], to: :items
+        alias depth size
+
+        class << self
+          def [](*items)
+            new(items)
+          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
+        end
+
+        def initialize(value = nil, sanitize: true)
+          @items = type.items_for(value, sanitize: sanitize).freeze
+        end
+
+        def to_s
+          type.serialize(self)
+        end
+
+        def ==(other)
+          other = other.items if other.is_a?(self.class)
+          other.is_a?(::Array) && items == other
+        end
+        alias eql? ==
+
+        def hash
+          items.hash
+        end
+
+        def root?
+          size <= 1
+        end
+
+        def root
+          self.class.new(items.first(1), sanitize: false)
+        end
+
+        def parent
+          self.class.new(items[0..-2], sanitize: false) unless root?
+        end
+
+        def /(other)
+          self.class.new(items + self.class.new(other).items, sanitize: false)
+        end
+
+        alias_method :+, :/
+
+        # Same as the +@>+ operator, which includes the path itself
+        def ancestor_of?(other)
+          other = self.class.new(other).items
+          size <= other.size && other.first(size) == items
+        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).items[0..-2] }
+          result = paths.shift
+          paths.each { |path| result = common_prefix(result, path) }
+          self.class.new(result, sanitize: false)
+        end
+
+        def index_of(subpath, offset = 0)
+          subpath = self.class.new(subpath).items
+          offset += size if offset.negative?
+          return -1 if subpath.empty? || offset.negative?
+
+          range = offset..(size - subpath.size)
+          position = range.find { |i| items[i, subpath.size] == subpath }
+          position || -1
+        end
+
+        private
+
+          def type
+            Adapter::OID::Ltree.new
+          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