permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/operators/rule_column.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext/module/delegation'
+
 module PermissionForge
   module Operators
     # The model column a rule's field_name names, as far as it can be told:
@@ -16,58 +18,212 @@ module PermissionForge
     # text after all. A lookup that is more generous than the database costs
     # nothing: the database then rejects the name itself.
     #
-    # When the table is none of the rule's, or has no such column, nothing is
-    # known and the value is left as it is. A field_name that is not a name
-    # ({.name?}) is {#malformed?}: such a rule matches nothing.
+    # When the table is none of the rule's, what the name is depends on the
+    # names the rule's query gives its tables ({RuleSources}: the FROM and
+    # JOINs, with the aliases ActiveRecord assigns — never a name that merely
+    # appears in a join condition): a name the join gives that is no model
+    # table (`parents_customers` on a self-join) is {UNKNOWN} and left to the
+    # database — unless the column it names holds ciphertext
+    # ({EncryptedAlias}: the name is resolved to the table it stands for and
+    # every loaded model on that table — a `has_many :through`'s join table
+    # and a table a default scope joins too; one that cannot be resolved
+    # counts as encrypted when any model along the path encrypts a column of
+    # that name), when it is that model's column, {#encrypted?}; a real table
+    # that is none of the rule's is {FOREIGN} (a filter
+    # rule compares its model's own table: it matches nothing; a join rule's
+    # query has to join that table itself); anything else is {#unresolvable?}
+    # ({UNRESOLVABLE}) and the rule matches nothing — the database would
+    # reject the query (`no such column: supplier_id.id`), and every holder
+    # would get an error instead of a denial. A table of the rule's that has
+    # no such column is {#missing?}: the database would reject the query, so
+    # a built-in operator matches nothing for it (ValueTyping.no_column?). A
+    # field_name that is not a name ({.name?}) is {#malformed?}: such a rule
+    # matches nothing. A column of an attribute declared with `encrypts`
+    # holds ciphertext ({#encrypted?}): no built-in operator that takes a
+    # value can compare it (ValueTyping).
     class RuleColumn
       # Adapters whose database compares a quoted name as it is written. On
       # every other one — MySQL, SQLite — `Flag` is the column `flag`.
       EXACT_NAMES = %w[PostgreSQL PostGIS].freeze
 
+      # What makes a rule's column or path "cannot tell" for a caller that
+      # only describes it (for_rule, RuleProblem.of_path — the admin, the
+      # audit, the model's checks): anything raised while the models are
+      # loaded or asked, a model file's SyntaxError or LoadError included.
+      # The applier's own walk does not rescue them (RulePath).
+      UNTELLABLE = [StandardError, ScriptError].freeze
+      # A character no name has (see .name?).
+      CONTROL_CHARACTER = /[[:cntrl:]]/
+
       # @return [ActiveRecord::ConnectionAdapters::Column, nil]
       attr_reader :column
       # @return [Hash, nil] label => stored value, when the model declares the column an enum
       attr_reader :enum
+      # @return [Class, nil] the model whose table the name was looked up in; nil when no table was
+      attr_reader :model
 
       class << self
         # A field name is one name, or several joined by dots. An empty one
         # among them — a leading, trailing or doubled dot, or nothing at all —
         # makes it no name: quoted segment by segment it would be another
-        # name than the one that was written.
+        # name than the one that was written. So does a control character (a
+        # newline, a NUL byte) in one: no column is called that, and quoted
+        # into a statement it reaches the database as written.
         def name?(field_name)
           segments = field_name.to_s.split('.', -1)
-          segments.any? && segments.none?(&:empty?)
+          segments.any? && segments.none? { |segment| segment.empty? || segment.match?(CONTROL_CHARACTER) }
         end
 
         # @param field_name [String] the rule's field_name
         # @param models [Array<Class>] the rule's model, then the model of each
         #   association on its path (see {.models_along})
+        # @param joined [Hash{String => String, nil}, Array<String>, nil] the
+        #   names a join rule's query gives its tables, with the table each
+        #   stands for ({RuleSources.tables}; a list of names: tables not
+        #   known); nil for a filter rule, whose query joins nothing of its own
         # @return [RuleColumn]
-        def find(field_name, models)
+        def find(field_name, models, joined: nil)
           return MALFORMED unless name?(field_name)
+          return UNKNOWN if models.empty?
 
           *qualifier, name = field_name.to_s.split('.')
