ddr-models 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa6eae9dd6e0e539d9222616a396ef3afd4649b5
-  data.tar.gz: f230b44dd2e80024d794d64c7aa93591de3ee6c3
+  metadata.gz: d4fe3945441c76c106744f6dde305b6e5fa58982
+  data.tar.gz: 8f356b6a8e1b21cb39baf12b4f567341d898ca86
 SHA512:
-  metadata.gz: 1fa22e05dd3d8c2344427f2ed275d0925fb8c4b0c31c78f24896c87e41baefb8934a18a282a6597d722585b4feed816c88f0495dbd1ee32530ad8baa1568b0bf
-  data.tar.gz: 5dc8ac9503b41570eee38251cc9859e81318387e15d9139fbd01cb7e7ffbdffdba47942c4bbe8e49fb030c90691bfda4e2576e411ac338653d91b04179be06ae
+  metadata.gz: 7b8d700036e95792c35bea91de5e963c56065665f50a32e507c7a323440f247febc6ef5d0973d671788de6f4a8db412669522c1c63592c503d98efff09d8eae3
+  data.tar.gz: e3cbe827d83386857783a5118c0d02112e0ae29b68dd7b31ad2246860514e7da4e27f9dfd5a716e53fa7b5522d50a10b54a50e4d28202115e98be35a7a8c6087

data/README.md

@@ -1,6 +1,6 @@
 # ddr-models
 
