iknow_view_models 2.8.4

data/lib/view_model/access_control.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'view_model/access_control_error'
+
+## Defines an access control discipline for a given action against a viewmodel.
+##
+## Access control is based around three edit check hooks: visible, editable and
+## valid_edit. The visible determines whether a view can be seen. The editable
+## check determines whether a view in its current state is eligible to be
+## changed. The valid_edit change determines whether an attempted change is
+## permitted. Each edit check returns a pair of boolean success and optional
+## exception to raise.
+class ViewModel::AccessControl
+  Result = Struct.new(:permit, :error) do
+    def initialize(permit, error: nil)
+      raise ArgumentError.new("Successful AccessControl::Result may not have an error") if permit && error
+      super(permit, error)
+    end
+
+    alias :permit? :permit
+
+    # Merge this result with another access control result. Takes a block
+    # returning a result, and returns a combined result for both tests. Access
+    # is permitted if both results permit. Otherwise, access is denied with the
+    # error value of the first denying Result.
+    def merge(&_block)
+      if permit?
+        yield
+      else
+        self
+      end
+    end
+  end
+
+  Result::PERMIT = Result.new(true).freeze
+  Result::DENY   = Result.new(false).freeze
+
+  def initialize
+    @initial_editability_store = {}
+  end
+
+  # Check that the user is permitted to view the record in its current state, in
+  # the given context.
+  def visible_check(_traversal_env)
+    Result::DENY
+  end
+
+  # Editable checks during deserialization are always a combination of
+  # `editable_check` and `valid_edit_check`, which express the following
+  # separate properties. `The after_deserialize check passes if both checks are
+  # successful.
+
+  # Check that the record is eligible to be changed in its current state, in the
+  # given context. This must be called before any edits have taken place (thus
+  # checking against the initial state of the viewmodel), and if editing is
+  # denied, an error must be raised only if an edit is later attempted. To be
+  # overridden by viewmodel implementations.
+  def editable_check(_traversal_env)
+    Result::DENY
+  end
+
+  # Once the changes to be made to the viewmodel are known, check that the
+  # attempted changes are permitted in the given context. For viewmodels with
+  # transactional backing models, the changes may be made in advance to give the
+  # edit checks the opportunity to compare values. To be overridden by viewmodel
+  # implementations.
+  def valid_edit_check(_traversal_env)
+    Result::DENY
+  end
+
+  # Wrappers to check access control for a single view directly. Because the
+  # checking is run directly on one node without any tree context, it's only
+  # valid to run:
+  # * on root views
+  # * when no children could contribute to the result
+  def visible!(view, context:)
+    run_callback(ViewModel::Callbacks::Hook::BeforeVisit, view, context)
+    run_callback(ViewModel::Callbacks::Hook::AfterVisit,  view, context)
+  end
+
+  def editable!(view, deserialize_context:, changes:)
+    run_callback(ViewModel::Callbacks::Hook::BeforeVisit,       view, deserialize_context)
+    run_callback(ViewModel::Callbacks::Hook::BeforeDeserialize, view, deserialize_context)
+    run_callback(ViewModel::Callbacks::Hook::OnChange,          view, deserialize_context, changes: changes) if changes
+    run_callback(ViewModel::Callbacks::Hook::AfterDeserialize,  view, deserialize_context, changes: changes)
+    run_callback(ViewModel::Callbacks::Hook::AfterVisit,        view, deserialize_context)
+  end
+
+  # Edit checks are invoked via traversal callbacks:
+  include ViewModel::Callbacks
+
+  before_visit do
+    result = visible_check(self)
+
+    raise_if_error!(result) do
+      ViewModel::AccessControlError.new(
+        "Illegal access to viewmodel '#{view.class.view_name}'",
+        view.blame_reference)
+    end
+  end
+
+  before_deserialize do
+    initial_result = editable_check(self)
+
+    save_editability(view, initial_result)
+  end
+
+  on_change do
+    initial_result = fetch_editability(view)
+    result = initial_result.merge do
+      valid_edit_check(self)
+    end
+
+    raise_if_error!(result) do
+      ViewModel::AccessControlError.new(
+        "Illegal edit to viewmodel '#{view.class.view_name}'",
+        view.blame_reference)
+    end
+  end
+
+  after_deserialize do
+    # If there was no change to consume the initial editability we still want to clean it up
+    cleanup_editability(view)
+  end
+
+  private
+
+  def save_editability(view, initial_editability)
+    if @initial_editability_store.has_key?(view.object_id)
+      raise RuntimeError.new("Access control data already recorded for view #{view.to_reference}")
+    end
+    @initial_editability_store[view.object_id] = initial_editability
+  end
+
+  def fetch_editability(view)
+    unless @initial_editability_store.has_key?(view.object_id)
+      raise RuntimeError.new("No access control data recorded for view #{view.to_reference}")
+    end
+    @initial_editability_store.delete(view.object_id)
+  end
+
+  def cleanup_editability(view)
+    @initial_editability_store.delete(view.object_id)
+  end
+
+  def raise_if_error!(result)
+    raise (result.error || yield) unless result.permit?
+  end
+end
+
+require 'view_model/access_control/open'
+require 'view_model/access_control/read_only'
+require 'view_model/access_control/composed'
+require 'view_model/access_control/tree'