-          model = table_model(qualifier.last, models)
-          model ? on(model, name) : UNKNOWN
+          table = qualifier.last
+          model = table_model(table, models) || EncryptedAlias.new(models, joined).model(table, name)
+          model ? on(model, name) : elsewhere(table, models.last, joined)
+        end
+
+        # Whether the connection has a data source (a table or view) named
+        # `table`: asked only for a qualifier that is none of the rule's
+        # tables. A "no" is asked of the database again once
+        # (PermissionForge::SchemaRead.table?): the schema cache may predate
+        # a table a migration just created.
+        #
+        # @param model [Class] a model on the connection
+        # @param table [String] the name as written
+        def data_source?(model, table)
+          PermissionForge::SchemaRead.table?(model, table)
+        end
+
+        # The columns a rule may compare on a model: every column of its
+        # table as the database knows them (a model's `ignored_columns`
+        # among them, as in .find) — the names the admin's rule builder
+        # offers and the model's validation accepts, one list.
+        #
+        # The list is compared with the database first
+        # (PermissionForge::SchemaRead, `verify: true`): a column a migration
+        # added since the schema was read is offered.
+        #
+        # @param model [Class] a model with a table
+        # @param verify [Boolean] false when the caller compared the columns already
+        # @return [Array<String>]
+        def names_for(model, verify: true)
+          PermissionForge::SchemaRead.columns(model, verify: verify).keys
+        end
+
+        # The column a rule row names, looked up the way PermissionRuleApplier
+        # looks it up: in the model its Resource is named after and along its
+        # association path (join rules only). nil when that cannot be told —
+        # the Resource names no model, the model cannot be loaded (its file
+        # raises anything as it loads: UNTELLABLE), the path cannot be
+        # followed, a table along it does not exist (asking a missing table
+        # for its columns fails the statement, and with it a transaction) or
+        # the database cannot be asked.
+        #
+        # `verify: true` (a rule being saved) compares the columns of every
+        # model along the path with the database first (one metadata query
+        # each, PermissionForge::SchemaRead): a name the process confirmed
+        # missing before a migration added it is accepted at save. The
+        # describing callers (the admin's pages, the audit) ask without it.
+        #
+        # @param rule [PermissionForge::PermissionSetRule]
+        # @param verify [Boolean]
+        # @return [RuleColumn, nil]
+        def for_rule(rule, verify: false)
+          model = rule_model(rule)
+          return unless model
+
+          chain = rule.join_rule? ? path_segments(rule.field_accessor_path) : []
+          models = models_along(model, chain)
+          find(rule.field_name, models, joined: rule_join_names(rule, model, chain)) if readable?(models, verify)
+        rescue *UNTELLABLE
+          nil
         end
 
         # The rule's own model, then the model of each association on its path;
-        # a plain field_name is a column of the last one.
+        # a plain field_name is a column of the last one. The path is
+        # followed by {RulePath}, the way ActiveRecord joins it.
         #
         # @param model [Class] the rule's model
         # @param association_chain [Array<String>] the rule's field_accessor_path, split
-        # @return [Array<Class>] empty when the path cannot be followed
+        # @return [Array<Class>] empty when the path cannot be followed (RulePath#broken?)
         def models_along(model, association_chain)
-          association_chain.reduce([model]) do |models, assoc|
-            joined = models.last.reflect_on_association(assoc.to_sym)&.klass
-            break [] unless joined
+          RulePath.follow(model, association_chain).models
+        end
+
+        # A rule's association path (its field_accessor_path), split into
+        # the association names the applier joins; a blank one is no path.
+        #
+        # @param path [String, nil]
+        # @return [Array<String>]
+        def path_segments(path)
+          path.blank? ? [] : path.to_s.split('.')
+        end
+
+        # The model the rule's Resource is named after, when it is one with a
+        # table (PermissionForge::ModelLookup, the one definition).
+        #
+        # @param rule [PermissionForge::PermissionSetRule]
+        # @return [Class, nil]
+        def rule_model(rule)
+          PermissionForge::ModelLookup.model_for(rule.resource&.name)
+        end
 
-            models << joined
-          end
+        # Whether `written` names `own` the way the database compares names
+        # (exactly where it compares a quoted name as written: EXACT_NAMES).
+        #
+        # @param own [String] the name as the schema or the model has it
+        # @param written [String] the name as the rule writes it
+        # @param exact [Boolean] see #exact_names?
+        def same_name?(own, written, exact)
+          own == written || (!exact && own.casecmp?(written))
+        end
+
+        # Whether the model's database compares a quoted name as written.
+        #
+        # @param model [Class]
+        def exact_names?(model)
+          EXACT_NAMES.include?(adapter_name(model))
         end
 
         private
 
