hyrax 3.0.2 → 3.1.0

data/app/models/concerns/hyrax/suppressible.rb

@@ -10,6 +10,11 @@ module Hyrax
     end
 
     ##
+    # @deprecated use `Hyrax::ResourceStatus` instead. in most cases,
+    #   {#suppressed?} is being called on a {SolrDocumentBehavior}. we continue
+    #   to index `suppressed_bsi` and expose its value as an attribute on solr
+    #   document objects.
+    #
     # Used to restrict visibility on search results for a work that is inactive. If the state is not set, the
     # default behavior is to consider the work not to be suppressed.
     #

data/app/models/concerns/hyrax/user.rb

@@ -31,7 +31,7 @@ module Hyrax::User
 
     scope :guests, ->() { where(guest: true) }
     scope :registered, ->() { where(guest: false) }
-    scope :without_system_accounts, -> { where("#{::User.user_key_field} not in (?)", [::User.batch_user_key, ::User.audit_user_key]) }
+    scope :without_system_accounts, -> { where("#{::User.user_key_field} not in (?)", [::User.batch_user_key, ::User.audit_user_key, ::User.system_user_key]) }
 
     # Validate and normalize ORCIDs
     validates_with OrcidValidator
@@ -145,7 +145,14 @@ module Hyrax::User
   end
 
   module ClassMethods
-    # Override this method if you aren't using email/password
+    def system_user
+      find_or_create_system_user(system_user_key)
+    end
+
+    def system_user_key
+      Hyrax.config.system_user_key
+    end
+
     def audit_user
       find_or_create_system_user(audit_user_key)
     end
@@ -158,7 +165,6 @@ module Hyrax::User
       Hydra.config.user_key_field
     end
 
-    # Override this method if you aren't using email/password
     def batch_user
       find_or_create_system_user(batch_user_key)
     end

data/app/models/hyrax/file_set.rb

@@ -9,6 +9,12 @@ module Hyrax
     include Hyrax::Schema(:core_metadata)
     include Hyrax::Schema(:basic_metadata)
 
+    def self.model_name(name_class: Hyrax::Name)
+      @_model_name ||= begin
+        name_class.new(self, nil, 'FileSet')
+      end
+    end
+
     attribute :file_ids, Valkyrie::Types::Array.of(Valkyrie::Types::ID) # id for FileMetadata resources
     attribute :original_file_id, Valkyrie::Types::ID # id for FileMetadata resource
     attribute :thumbnail_id, Valkyrie::Types::ID # id for FileMetadata resource

data/app/models/hyrax/pcdm_collection.rb

@@ -11,6 +11,7 @@ module Hyrax
 
     attribute :collection_type_gid, Valkyrie::Types::String
     attribute :member_ids, Valkyrie::Types::Array.of(Valkyrie::Types::ID).meta(ordered: true)
+    attribute :member_of_collection_ids, Valkyrie::Types::Set.of(Valkyrie::Types::ID)
 
     ##
     # @api private

data/app/models/hyrax/permission_template.rb

@@ -1,20 +1,61 @@
 # frozen_string_literal: true
 module Hyrax
   ##
-  # Defines behavior that is applied to objects added as members of an AdminSet
+  # Holds policy data about the workflow and permissions applied objects when
+  # they are deposited through an Administrative Set or a Collection. Each
+  # template record has a {#source} (through {#source_id}); the template's
+  # rules inform the behavior of objects deposited through that {#source_model}.
   #
-  #  * access rights to stamp on each object
-  #  * calculate embargo/lease release dates
+  # The {PermissionTemplate} specifies:
   #
-  # There is an interplay between an AdminSet and a PermissionTemplate.
+  # - an {#active_workflow} that the object will enter and be processed through.
+  # - {#access_grants} that can be applied to each object (especially at deposit
+  #   time).
+  # - an embargo configuration ({#release_date} {#release_period}) for default
+  #   embargo behavior.
   #