data/lib/view_model/access_control/composed.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+## Provides access control as a combination of `x_if!` and `x_unless!` checks
+## for each access check (visible, editable, edit_valid). An action is permitted
+## if at least one `if` check and no `unless` checks succeed. For example:
+##    edit_valid_if!("logged in as specified user") { ... }
+##    edit_valid_unless!("user is on fire") { ... }
+class ViewModel::AccessControl::Composed < ViewModel::AccessControl
+  ComposedResult = Struct.new(:allow, :veto, :allow_error, :veto_error) do
+    def initialize(allow, veto, allow_error, veto_error)
+      raise ArgumentError.new("Non-vetoing result may not have a veto error") if veto_error  && !veto
+      raise ArgumentError.new("Allowing result may not have a allow error")   if allow_error && allow
+      super
+    end
+
+    def permit?
+      !veto && allow
+    end
+
+    def error
+      case
+      when veto   then veto_error
+      when !allow then allow_error
+      else nil
+      end
+    end
+
+    # Merge this composed result with another. `allow`s widen and `veto`es narrow.
+    def merge(&_block)
+      if self.veto
+        self
+      else
+        other = yield
+
+        new_allow = self.allow || other.allow
+
+        new_allow_error =
+          case
+          when new_allow
+            nil
+          when self.allow_error && other.allow_error
+            self.allow_error.merge(other.allow_error)
+          else
+            self.allow_error || other.allow_error
+          end
+
+        ComposedResult.new(new_allow, other.veto, new_allow_error, other.veto_error)
+      end
+    end
+  end
+
+  PermissionsCheck = Struct.new(:location, :reason, :error_type, :checker) do
+    def name
+      "#{reason} (#{location})"
+    end
+
+    def check(env)
+      env.instance_exec(&self.checker)
+    end
+  end
+
+  # Error type when no `if` conditions succeed.
+  class NoRequiredConditionsError < ViewModel::AccessControlError
+    attr_reader :reasons
+
+    def initialize(nodes, reasons)
+      super("Action not permitted because none of the possible conditions were met.", nodes)
+      @reasons = reasons
+    end
+
+    def meta
+      super.merge(conditions: @reasons.to_a)
+    end
+
+    def merge(other)
+      NoRequiredConditionsError.new(nodes | other.nodes,
+                                    Lazily.concat(reasons, other.reasons).uniq)
+    end
+  end
+
+  class << self
+    attr_reader :edit_valid_ifs,
+                :edit_valid_unlesses,
+                :editable_ifs,
+                :editable_unlesses,
+                :visible_ifs,
+                :visible_unlesses
+
+    def inherited(subclass)
+      super
+      subclass.initialize_as_composed_access_control
+    end
+
+    def initialize_as_composed_access_control
+      @included_checkers   = []
+
+      @edit_valid_ifs      = []
+      @edit_valid_unlesses = []
+
+      @editable_ifs        = []
+      @editable_unlesses   = []
+
+      @visible_ifs         = []
+      @visible_unlesses    = []
+    end
+
+    ## Configuration API
+    def include_from(ancestor)
+      unless ancestor < ViewModel::AccessControl::Composed
+        raise ArgumentError.new("Invalid ancestor: #{ancestor}")
+      end
+
+      @included_checkers << ancestor
+    end
+
+    def visible_if!(reason, &block)
+      @visible_ifs         << new_permission_check(reason, &block)
+    end
+
+    def visible_unless!(reason, &block)
+      @visible_unlesses    << new_permission_check(reason, &block)
+    end
+
+    def editable_if!(reason, &block)
+      @editable_ifs        << new_permission_check(reason, &block)
+    end
+
+    def editable_unless!(reason, &block)
+      @editable_unlesses   << new_permission_check(reason, &block)
+    end
+
+    def edit_valid_if!(reason, &block)
+      @edit_valid_ifs      << new_permission_check(reason, &block)
+    end
+
+    def edit_valid_unless!(reason, &block)
+      @edit_valid_unlesses << new_permission_check(reason, &block)
+    end
+
+    ## Implementation
+
+    def new_permission_check(reason, error_type: ViewModel::AccessControlError, &block)
+      PermissionsCheck.new(self.name&.demodulize, reason, error_type, block)
+    end
+
+    def each_check(check_name, include_ancestor = nil)
+      return enum_for(:each_check, check_name, include_ancestor) unless block_given?
+
+      self.public_send(check_name).each { |x| yield x }
+
+      visited = Set.new
+      @included_checkers.each do |ancestor|
+        next unless visited.add?(ancestor)
+        next if include_ancestor && !include_ancestor.call(ancestor)
+        ancestor.each_check(check_name) { |x| yield x }
+      end
+    end
+
+    def inspect
+      s = super + "("
+      s += inspect_checks.join(", ")
+      s += " includes checkers: #{@included_checkers.inspect}" if @included_checkers.present?
+      s += ")"
+      s
+    end
+
+    def inspect_checks
+      checks = []
+      checks << "visible_if: #{@visible_ifs.map(&:reason)}"                if @visible_ifs.present?
+      checks << "visible_unless: #{@visible_unlesses.map(&:reason)}"       if @visible_unlesses.present?
+      checks << "editable_if: #{@editable_ifs.map(&:reason)}"              if @editable_ifs.present?
+      checks << "editable_unless: #{@editable_unlesses.map(&:reason)}"     if @editable_unlesses.present?
+      checks << "edit_valid_if: #{@edit_valid_ifs.map(&:reason)}"          if @edit_valid_ifs.present?
+      checks << "edit_valid_unless: #{@edit_valid_unlesses.map(&:reason)}" if @edit_valid_unlesses.present?
+      checks
+    end
+
+  end
+
+  # final
+  def visible_check(traversal_env)
+    check_delegates(traversal_env, self.class.each_check(:visible_ifs), self.class.each_check(:visible_unlesses))
+  end
+
+  # final
+  def editable_check(traversal_env)
+    check_delegates(traversal_env, self.class.each_check(:editable_ifs), self.class.each_check(:editable_unlesses))
+  end
+
+  # final
+  def valid_edit_check(traversal_env)
+    check_delegates(traversal_env, self.class.each_check(:edit_valid_ifs), self.class.each_check(:edit_valid_unlesses))
+  end
+
+  protected
+
+  def check_delegates(env, ifs, unlesses)
+    vetoed_checker = unlesses.detect { |checker| checker.check(env) }
+
+    veto = vetoed_checker.present?
+    if veto
+      veto_error = vetoed_checker.error_type.new("Action not permitted because: " +
+                                                 vetoed_checker.reason,
+                                                 env.view.blame_reference)
+    end
+
+    allow = ifs.any? { |checker| checker.check(env) }
+
+    unless allow
+      allow_error = NoRequiredConditionsError.new(env.view.blame_reference,
+                                                  ifs.map(&:name))
+    end
+
+    ComposedResult.new(allow, veto, allow_error, veto_error)
+  end
+end