+        # A qualifier that is none of the rule's models: a name the query
+        # gives a table (an alias: `joined` is a Hash of name => table, or a
+        # list of names), a real table, or nothing at all.
+        def elsewhere(table, model, joined)
+          return UNKNOWN if joined&.any? { |source, _table| same_name?(source, table, exact_names?(model)) }
+
+          data_source?(model, table) ? FOREIGN : UNRESOLVABLE
+        end
+
+        # nil for a filter rule (no join of its own); a join rule's join
+        # names, read only for a qualified field_name.
+        def rule_join_names(rule, model, chain)
+          return unless rule.join_rule?
+
+          rule.field_name.to_s.include?('.') ? RuleSources.of_join(model, rule.join_type, chain) : {}
+        end
+
+        # Every table along the path is there (asking a missing one for its
+        # columns fails the statement); compared with the database first when
+        # `verify`.
+        def readable?(models, verify)
+          return false unless models.any? && models.all? { |model| PermissionForge::SchemaRead.table?(model, model.table_name) }
+
+          models.each { |model| PermissionForge::SchemaRead.columns(model, verify: true) } if verify
+          true
+        end
+
         # The model a table name stands for; without one, the model the rule ends on.
         def table_model(table, models)
           return models.last unless table
@@ -75,45 +231,104 @@ module PermissionForge
           models.find { |model| same_name?(model.table_name.to_s.split('.').last, table, exact_names?(model)) }
         end
 
+        # The table's column of that name; a name the schema cache does not
+        # have is looked up again once after the schema is read again
+        # (PermissionForge::SchemaRead): a column a migration just added.
         def on(model, name)
-          connection = model.connection
-          column = column_named(connection.schema_cache.columns_hash(model.table_name), name, exact_names?(model))
-          new(column, column && model.defined_enums[column.name], connection.adapter_name)
+          exact = exact_names?(model)
+          column = PermissionForge::SchemaRead.column(model, name) { |columns| column_named(columns, name, exact) }
+          new(column, column && model.defined_enums[column.name], adapter_name(model), model)
         end
 
         def column_named(columns, name, exact)
           columns[name] || columns.each_value.find { |column| same_name?(column.name, name, exact) }
         end
 
-        def same_name?(own, written, exact)
-          own == written || (!exact && own.casecmp?(written))
-        end
-
-        def exact_names?(model)
-          EXACT_NAMES.include?(model.connection.adapter_name)
+        # Through the pool, never `model.connection` (it raises under
+        # ActiveRecord.permanent_connection_checkout = :disallowed).
+        def adapter_name(model)
+          model.connection_pool.with_connection(&:adapter_name)
         end
       end
 
-      def initialize(column, enum, adapter_name)
+      def initialize(column, enum, adapter_name, model = nil)
         @column = column
         @enum = enum
         @adapter_name = adapter_name
+        @model = model
       end
 
-      # Nothing is known about the column: no table of the rule, or no such column.
+      # Nothing is known about the column: the name's table is none of the
+      # rule's models but a name the rule's query gives a table (an alias a
+      # join gives), or the path cannot be followed.
       UNKNOWN = new(nil, nil, nil).freeze
+      # The name's table is a real table that is none of the rule's (not its
+      # model's, not one along its path or its query's joins): a filter rule
+      # matches nothing (RuleProblem :foreign_table); a join rule's query has
+      # to join it itself, or it matches nothing too.
+      FOREIGN = new(nil, nil, nil).freeze
       # The rule's field_name is not a name.
       MALFORMED = new(nil, nil, nil).freeze
+      # The name's table is none of the rule's and no table of the database
+      # (a rule that joins nothing): the database would reject the query.
+      UNRESOLVABLE = new(nil, nil, nil).freeze
 
       def malformed?
         equal?(MALFORMED)
       end
 