-  # @see Hyrax::AdminSet for further discussion
-  class PermissionTemplate < ActiveRecord::Base
+  # Additionally, the {PermissionTemplate} grants authority to perform actions
+  # that relate to the Administrative Set/Collection itself. Rules for who can
+  # deposit to, view(?!), or manage the admin set are governed by related
+  # {PermissionTemplateAccess} records. Administrat Sets should have a manager
+  # granted by some such record.
+  #
+  # @todo write up what "default embargo behavior", when it is applied, and how
+  #   it interacts with embargoes specified by user input.
+  #
+  # @example cerating a permission template and manager for an admin set
+  #   admin_set = Hyrax::AdministrativeSet.new(title: 'My Admin Set')
+  #   admin_set = Hyrax.persister.save(resource: admin_set)
+  #
+  #   template = PermissionTemplate.create!(source_id: admin_set.id.to_s)
+  #   Hyrax::PermissionTemplateAccess.create!(permission_template: template,
+  #                                          agent_type: Hyrax::PermissionTemplateAccess::USER,
+  #                                          agent_id: user.user_key,
+  #                                          access: Hyrax::PermissionTemplateAccess::MANAGE)
+  #
+  # @see Hyrax::AdministrativeSet
+  class PermissionTemplate < ActiveRecord::Base # rubocop:disable Metrics/ClassLength
     self.table_name = 'permission_templates'
 
+    ##
+    # @!attribute [rw] source_id
+    #   @return [String] identifier for the {Collection} or {AdministrativeSet}
+    #     to which this template applies.
+    # @!attribute [rw] access_grants
+    #   @return [Hyrax::PermissionTemplateAccess]
+    # @!attribute [rw] active_workflow
+    #   @return [Sipity::Workflow]
+    # @!attribute [rw] available_workflows
+    #   @return [Enumerable<Sipity::Workflow>]
     has_many :access_grants, class_name: 'Hyrax::PermissionTemplateAccess', dependent: :destroy
     accepts_nested_attributes_for :access_grants, reject_if: :all_blank
 
+    # The list of workflows that could be activated; It includes the active workflow
+    has_many :available_workflows, class_name: 'Sipity::Workflow', dependent: :destroy
+
+    # In a perfect world, there would be a join table that enforced uniqueness on the ID.
+    has_one :active_workflow, -> { where(active: true) }, class_name: 'Sipity::Workflow', foreign_key: :permission_template_id
+
     ##
     # @api public
     #
@@ -28,12 +69,6 @@ module Hyrax
       access_grants.where(agent_type: agent_type, access: access).pluck(:agent_id)
     end
 
-    # The list of workflows that could be activated; It includes the active workflow
-    has_many :available_workflows, class_name: 'Sipity::Workflow', dependent: :destroy
-
-    # In a perfect world, there would be a join table that enforced uniqueness on the ID.
-    has_one :active_workflow, -> { where(active: true) }, class_name: 'Sipity::Workflow', foreign_key: :permission_template_id
-
     ##
     # @note this is a convenience method for +Hyrax.query_service.find_by(id: template.source_id)+
     #
@@ -153,6 +188,57 @@ module Hyrax
       visibility == value
     end
 
+    ##
+    # @return [Array<String>]
+    def edit_users
+      agent_ids_for(access: 'manage', agent_type: 'user')
+    end
+
+    ##
+    # @return [Array<String>]
+    def edit_groups
+      agent_ids_for(access: 'manage', agent_type: 'group')
+    end
+
+    ##
+    # @return [Array<String>]
+    def read_users
+      (agent_ids_for(access: 'view', agent_type: 'user') +
+        agent_ids_for(access: 'deposit', agent_type: 'user')).uniq
+    end
+
+    ##
+    # @return [Array<String>]
+    def read_groups
+      (agent_ids_for(access: 'view', agent_type: 'group') +
+        agent_ids_for(access: 'deposit', agent_type: 'group')).uniq -
+        [::Ability.registered_group_name, ::Ability.public_group_name]
+    end
+
+    ##
+    # @return [Boolean]
+    def reset_access_controls(interpret_visibility: false)
+      reset_access_controls_for(collection: source_model,
+                                interpret_visibility: interpret_visibility)
+    end
+
+    ##
+    # @return [Boolean]
+    def reset_access_controls_for(collection:, interpret_visibility: false)
+      interpreted_read_groups = read_groups
+
+      if interpret_visibility
+        visibilities = Hyrax::VisibilityMap.instance
+        interpreted_read_groups -= visibilities.deletions_for(visibility: collection.visibility)
+        interpreted_read_groups += visibilities.additions_for(visibility: collection.visibility)
+      end
+
+      collection.update!(edit_users: edit_users,
+                         edit_groups: edit_groups,
+                         read_users: read_users,
+                         read_groups: interpreted_read_groups.uniq)
+    end
+
     private
 
     # If template requires no delays, check if date is exactly today