data/lib/view_model/access_control/open.rb

@@ -0,0 +1,13 @@
+class ViewModel::AccessControl::Open < ViewModel::AccessControl
+  def visible_check(_traversal_env)
+    ViewModel::AccessControl::Result::PERMIT
+  end
+
+  def editable_check(_traversal_env)
+    ViewModel::AccessControl::Result::PERMIT
+  end
+
+  def valid_edit_check(_traversal_env)
+    ViewModel::AccessControl::Result::PERMIT
+  end
+end

data/lib/view_model/access_control/read_only.rb

@@ -0,0 +1,13 @@
+class ViewModel::AccessControl::ReadOnly < ViewModel::AccessControl
+  def visible_check(_traversal_env)
+    ViewModel::AccessControl::Result::PERMIT
+  end
+
+  def editable_check(_traversal_env)
+    ViewModel::AccessControl::Result::DENY
+  end
+
+  def valid_edit_check(_traversal_env)
+    ViewModel::AccessControl::Result::DENY
+  end
+end

data/lib/view_model/access_control/tree.rb

@@ -0,0 +1,264 @@
+## Defines an access control discipline for a given action against a tree of
+## viewmodels.
+##
+## Extends the basic AccessControl to offer different checking based on the view
+## type and position in a viewmodel tree.
+##
+## Access checks for each given node type are specified at class level as
+## `ComposedAccessControl`s, using `view` blocks. Checks that apply to all node
+## types are specified in an `always` block.
+##
+## In addition, node types can be marked as a 'root'. Root types may permit and
+## veto access to their non-root tree descendents with the additional access
+## checks `root_children_{editable,visible}_if!` and `root_children_
+## {editable,visible}_unless!`. The results of evaluating these checks on entry
+## to the root node.object_id will be cached and used when evaluating `visible` and
+## `editable` on children.
+class ViewModel::AccessControl::Tree < ViewModel::AccessControl
+  class << self
+    attr_reader :view_policies
+
+    def inherited(subclass)
+      super
+      subclass.initialize_as_tree_access_control
+    end
+
+    def initialize_as_tree_access_control
+      @included_checkers = []
+      @view_policies     = {}
+      const_set(:AlwaysPolicy, Class.new(Node))
+    end
+
+    def include_from(ancestor)
+      unless ancestor < ViewModel::AccessControl::Tree
+        raise ArgumentError.new("Invalid ancestor: #{ancestor}")
+      end
+
+      @included_checkers << ancestor
+
+      self::AlwaysPolicy.include_from(ancestor::AlwaysPolicy)
+      ancestor.view_policies.each do |view_name, ancestor_policy|
+        policy = find_or_create_policy(view_name)
+        policy.include_from(ancestor_policy)
+      end
+    end
+
+    # Definition language
+    def view(view_name, &block)
+      policy = find_or_create_policy(view_name)
+      policy.instance_exec(&block)
+    end
+
+    def always(&block)
+      self::AlwaysPolicy.instance_exec(&block)
+    end
+
+    ## implementation
+
+    def create_policy(view_name)
+      policy = Class.new(Node)
+      # View names are not necessarily rails constants, but we want
+      # `const_set` them so they show up in stack traces.
+      mangled_name = view_name.tr('.', '_')
+      const_set(:"#{mangled_name}Policy", policy)
+      view_policies[view_name] = policy
+      policy.include_from(self::AlwaysPolicy)
+      policy
+    end
+
+    def find_or_create_policy(view_name)
+      view_policies.fetch(view_name) { create_policy(view_name) }
+    end
+
+    def inspect
+      "#{super}(checks:\n#{@view_policies.values.map(&:inspect).join("\n")}\n#{self::AlwaysPolicy.inspect}\nincluded checkers: #{@included_checkers})"
+    end
+  end
+
+  def initialize
+    super()
+    @always_policy_instance = self.class::AlwaysPolicy.new(self)
+    @view_policy_instances  = self.class.view_policies.each_with_object({}) { |(name, policy), h| h[name] = policy.new(self) }
+    @root_visibility_store  = {}
+    @root_editability_store = {}
+  end
+
+  # Evaluation entry points
+  def visible_check(traversal_env)
+    policy_instance_for(traversal_env.view).visible_check(traversal_env)
+  end
+
+  def editable_check(traversal_env)
+    policy_instance_for(traversal_env.view).editable_check(traversal_env)
+  end
+
+  def valid_edit_check(traversal_env)
+    policy_instance_for(traversal_env.view).valid_edit_check(traversal_env)
+  end
+
+  def store_descendent_editability(view, descendent_editability)
+    if @root_editability_store.has_key?(view.object_id)
+      raise RuntimeError.new("Root access control data already saved for root")
+    end
+    @root_editability_store[view.object_id] = descendent_editability
+  end
+
+  def fetch_descendent_editability(view)
+    @root_editability_store.fetch(view.object_id) do
+      raise RuntimeError.new("No root access control data recorded for root")
+    end
+  end
+
+  def store_descendent_visibility(view, descendent_visibility)
+    if @root_visibility_store.has_key?(view.object_id)
+      raise RuntimeError.new("Root access control data already saved for root")
+    end
+    @root_visibility_store[view.object_id] = descendent_visibility
+  end
+
+  def fetch_descendent_visibility(view)
+    @root_visibility_store.fetch(view.object_id) do
+      raise RuntimeError.new("No root access control data recorded for root")
+    end
+  end
+
+  def cleanup_descendent_results(view)
+    @root_visibility_store.delete(view.object_id)
+    @root_editability_store.delete(view.object_id)
+  end
+
+  after_visit do
+    cleanup_descendent_results(view) if context.root?
+  end
+
+  private
+
+  def policy_instance_for(view)
+    view_name = view.class.view_name
+    @view_policy_instances.fetch(view_name) { @always_policy_instance }
+  end
+
+  class Node < ViewModel::AccessControl::Composed
+    class << self
+      attr_reader :root_children_editable_ifs,
+                  :root_children_editable_unlesses,
+                  :root_children_visible_ifs,
+                  :root_children_visible_unlesses
+
+      def inherited(subclass)
+        super
+        subclass.initialize_as_node
+      end
+
+      def initialize_as_node
+        @root = false
+        @root_children_editable_ifs      = []
+        @root_children_editable_unlesses = []
+        @root_children_visible_ifs       = []
+        @root_children_visible_unlesses  = []
+      end
+
+      def root_children_visible_if!(reason, &block)
+        @root = true
+        root_children_visible_ifs << new_permission_check(reason, &block)
+      end
+
+      def root_children_visible_unless!(reason, &block)
+        @root = true
+        root_children_visible_unlesses << new_permission_check(reason, &block)
+      end
+
+      def root_children_editable_if!(reason, &block)
+        @root = true
+        root_children_editable_ifs << new_permission_check(reason, &block)
+      end
+
+      def root_children_editable_unless!(reason, &block)
+        @root = true
+        root_children_editable_unlesses << new_permission_check(reason, &block)
+      end
+
+      def root?
+        @root
+      end
+
+      alias requires_root? root?
+
+      def inspect_checks
+        checks = super
+        if root?
+          checks << "no root checks"
+        else
+          checks << "root_children_visible_if: #{root_children_visible_ifs.map(&:reason)}"            if root_children_visible_ifs.present?
+          checks << "root_children_visible_unless: #{root_children_visible_unlesses.map(&:reason)}"   if root_children_visible_unlesses.present?
+          checks << "root_children_editable_if: #{root_children_editable_ifs.map(&:reason)}"          if root_children_editable_ifs.present?
+          checks << "root_children_editable_unless: #{root_children_editable_unlesses.map(&:reason)}" if root_children_editable_unlesses.present?
+        end
+        checks
+      end
+    end
+
+    def initialize(tree_access_control)
+      super()
+      @tree_access_control = tree_access_control
+    end
+
+    delegate :store_descendent_visibility, :fetch_descendent_visibility,
+             :store_descendent_editability, :fetch_descendent_editability,
+             to: :@tree_access_control
+
+    def visible_check(traversal_env)
+      view    = traversal_env.view
+      context = traversal_env.context
+
+      validate_root!(view, context)
+
+      if context.root?
+        save_root_visibility!(traversal_env)
+        super
+      else
+        root_visibility = fetch_descendent_visibility(context.nearest_root_viewmodel)
+        root_visibility.merge { super }
+      end
+    end
+
+    def editable_check(traversal_env)
+      view                = traversal_env.view
+      deserialize_context = traversal_env.deserialize_context
+
+      validate_root!(view, deserialize_context)
+
+      if deserialize_context.root?
+        save_root_editability!(traversal_env)
+        super
+      else
+        root_editability = fetch_descendent_editability(deserialize_context.nearest_root_viewmodel)
+        root_editability.merge { super }
+      end
+    end
+
+    private
+
+    def validate_root!(view, context)
+      if self.class.requires_root? && !context.root?
+        raise RuntimeError.new("AccessControl instance for #{view.class.view_name} node requires root context but was visited in owned context.")
+      end
+    end
+
+    def save_root_visibility!(traversal_env)
+      result = check_delegates(traversal_env,
+                               self.class.each_check(:root_children_visible_ifs,      ->(a) { a.is_a?(Node) }),
+                               self.class.each_check(:root_children_visible_unlesses, ->(a) { a.is_a?(Node) }))
+
+      store_descendent_visibility(traversal_env.view, result)
+    end
+
+    def save_root_editability!(traversal_env)
+      result = check_delegates(traversal_env,
+                               self.class.each_check(:root_children_editable_ifs,      ->(a) { a.is_a?(Node) }),
+                               self.class.each_check(:root_children_editable_unlesses, ->(a) { a.is_a?(Node) }))
+
+      store_descendent_editability(traversal_env.view, result)
+    end
+  end
+end