+      # The name is qualified with a real table that is none of the rule's (see FOREIGN).
+      def foreign?
+        equal?(FOREIGN)
+      end
+
+      # The name is qualified with a table that is not there (see UNRESOLVABLE):
+      # such a rule matches nothing.
+      def unresolvable?
+        equal?(UNRESOLVABLE)
+      end
+
+      # The name's table is one of the rule's ({#model}), and it has no such
+      # column: the database would reject a query that compares it.
+      def missing?
+        !model.nil? && column.nil?
+      end
+
+      # Whether the column holds ciphertext: an attribute of {#model} — the
+      # class the rule is applied to (the applier's model class), one along
+      # its path, or one on a table its query joins (EncryptedAlias) —
+      # declared with `encrypts` by it or a class of its hierarchy on its
+      # table (PermissionForge::EncryptedAttributes). Asked with the column's
+      # own name (a field name written in another case resolves to it).
+      def encrypted?
+        return false if model.nil? || column.nil?
+
+        PermissionForge::EncryptedAttributes.encrypted?(model, column.name)
+      end
+
+      class << self
+        # @!method encrypted?(model, name)
+        #   Whether `name` is a column of `model` that holds ciphertext (an
+        #   attribute declared with `encrypts`; PermissionForge::EncryptedAttributes,
+        #   the one definition): a rule can only ask whether it is empty. What
+        #   the admin's rule builder asks before it offers a column.
+        #   @param model [Class, nil] the model whose table the column is in
+        #   @param name [String, Symbol] the column's name, as the model has it
+        #   @return [Boolean]
+        delegate :encrypted?, to: PermissionForge::EncryptedAttributes
+      end
+
       # The caster for the column's type, on the database it is in.
       #
       # @return [#call] see ValueCasters.for
       def caster
-        ValueCasters.for(column, @adapter_name)
+        ValueCasters.for(column, @adapter_name, model)
+      end
+
+      # Whether a LIKE pattern can be matched against the column, on the
+      # database it is in (ValueCasters.pattern?).
+      def pattern?
+        ValueCasters.pattern?(caster, @adapter_name)
       end
     end
   end