-[![Build Status](https://travis-ci.org/duke-libraries/ddr-models.svg?branch=develop)](https://travis-ci.org/duke-libraries/ddr-models)
+[![Build Status](https://travis-ci.org/duke-libraries/ddr-models.svg?branch=master)](https://travis-ci.org/duke-libraries/ddr-models)
 [![Gem Version](https://badge.fury.io/rb/ddr-models.svg)](http://badge.fury.io/rb/ddr-models)
 
 A Rails engine providing Hydra and ActiveRecord models and common services for the Duke Digital Repository.
@@ -15,5 +15,79 @@ and
 
     bundle install
 
+## Configuration
 
+ddr-models has several runtime dependencies that are independently configurable:
 
+- [active_fedora](https://github.com/projecthydra/active_fedora)
+- [hydra-head](https://github.com/projecthydra/hydra-head)
+- [ddr-antivirus](https://github.com/duke-libraries/ddr-antivirus)
+- [devise-remote-user](https://github.com/duke-libraries/devise-remote-user)
+
+ddr-models configuration options:
+
+- Authentication/Authorization options are set on [Ddr::Auth](http://www.rubydoc.info/gems/ddr-models/Ddr/Auth).
+
+### Additional configuration steps
+
+#### User model
+
+Include `Ddr::Auth::User` in `app/models/user.rb` and remove content inserted by Hydra, Blacklight and Devise generators:
+
+```ruby
+class User
+  include Ddr::Auth::User
+  #
+  # Remove content inserted by Hydra, Blacklight, or Devise generators --
+  # it's provided by Ddr::Auth::User.
+  #
+  # include Blacklight::User
+  # include Hydra::User
+  # devise :database_authenticatable [...]
+  #
+  # ... as well as any methods.
+  #
+  # You can add custom methods for the app as needed.
+  #
+end
+```
+
+#### Ability class
+
+The hydra-head generator may have created a class module at `app/models/ability.rb` like so:
+
+```ruby
+class Ability
+  include Hydra::Ability
+end
+```
+
+Change the class like so:
+
+```ruby
+class Ability < Ddr::Auth::Ability
+  #
+  # Ddr::Auth::Ability includes Hydra::PolicyAwareAbility
+  # include Hydra::Ability
+  #
+  # Add custom methods here as needed to Ability.ability_logic:
+  #
+  # self.ability_logic += [:my_ability]
+  #
+  # def my_ability
+  #   # whatever
+  # end
+  #
+end
+```
+
+#### Migrations
+
+Install the ddr-models migrations:
+
+    rake ddr_models:install:migrations
+    
+then
+
+    rake db:migrate db:test:prepare
+    

data/app/models/attachment.rb

@@ -1,7 +1,12 @@
+#
+# An Attachment is a miscellaneous content-bearing resource associated with a Collection.
+#
+# Example: A collection digitization QC information spreadsheet.
+#
 class Attachment < Ddr::Models::Base
 
   include Ddr::Models::HasContent
   
   belongs_to :attached_to, property: :is_attached_to, class_name: 'ActiveFedora::Base'
   
-end
+end

data/app/models/collection.rb

@@ -1,3 +1,9 @@
+#
+# A Collection is a conceptual and administrative entity containing a set of items. 
+#
+# Provides default permissions (Hydra admin policy) for objects associated with the collection 
+# via an isGovernedBy relation.
+#
 class Collection < Ddr::Models::Base
   
   include Hydra::AdminPolicyBehavior
@@ -17,6 +23,9 @@ class Collection < Ddr::Models::Base
   
   validates_presence_of :title
   
+  # Returns the SolrDocuments for Components associated with the Collection through its member Items.
+  #
+  # @return A lazy enumerator of SolrDocuments.
   def components_from_solr
     outer = Ddr::IndexFields::IS_PART_OF
     inner = Ddr::IndexFields::INTERNAL_URI
@@ -27,20 +36,29 @@ class Collection < Ddr::Models::Base
     results.lazy.map {|doc| SolrDocument.new(doc)}
   end
   
+  # Returns the license attributes provided as default values for objects governed by the Collection.
+  #
+  # @return [Hash] the attributes, `:title`, `:description`, and `:url`.
   def default_license
     if default_license_title.present? or default_license_description.present? or default_license_url.present?
       {title: default_license_title, description: default_license_description, url: default_license_url}
     end
   end
   
+  # Sets the default license attributes for objects governed by the Collection.
   def default_license=(new_license)
-    raise ArgumentError unless new_license.is_a?(Hash)
+    raise ArgumentError unless new_license.is_a?(Hash) # XXX don't do this - not duck-typeable
     l = new_license.with_indifferent_access
     self.default_license_title = l[:title]
     self.default_license_description = l[:description]
     self.default_license_url = l[:url]
   end
   
+  # Returns a list of entities (either users or groups) having a default access level on objects governed by the Collection.
+  # 
+  # @param type [String] the type of entity, "user" or "group".
+  # @param access [String] the default access level, "discover", "read", or "edit".
+  # @return [Array<String>] the entities (users or groups)
   def default_entities_for_permission(type, access)
     default_permissions.collect { |p| p[:name] if p[:type] == type and p[:access] == access }.compact
   end

data/app/models/component.rb

@@ -1,3 +1,8 @@
+#
+# A Component is a part of an Item; the principal content-bearing repository resource.
+#
+# Examples: Page of a book, track of a recording, etc.
+#
 class Component < Ddr::Models::Base
  
   include Ddr::Models::HasContent
@@ -12,4 +17,4 @@ class Component < Ddr::Models::Base
     self.parent.parent rescue nil
   end
 
-end
+end

data/app/models/item.rb

@@ -1,3 +1,8 @@
+# 
+# An Item is a  member of a Collection -- i.e., a "work" -- the principal describable resource.
+#
+# Examples: photograph, book, article, sound recording, video, etc.
+#
 class Item < Ddr::Models::Base
   
   include Ddr::Models::HasContentMetadata
@@ -16,4 +21,4 @@ class Item < Ddr::Models::Base
   alias_method :collection_id, :parent_id
   alias_method :collection=, :parent=
     
-end
+end

data/app/models/solr_document.rb

@@ -1,4 +1,7 @@
 # -*- encoding : utf-8 -*-
+#
+# A SolrDocument is a wrapper of a raw Solr document result.
+#
 class SolrDocument 
 
   include Blacklight::Solr::Document

data/app/models/target.rb

@@ -1,3 +1,10 @@
+#
+# A Target is digital scanner calibration artifact.
+#
+# A Target has a content file and is associated with a Collection OR one or more Components.
+#
+# See http://www.loc.gov/standards/mix/ and NISO Z39.87.
+#
 class Target < Ddr::Models::Base
 
   include Ddr::Models::HasContent
@@ -5,4 +12,4 @@ class Target < Ddr::Models::Base
   has_many :components, property: :has_external_target, class_name: 'Component'
   belongs_to :collection, property: :is_external_target_for, class_name: 'Collection'
 
-end
+end

data/config/initializers/devise.rb~

@@ -0,0 +1,245 @@
+require 'devise'
+
+# Use this hook to configure devise mailer, warden hooks and so forth.
+# Many of these configuration options can be set straight in your model.
+Devise.setup do |config|
+
+  # Given the modules that we implement, this shouldn't be used, but Devise >= 3.1 requires it,
+  # so a random value should suffice.
+  config.secret_key = SecureRandom.hex(64)
+
+  # ==> Mailer Configuration
+  # Configure the e-mail address which will be shown in Devise::Mailer,
+  # note that it will be overwritten if you use your own mailer class with default "from" parameter.
+  config.mailer_sender = "lib-drs@duke.edu"
+
+  # Configure the class responsible to send e-mails.
+  # config.mailer = "Devise::Mailer"
+
+  # ==> ORM configuration
+  # Load and configure the ORM. Supports :active_record (default) and
+  # :mongoid (bson_ext recommended) by default. Other ORMs may be
+  # available as additional gems.
+  require 'devise/orm/active_record'
+
+  # ==> Configuration for any authentication mechanism
+  # Configure which keys are used when authenticating a user. The default is
+  # just :email. You can configure it to use [:username, :subdomain], so for
+  # authenticating a user, both parameters are required. Remember that those
+  # parameters are used only when authenticating and not when retrieving from
+  # session. If you need permissions, you should implement that in a before filter.
+  # You can also supply a hash where the value is a boolean determining whether
+  # or not authentication should be aborted when the value is not present.
+  config.authentication_keys = [ :username ]
+
+  # Configure parameters from the request object used for authentication. Each entry
+  # given should be a request method and it will automatically be passed to the
+  # find_for_authentication method and considered in your model lookup. For instance,
+  # if you set :request_keys to [:subdomain], :subdomain will be used on authentication.
+  # The same considerations mentioned for authentication_keys also apply to request_keys.
+  # config.request_keys = []
+
+  # Configure which authentication keys should be case-insensitive.
+  # These keys will be downcased upon creating or modifying a user and when used
+  # to authenticate or find a user. Default is :email.
+  config.case_insensitive_keys = [ :username ]
+
+  # Configure which authentication keys should have whitespace stripped.
+  # These keys will have whitespace before and after removed upon creating or
+  # modifying a user and when used to authenticate or find a user. Default is :email.
+  config.strip_whitespace_keys = [ :username ]
+
+  # Tell if authentication through request.params is enabled. True by default.
+  # It can be set to an array that will enable params authentication only for the
+  # given strategies, for example, `config.params_authenticatable = [:database]` will
+  # enable it only for database (email + password) authentication.
+  config.params_authenticatable = [:database]
+
+  # Tell if authentication through HTTP Basic Auth is enabled. False by default.
+  # It can be set to an array that will enable http authentication only for the
+  # given strategies, for example, `config.http_authenticatable = [:token]` will
+  # enable it only for token authentication.
+  # config.http_authenticatable = false
+
+  # If http headers should be returned for AJAX requests. True by default.
+  # config.http_authenticatable_on_xhr = true
+
+  # The realm used in Http Basic Authentication. "Application" by default.
+  # config.http_authentication_realm = "Application"
+
+  # It will change confirmation, password recovery and other workflows
+  # to behave the same regardless if the e-mail provided was right or wrong.
+  # Does not affect registerable.
+  # config.paranoid = true
+
+  # By default Devise will store the user in session. You can skip storage for
+  # :http_auth and :token_auth by adding those symbols to the array below.
+  # Notice that if you are skipping storage for all authentication paths, you
+  # may want to disable generating routes to Devise's sessions controller by
+  # passing :skip => :sessions to `devise_for` in your config/routes.rb
+  config.skip_session_storage = [:http_auth]
+
+  # ==> Configuration for :database_authenticatable
+  # For bcrypt, this is the cost for hashing the password and defaults to 10. If
+  # using other encryptors, it sets how many times you want the password re-encrypted.
+  #
+  # Limiting the stretches to just one in testing will increase the performance of
+  # your test suite dramatically. However, it is STRONGLY RECOMMENDED to not use
+  # a value less than 10 in other environments.
+  config.stretches = Rails.env.test? ? 1 : 10
+
+  # Setup a pepper to generate the encrypted password.
+  # config.pepper = "37669e0c50042b93e63f790c4102864bace2ee0a30eecad6fca7d490f3124d855d8bc6d2978e5500fb266aab2b8c8003d9f202a1f23e4c2c8e8f105b7c46a68f"
+
+  # ==> Configuration for :confirmable
+  # A period that the user is allowed to access the website even without
+  # confirming his account. For instance, if set to 2.days, the user will be
+  # able to access the website for two days without confirming his account,
+  # access will be blocked just in the third day. Default is 0.days, meaning
+  # the user cannot access the website without confirming his account.
+  # config.allow_unconfirmed_access_for = 2.days
+
+  # If true, requires any email changes to be confirmed (exactly the same way as
+  # initial account confirmation) to be applied. Requires additional unconfirmed_email
+  # db field (see migrations). Until confirmed new email is stored in
+  # unconfirmed email column, and copied to email column on successful confirmation.
+  config.reconfirmable = true
+
+  # Defines which key will be used when confirming an account
+  config.confirmation_keys = [ :username ]
+
+  # ==> Configuration for :rememberable
+  # The time the user will be remembered without asking for credentials again.
+  # config.remember_for = 2.weeks
+
+  # If true, extends the user's remember period when remembered via cookie.
+  # config.extend_remember_period = false
+
+  # Options to be passed to the created cookie. For instance, you can set
+  # :secure => true in order to force SSL only cookies.
+  # config.rememberable_options = {}
+
+  # ==> Configuration for :validatable
+  # Range for password length. Default is 6..128.
+  # config.password_length = 6..128
+
+  # Email regex used to validate email formats. It simply asserts that
+  # an one (and only one) @ exists in the given string. This is mainly
+  # to give user feedback and not to assert the e-mail validity.
+  # config.email_regexp = /\A[^@]+@[^@]+\z/
+
+  # ==> Configuration for :timeoutable
+  # The time you want to timeout the user session without activity. After this
+  # time the user will be asked for credentials again. Default is 30 minutes.
+  # config.timeout_in = 30.minutes
+  
+  # If true, expires auth token on session timeout.
+  # config.expire_auth_token_on_timeout = false
+
+  # ==> Configuration for :lockable
+  # Defines which strategy will be used to lock an account.
+  # :failed_attempts = Locks an account after a number of failed attempts to sign in.
+  # :none            = No lock strategy. You should handle locking by yourself.
+  # config.lock_strategy = :failed_attempts
+
+  # Defines which key will be used when locking and unlocking an account
+  config.unlock_keys = [ :username ]
+
+  # Defines which strategy will be used to unlock an account.
+  # :email = Sends an unlock link to the user email
+  # :time  = Re-enables login after a certain amount of time (see :unlock_in below)
+  # :both  = Enables both strategies
+  # :none  = No unlock strategy. You should handle unlocking by yourself.
+  # config.unlock_strategy = :both
+
+  # Number of authentication tries before locking an account if lock_strategy
+  # is failed attempts.
+  # config.maximum_attempts = 20
+
+  # Time interval to unlock the account if :time is enabled as unlock_strategy.
+  # config.unlock_in = 1.hour
+
+  # ==> Configuration for :recoverable
+  #
+  # Defines which key will be used when recovering the password for an account
+  config.reset_password_keys = [ :username ]
+
+  # Time interval you can reset your password with a reset password key.
+  # Don't put a too small interval or your users won't have the time to
+  # change their passwords.
+  config.reset_password_within = 6.hours
+
+  # ==> Configuration for :encryptable
+  # Allow you to use another encryption algorithm besides bcrypt (default). You can use
+  # :sha1, :sha512 or encryptors from others authentication tools as :clearance_sha1,
+  # :authlogic_sha512 (then you should set stretches above to 20 for default behavior)
+  # and :restful_authentication_sha1 (then you should set stretches to 10, and copy
+  # REST_AUTH_SITE_KEY to pepper)
+  # config.encryptor = :sha512
+
+  # ==> Configuration for :token_authenticatable
+  # Defines name of the authentication token params key
+  # config.token_authentication_key = :auth_token
+
+  # ==> Scopes configuration
+  # Turn scoped views on. Before rendering "sessions/new", it will first check for
+  # "users/sessions/new". It's turned off by default because it's slower if you
+  # are using only default views.
+  # config.scoped_views = false
+
+  # Configure the default scope given to Warden. By default it's the first
+  # devise role declared in your routes (usually :user).
+  # config.default_scope = :user
+
+  # Set this configuration to false if you want /users/sign_out to sign out
+  # only the current scope. By default, Devise signs out all scopes.
+  # config.sign_out_all_scopes = true
+
+  # ==> Navigation configuration
+  # Lists the formats that should be treated as navigational. Formats like
+  # :html, should redirect to the sign in page when the user does not have
+  # access, but formats like :xml or :json, should return 401.
+  #
+  # If you have any extra navigational formats, like :iphone or :mobile, you
+  # should add them to the navigational formats lists.
+  #
+  # The "*/*" below is required to match Internet Explorer requests.
+  # config.navigational_formats = ["*/*", :html]
+
+  # The default HTTP method used to sign out a resource. Default is :delete.
+  config.sign_out_via = :get
+
+  # ==> OmniAuth
+  # Add a new OmniAuth provider. Check the wiki for more information on setting
+  # up on your models and hooks.
+  # config.omniauth :github, 'APP_ID', 'APP_SECRET', :scope => 'user,public_repo'
+
+  # ==> Warden configuration
+  # If you want to use other strategies, that are not supported by Devise, or
+  # change the failure app, you can configure them inside the config.warden block.
+  #
+  # config.warden do |manager|
+    # manager.intercept_401 = false
+    # manager.default_strategies(:scope => :user).unshift :remote_user_authenticatable
+  # end
+
+  config.warden do |manager|
+    # :superuser scope
+    manager.serialize_into_session(:superuser) { |superuser| superuser.id }
+    manager.serialize_from_session(:superuser) { |id| User.find(id) }
+  end
+
+  # ==> Mountable engine configurations
+  # When using Devise inside an engine, let's call it `MyEngine`, and this engine
+  # is mountable, there are some extra configurations to be taken into account.
+  # The following options are available, assuming the engine is mounted as:
+  #
+  #     mount MyEngine, at: "/my_engine"
+  #
+  # The router that invoked `devise_for`, in the example above, would be:
+  # config.router_name = :my_engine
+  #
+  # When using omniauth, Devise cannot automatically set Omniauth path,
+  # so you need to do it manually. For the users scope, it would be:
+  # config.omniauth_path_prefix = "/my_engine/users/auth"
+end