data/app/models/hyrax/virus_scanner.rb

@@ -1,23 +1,28 @@
 # frozen_string_literal: true
-# The default virus scanner Hyrax::Works, ported from hydra_works.
-# If ClamAV is present, it will be used to check for the presence of a virus. If ClamAV is not
-# installed or otherwise not available to your application, Hyrax::Works does no virus checking
-# add assumes files have no viruses.
-#
-# @example to use a virus checker other than Hyrax::VirusScanner:
-#   class MyScanner < Hyrax::Works::VirusScanner
-#     def infected?
-#       my_result = Scanner.check_for_viruses(file)
-#       [return true or false]
-#     end
-#   end
-#
-#   # Then set Hyrax::Works to use your scanner either in a config file or initializer:
-#   Hyrax.config.virus_scanner = MyScanner
+
 module Hyrax
+  ##
+  # The default virus scanner ported from +Hyrax::Works+.
+  #
+  # If ClamAV is present, it will be used to check for the presence of a virus.
+  # If ClamAV is not installed or otherwise not available to your application,
+  # +Hyrax::Works+ does no virus checking add assumes files have no viruses.
+  #
+  # @example to use a virus checker other than Hyrax::VirusScanner:
+  #   class MyScanner < Hyrax::Works::VirusScanner
+  #     def infected?
+  #       my_result = Scanner.check_for_viruses(file)
+  #       [return true or false]
+  #     end
+  #   end
+  #
+  #   # Then set Hyrax::Works to use your scanner either in a config file or initializer:
+  #   Hyrax.config.virus_scanner = MyScanner
+  #
   class VirusScanner
     attr_reader :file
 
+    ##
     # @api public
     # @param file [String]
     def self.infected?(file)
@@ -28,7 +33,9 @@ module Hyrax
       @file = file
     end
 
-    # Override this method to use your own virus checking software
+    ##
+    # @note Override this method to use your own virus checking software
+    #
     # @return [Boolean]
     def infected?
       defined?(ClamAV) ? clam_av_scanner : null_scanner
@@ -41,8 +48,10 @@ module Hyrax
       true
     end
 
-    # Always return zero if there's nothing available to check for viruses. This means that
-    # we assume all files have no viruses because we can't conclusively say if they have or not.
+    ##
+    # Always return zero if there's nothing available to check for viruses.
+    # This means that we assume all files have no viruses because we can't
+    # conclusively say if they have or not.
     def null_scanner
       warning "Unable to check #{file} for viruses because no virus scanner is defined" unless
         Rails.env.test?

data/app/models/sipity/agent.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 module Sipity
+  ##
   # A proxy for something that can take an action.
   #
   # * A User can be an agent

data/app/models/sipity/entity.rb

@@ -1,19 +1,39 @@
 # frozen_string_literal: true
 module Sipity
-  # A proxy for the entity that is being processed via workflows.
+  ##
+  # A proxy for the entity (e.g. a repository Object) that is being processed
+  # via workflows.
   #
-  # By using a proxy, we need not worry about polluting the proxy's concerns
-  # with things related to workflow processing.
+  # Objects of this class (and their underlying database records) represent
+  # another object in the context of the workflow process. By using a proxy,
+  # we can avoid polluting the repository object's data and behavior with
+  # things related to workflow processing. This means we can move an object into
+  # and through a workflow without making changes independently from curatorial
+  # considerations (e.g. metadata changes).
+  #
+  # Keeping this object and interface separate also presents a clear seam for
+  # alternative solutions.
+  #
+  # The {Sipity::Entity} relates to repository objects via a +GlobalID+ URI via
+  # {#proxy_for_global_id}. Since the repository objects aren't assumed to be
+  # +ActiveRecord+ or +ActiveModel+ compatible, we use the URI-based system
+  # provided by +GlobalID+ to ensure that this relationship functions independent
+  # of the modelling system used for the respository objects. {#proxy_for} is
+  # provided as a convenience method for retrieving the underlying repository
+  # object.
+  #
+  # Each {Sipity::Entity} holds a relationship to a {Sipity::Workflow}, which is
+  # the active workflow on the object represented by the {Entity}. It also holds
+  # a reference to a {Sipity::WorkflowState}, which is the current state of the
+  # object within the workflow.
   #