data/lib/permission_forge/operators/rule_path.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Operators
+    # A join rule's association path (its field_accessor_path, split on
+    # dots), followed from the rule's model the way ActiveRecord follows it
+    # when it builds the join: the one walk of a path (the applier, the
+    # column lookup, the model's validation and the audit all go through it).
+    #
+    # ActiveRecord raises for a join it cannot build — when the query runs,
+    # so in every find_by / permission_scoped of the rule's holders. Before
+    # it joins a name (Associations::JoinDependency#build) it looks the
+    # association up by that name and asks the reflection check_validity!
+    # and check_eager_loadable!; a polymorphic one raises, and the class of
+    # every other one is loaded. A segment that fails any of those is where
+    # the path {#broken?}:
+    #
+    # - :unknown_association — the model has no association of that name
+    #   (a typo: `ownr`), or the segment is empty (`parent..owner`; cause
+    #   :empty_segment);
+    # - :unjoinable_association — the association is there, but no join can
+    #   be built through it; {#cause} says why (UNJOINABLE_CAUSES).
+    #
+    # Everything ActiveRecord joins — has_many / has_one / belongs_to,
+    # :through, has_and_belongs_to_many, a scoped association — is followed.
+    # A rule whose path is broken matches nothing (PermissionRuleApplier):
+    # the join would raise.
+    #
+    # A model file that raises a ScriptError (SyntaxError, LoadError) while
+    # it loads is not a broken path: the error propagates, from the applier
+    # too (the query raises; it never answers). An admin-facing caller that
+    # only describes the path (RuleProblem.of_path, RuleColumn.for_rule)
+    # treats it as "cannot tell".
+    #
+    # @example
+    #   path = RulePath.follow(Customer, %w[supplier owner])
+    #   path.models  # => [Customer, Supplier, User]
+    #   RulePath.follow(Customer, %w[ownr]).reason # => :unknown_association
+    class RulePath
+      # Why an association is there but cannot be joined (#cause of an
+      # :unjoinable_association path), in the order they are checked:
+      #
+      # - :invalid_definition — its :through, :source or inverse_of names an
+      #   association that is not there (Reflection#check_validity! raises);
+      # - :polymorphic — a polymorphic belongs_to: no one class to join;
+      # - :record_dependent_scope — its scope, or one along its :through
+      #   (the through association's or the source's), takes the record
+      #   (`->(record) { … }`): a join has no record to give it;
+      # - :class_not_loadable — its class (or one along its :through) cannot
+      #   be loaded: no such constant, or its file raised while it loaded.
+      UNJOINABLE_CAUSES = %i[invalid_definition polymorphic record_dependent_scope class_not_loadable].freeze
+
+      # @return [Array<Class>] the rule's model, then the model of each
+      #   association on the path; empty when the path is broken
+      attr_reader :models
+      # @return [String, nil] the segment the path breaks at
+      attr_reader :segment
+      # @return [Class, nil] the model that segment was looked up in
+      attr_reader :owner
+      # @return [Symbol, nil] :unknown_association or :unjoinable_association
+      attr_reader :reason
+      # @return [Symbol, nil] :empty_segment for an empty segment, one of
+      #   UNJOINABLE_CAUSES for an :unjoinable_association, else nil
+      attr_reader :cause
+
+      # @param model [Class] the rule's model
+      # @param association_chain [Array<String>] the rule's field_accessor_path, split
+      # @return [RulePath]
+      def self.follow(model, association_chain)
+        association_chain.reduce(new([model])) do |path, name|
+          path.through(name.to_s)
+        end
+      end
+
+      def initialize(models, segment: nil, owner: nil, reason: nil, cause: nil)
+        @models = models
+        @segment = segment
+        @owner = owner
+        @reason = reason
+        @cause = cause
+      end
+
+      def broken?
+        !@reason.nil?
+      end
+
+      # The path one association further; a broken path stays broken where it broke.
+      #
+      # @param name [String] the next segment
+      # @return [RulePath]
+      def through(name)
+        return self if broken?
+
+        owner = models.last
+        at = { segment: name, owner: owner }
+        return RulePath.new([], **at, reason: :unknown_association, cause: :empty_segment) if name.empty?
+
+        reflection = owner._reflect_on_association(name)
+        return RulePath.new([], **at, reason: :unknown_association) unless reflection
+
+        cause = RulePath.unjoinable_cause(reflection)
+        return RulePath.new([], **at, reason: :unjoinable_association, cause: cause) if cause
+
+        RulePath.new(models + [reflection.klass])
+      end
+
+      class << self
+        # The relation with the path joined, the way every rule's join is
+        # made (the applier's query, RuleColumn.join_names): one association
+        # by name, a longer path as the nested Hash ActiveRecord joins.
+        #
+        # @param relation [ActiveRecord::Relation]
+        # @param join_method [Symbol] one of PermissionRuleApplier::JOIN_METHODS — never a rule's own text
+        # @param association_chain [Array<String>] the rule's path, split
+        # @return [ActiveRecord::Relation]
+        def join(relation, join_method, association_chain)
+          return relation if association_chain.empty?
+
+          relation.public_send(join_method, join_structure(association_chain))
+        end
+
+        # Where ActiveRecord would raise building a join through the
+        # reflection, why (UNJOINABLE_CAUSES); nil when it builds one. A raise
+        # of any kind counts: it would be raised in the holders' queries.
+        # check_validity! and check_eager_loadable! are what JoinDependency
+        # asks of the reflection itself; a :through also evaluates the scopes
+        # along its chain (record_dependent?).
+        #
+        # @param reflection [ActiveRecord::Reflection::AbstractReflection]
+        # @return [Symbol, nil] one of UNJOINABLE_CAUSES
+        def unjoinable_cause(reflection)
+          failure(:invalid_definition) { reflection.check_validity! } ||
+            (:polymorphic if reflection.polymorphic?) ||
+            failure(:record_dependent_scope) { reflection.check_eager_loadable! } ||
+            failure(:class_not_loadable) { reflection.klass } ||
+            (:record_dependent_scope if record_dependent?(reflection))
+        end
+
+        private
+
+        # `supplier` => :supplier; `supplier.owner` => { supplier: :owner }.
+        def join_structure(association_chain)
+          *outer, last = association_chain.map(&:to_sym)
+          outer.reverse.reduce(last) { |inner, name| { name => inner } }
+        end
+
+        # nil when the block raises nothing (what it answers is not looked
+        # at). When it raises: `cause` for what a definition or a check raises
+        # (an ActiveRecordError, ArgumentError or NoMethodError), else
+        # :class_not_loadable — a constant that is not there (NameError), or
+        # whatever a model file raised as it loaded.
+        def failure(cause)
+          yield
+          nil
+        rescue NoMethodError, ArgumentError, ActiveRecord::ActiveRecordError
+          cause
+        rescue StandardError
+          :class_not_loadable
+        end
+
+        # Whether a scope along the reflection's join chain takes the record:
+        # the reflection's own, the :through association's (and so on along
+        # the chain), and the source's of each :through. A chain that cannot
+        # be walked counts: the join would raise walking it.
+        def record_dependent?(reflection)
+          reflection.chain.any? do |link|
+            takes_record?(link.scope) || (link.through_reflection? && record_dependent?(link.source_reflection))
+          end
+        rescue StandardError
+          true
+        end
+
+        def takes_record?(scope)
+          !scope.nil? && !scope.arity.zero?
+        end
+      end
+    end
+  end
+end