-  # The goal is to keep this behavior separate, so that we can possibly
-  # extract the information.
   # @example To get the Sipity::Entity for a work
   #   work = GenericWork.first
-  #   work_global_id = Hyrax::GlobalID(work).to_s
-  #   => "gid://whatever/GenericWork/3x816m604"
-  #   Sipity::Entity.where(proxy_for_global_id: work_global_id).first
+  #   Sipity::Entity(work)
   #   => #<Sipity::Entity id: 1, proxy_for_global_id: "gid://whatever/GenericWork/3x816m604",
   # workflow_id: 8, workflow_state_id: 20, created_at: "2017-07-07 13:39:42", updated_at: "2017-07-07 13:39:42">
+  #
+  # @see https://github.com/rails/globalid Rails' GlobalID library
   class Entity < ActiveRecord::Base
     self.table_name = 'sipity_entities'
 
@@ -35,6 +55,8 @@ module Sipity
     # Defines the method #workflow_name
     delegate :name, to: :workflow, prefix: :workflow
 
+    ##
+    # @return [Object] the thing this +Entity+ represents.
     def proxy_for
       @proxy_for ||= GlobalID::Locator.locate(proxy_for_global_id)
     end

data/app/models/sipity/workflow.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 module Sipity
+  ##
   # A named workflow for processing an entity. Originally I had thought of
   # calling this a Type, but once I extracted the Processing submodule,
   # type felt to much of a noun, not conveying potentiality. Workflow

data/app/models/sipity.rb

@@ -1,6 +1,44 @@
 # frozen_string_literal: true
 
+##
+# {Sipity} is a workflow/state engine.
+#
+# This module and the classes namespaced within it provide a domain model and
+# implementation for managing the movement of repository objects through a
+# defined workflow. The workflows themselves are configured using JSON documents
+# and loaded into the database/domain model as {Sipity::Workflow}. Each workflow
+# can be understood as finite sets of {Sipity::WorkflowState},
+# {Sipity::WorkflowAction} (transitions from state to state), and {Sipity::Role}
+# authorized to carry out each action.
+#
+# Any uniquely identifiable object can be managed by a {Sipity::Workflow}.
+# Normally Hyrax uses workflows to handle the deposit process and maintenance
+# lifecycle of repository objects at the level of the Work (within the Hydra
+# Works model). Objects are represented within the Sipity engine's domain model
+# by a {Sipity::Entity}. Each object has at most one {Sipity::Entity}, is
+# governed by one {Sipity::Workflow}, and in one {Sipity::WorkflowState} at any
+# given time.
+#
+# Some use cases for Sipity workflows include:
+#
+# * Simple unmediated deposit with on-deposit notifications and actions;
+# * Mediated deposit with one or more review steps;
+# * Publication workflows requiring multiple levels of editorial approval
+#   and/or peer review;
+# * Preservation processes involving post-deposit selection of objects for
+#   replication to external preservation platforms and/or required action
+#   in case of failed fixity checks;
+# * Electronic Thesis & Dissertation submission processes involving (e.g.)
+#   student deposit, committee and/or departmental approval, centralized/
+#   graduate school review, and a final graduation step.
+#
 module Sipity
+  ##
+  # Cast a given input (e.g. a +::User+ or {Hyrax::Group} to a {Sipity::Agent}).
+  #
+  # @param input [Object]
+  #
+  # @return [Sipity::Agent]
   def Agent(input, &block) # rubocop:disable Naming/MethodName
     result = case input
              when Sipity::Agent
@@ -13,6 +51,10 @@ module Sipity
 
   ##
   # Cast an object to an Entity
+  #
+  # @param input [Object]
+  #
+  # @return [Sipity::Entity]
   # rubocop:disable Naming/MethodName, Metrics/CyclomaticComplexity, Metrics/MethodLength
   def Entity(input, &block)
     result = case input

data/app/presenters/hyrax/admin_set_options_presenter.rb

@@ -59,16 +59,8 @@ module Hyrax
       # > remove files from a work, and add new works to the set.
       return true if @current_ability.can?(:manage, permission_template)
 
-      # Otherwise, we check if the workflow was setup, active, and
-      # allows_access_grants.
-      wf = workflow(permission_template: permission_template)
-      return false unless wf
-      wf.allows_access_grant?
-    end
-
-    def workflow(permission_template:)
-      return unless permission_template.active_workflow
-      Sipity::Workflow.find_by!(id: permission_template.active_workflow.id)
+      # Otherwise, we check if the active workflow allows access grants
+      !!permission_template.active_workflow&.allows_access_grant?
     end
   end
 end

data/app/presenters/hyrax/admin_set_presenter.rb

@@ -12,7 +12,11 @@ module Hyrax
     end
 
     def total_viewable_items
-      ActiveFedora::Base.where("isPartOf_ssim:#{id}").accessible_by(current_ability).count
+      field_pairs = { "isPartOf_ssim" => id.to_s }
+      SolrQueryService.new
+                      .with_field_pairs(field_pairs: field_pairs)
+                      .accessible_by(ability: current_ability)
+                      .count
     end
 
     # AdminSet cannot be deleted if default set or non-empty

data/app/presenters/hyrax/admin_set_selection_presenter.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+module Hyrax
+  ##
+  # @api public
+  # @since 3.1.0
+  #
+  # Presents select options for admin sets.
+  #
+  # Each entry in the {#select_options} return value provides a label for
+  # display, an id to serve as the value, and a data hash which is used as HTML5
+  # data entries. The data entries can be used as hooks for Javascript
+  # to control input validation taking into account the Admin Set and
+  # `PermissionTemplate` rules (`visibility_component.es6` does this, for
+  # example).
+  #
+  # @note this supersedes the older +Hyrax::AdminSetOptionsPresenter+, which
+  #   actied more like a "service" sending database queries to Solr and
+  #   ActiveRecord.  this version seeks only to present the input data and
+  #   relies on its caller to pass in the right data.
+  class AdminSetSelectionPresenter
+    ##
+    # @param [Array<#id>]
+    def initialize(admin_sets:)
+      @admin_sets = admin_sets
+    end
+
+    ##
+    # @return [Array<Array<String, String, Hash>>] an array suitable for  a form
+    #   input `collection:` parameter. it should contain a label, an id, and a
+    #   hash of HTML5  data attributes.
+    def select_options
+      @admin_sets.map do |admin_set|
+        case admin_set
+        when OptionsEntry
+          admin_set.result
+        else
+          OptionsEntry.new(admin_set: admin_set).result
+        end
+      end
+    end
+
+    ##
+    # @api public
+    class OptionsEntry
+      ##
+      # @!attribute [rw] admin_set
+      #   @return [AdministrativeSet, SolrDocument]
+      # @!attribute [rw] permission_template
+      #   @return [PermissionTemplate]
+      # @!attribute [rw] permit_sharing
+      #   @return [Boolean]
+      attr_accessor :admin_set, :permission_template, :permit_sharing
+
+      ##
+      # @param [AdministrativeSet, SolrDocument] admin_set
+      # @param [PermissionTemplate] permission_template
+      # @param [Boolean] permit_sharing
+      def initialize(admin_set:, permission_template: nil, permit_sharing: false)
+        @admin_set = admin_set
+        @permission_template = permission_template
+        @permit_sharing = permit_sharing
+      end
+
+      ##
+      # @return [Array<String, String, Hash>]
+      def result
+        [label, id, data]
+      end
+
+      ##
+      # @return [String]
+      def label
+        Array(admin_set.title).first || admin_set.to_s
+      end
+
+      ##
+      # @return [String]
+      def id
+        admin_set.id.to_s
+      end
+
+      ##
+      # @return [Hash{String => Object}]
+      def data
+        {}.tap do |data|
+          data['data-sharing'] = permit_sharing
+
+          if permission_template
+            data.merge!(data_for(permission_template))
+          else
+            data['data-release-no-delay'] = true
+          end
+        end
+      end
+
+      private
+
+      ##
+      # @api private
+      def data_for(template)
+        {}.tap do |data|
+          if template.release_no_delay?
+            data['data-release-no-delay'] = true
+          elsif template.release_date.present?
+            data['data-release-date'] = template.release_date
+          end
+
+          data['data-release-before-date'] = true if
+            template.release_before_date?
+          data['data-visibility'] = template.visibility if
+            template.visibility.present?
+        end
+      end
+    end
+  end
+end