hydramata-works 0.0.1.prerelease

data/documents/hydramata-components.md

@@ -0,0 +1,82 @@
+# Hydramata Components
+
+In terms of dependencies, the Work component should happen first.
+Then the Permissions and Workflow components can happen independently.
+
+We can begin working on Permissions and Workflow as the Work component is in process.
+Permissions will be easier to do in isolation whereas Workflow will require greater coordination with the Work component effort.
+
+Once the Work, Permissions, and Workflow components are complete, most other components could proceed.
+
+## Hydramata::Works
+
+A way to suggest the properties and structure of different work types (ie Article, Dataset, etc) while allowing the persisted work to be the authority of its properties.
+
+Responsible for defining how a work is:
+
+* Represented at three different levels (ie Persistence, Application Object, and User Output).
+* Transformed from one level to another (ie Persistence -> Application Object; Application Object -> User Output).
+
+### What pain points is Hydramata::Works addressing?
+
+* Remove duplication of knowledge of a work's data and structure.
+  Presently knowledge of a work's data is in the ActiveFedora model, datastreams, show page, and edit page.
+* Allow institutions to define their own work types.
+* Improve the sharability of components that interact with a well-defined narrow interface for a work.
+* Allow institutions to add new work types without requiring deploys.
+* Allow institutions to modify existing work types without always requiring data migrations.
+* Acknowledge that our understanding of the suggested structure and properties of a work is changing over time, but this shouldn't mandate a migration.
+
+## Hydramata::Permissions
+
+A common interface for application level permissions. That is to say "Can I view this work?" or perhaps more specifically, "When I view this work, what do I see?"
+
+Responsible for defining what an agent interacting with the application can do.
+
+The scope of the permissions system is beyond just works.
+Can this person, because they are a member of these groups take this specific action.
+And the action could be:
+
+* "Show the Resque worker queue."
+* "Masquerade as another user."
+* "Edit a given work."
+
+### What pain points is Hydramata::Permissions addressing?
+
+* Normalize the application permissions (i.e. Repository Manager and System Manager are handled differently from a Work's editor)
+* Expose a well-defined narrow interface for Groups, so that each institution could create an adaptor that suits them.
+* Allow institutions to add new roles to represent a set of abilities (ie a "Librarian" role could edit all AIPs)
+
+## Hydramata::Worksflow
+
+A common processing architecture for running tasks that need not be run within a request cycle.
+
+Responsible for providing a asynchronous processing capabilities.
+This could be ingesting SIPs, sending emails to depositors, running characterizations, and generating derivatives.
+
+### What pain points is Hydramata::Permissions addressing?
+
+* Acknowledging the fragility of deposit when handled within request queue ([See Google Doc](https://docs.google.com/document/d/1AyEFK0PTIt4STFcsNw2x5zeJthP0rRxKX7K0Yv5O_hM/edit)).
+* Acknowledging the transactional challenges of coordinating updates to Fedora and SOLR so as to deliver on the promise of preservation.
+* Teasing apart numerous small tasks that can be run and tested in isolation.
+* Speeding up the responsiveness and scalability of user deposit.
+
+## Hydramata::AdministrativeSet
+
+A conceptual place where Works are put.
+
+As it relates to the Hydramata::Permissions component, the AdministrativeSet is a Resource.
+An AdministrativeSetMembership is also a Resource.
+
+If I want to create a Work, I need to declare which AdministrativeSet I want to put it in.
+"Can I create AdministrativeSetMembership (an Article in this AdministrativeSet)?"
+
+### @TODO
+
+Consider how we persist a Work's AdministrativeSet.
+Is this uneditable?
+Is the attribute shown on the page?
+How to enforce that?
+
+The reification strategy.
+If a property is present but not editable, discard any value associated with the property when we attempt to.

data/documents/interface-between-work-and-permissions.md

@@ -0,0 +1,131 @@
+# DRAFT - Interface between Work and Permissions component - DRAFT
+
+## Initial Interface
+
+For a Work to assert its available predicates, the Permissions subsystem should:
+
+* Provide a `Hydramata::Permissions.roles_for(agent)` service. Responsible for getting all of the roles of an agent.
+* Each of the returned objects from `Hydramata::Permissions.roles_for` should:
+  * have a unique identifying symbol from which the Work subsystem can craft the appropriate Work Reification Strategy (which properties go on the work value object that is being passed through the system).
+
+The Permissions subsystem is concerned with these three concepts:
+
+* Resource - exposes the following methods `#persisted?`, `#to_key`, `#class#model_name` (a subset of the [ActiveModel::Lint::Test](http://api.rubyonrails.org/classes/ActiveModel/Lint/Tests.html))
+* Action - what is the agent trying to do with the resource? This would likely be the Controller#action_name
+* Agent - who (or what) is attempting to take action on the resource
+
+For the Permissions subsystem to interact with a Work, the Work object should implement a Resource interface.
+
+### Searching for Resources
+
+This is a more complicated case. When searching for Works there are two permission checks:
+
+1. "Can I create a Search?" - In other words, can I perform a search?
+1. "Can I show a given Search result?" - In other words, what are the documents returned in the search?
+
+The Permission system is responsible for appending additional restrictions to Search object/query.
+The additional restrictions would modify the Search by in effect adding "AND I can Show" to the search query.
+
+For a search request, we will search across all indexed properties of the solr documents, regardless of permissions.
+When we render a search result document, only properties that the user can access will be available for rendering to the output buffer.
+
+Said another way:
+
+```gherkin
+Feature: I can search amongst properties that I may not be able to access
+  As patron of the library
+  I want to...
+  So that I...
+
+  Scenario:
+    Given an Agent
+    And there exists the following indexed Works:
+      | work_type | properties                        |
+      | Article   | { title: 'Hello', secret: 'Dog' } |
+      | Book      | { title: 'Dog' }                  |
+      | Article   | { title: 'World' }                |
+    And I can accessess the following predicates by Work Type:
+      | work_type | predicates |
+      | Article   | [:title]   |
+      | Book      | [:title]   |
+    When the Agent searches for "Dog"
+    Then they will find two Works with the following properties:
+      | work_type | properties         |
+      | Article   | { title: 'Hello' } |
+      | Book      | { title: 'Dog' }   |
+```
+
+## Initial Scenarios
+
+```gherkin
+Feature: Role-based access to Predicates
+  As the steward of repository content
+  I want to ensure that the appropriate content is available based on the requesting Agent.
+    And that some content is not available.
+  So that I am upholding any institutional policies and protocols regarding content.
+
+  As the Work component is responsible for wrangling the Work from persistence to memory to output buffer,
+  it would be the responsibility of the Work component to negotiate any predicate level access.
+
+  Scenario Outline:
+
+    Given an Agent with role <role>
+    And a Work of work type <work_type> with predicates <predicates>
+    And the role <role> can only access the following predicates <accessible_predicates>
+    When the Agent requests the Work
+    Then the Work asserts that the Agent only accesses the following predicates <accessible_predicates>
+
+    Examples:
+      | role      | work_type | predicates          | accessible_predicates  |
+      | Anonymous | Article   | :identifier, :title | :identifier            |
+      | Librarian | Article   | :identifier, :title | :identifier, :title    |
+      | Librarian | Article   | :identifier, :title | :identifier, :title    |
+```
+
+```gherkin
+Feature: Work object interacting with Permissions
+  As the steward of repository content
+  I want to ensure that the appropriate content is available based on the requesting Agent.
+    And that some content is not available.
+  So that I am upholding any institutional policies and protocols regarding content.
+
+  Scenario Outline:
+
+    Given an Agent with role <role>
+    And a Work of work type <work_type>
+    When the Agent requests the Work
+    Then the Permissions subsystem asserts that the Agent is <access_state> access to the Work.
+
+    Examples:
+      | role      | work_type | access_state |
+      | Anonymous | Article   | not allowed  |
+      | Librarian | Article   | allowed      |
+
+  Scenario:
+
+    Given an Agent with roles:
+      | role      |
+      | Professor |
+      | Librarian |
+    And a Work of work type Article
+    And an Article has the following role-based permissions:
+      | role      | access_state |
+      | Professor | not allowed  |
+      | Librarian | allowed      |
+    When the Agent requests the Work
+    Then the Permissions subsystem asserts that the Agent is allowed access to the Work.
+
+  Scenario:
+
+    Given an Agent with roles:
+      | role      |
+      | Professor |
+      | Librarian |
+    And a Work of work type Article
+    And an Article has the following role-based permissions:
+      | role      | access_state |
+      | Professor | not allowed  |
+      | Librarian | allowed      |
+    When the Agent requests the Work
+    Then the Permissions subsystem asserts that the Agent is allowed access to the Work.
+```

data/documents/interface-between-work-and-workflow.md

@@ -0,0 +1,6 @@
+# DRAFT - Interface between Work and Workflow component - DRAFT
+
+## Initial Interface
+
+
+## Initial Scenarios

data/documents/timeline.md

@@ -0,0 +1,75 @@
+# Proposed Hydramata Timeline
+
+## Work
+
+### Where does this exist in Curate?
+
+Presently the definition of a Work is spread across six major concerns:
+
+* Model - exposes attributes, validations, defines model level indexing strategy
+* Datastream - exposes attributes and indexing strategy
+* Actor - handles input interactions, DOI minting, file uploading
+* Show page - renders attributes
+* Edit page - renders attributes (and values)
+* Index/search result - renders attributes and values
+
+The sequence of rendered attributes is not kept in sync between the different view contexts.
+
+### Replacement Strategy
+
+
+1. Define the narrow public interface for a Work's expected methods and their behavior.
+   This involves providing object linters to verify the API.
+1. Establish application plugin structure.
+1. Data-driven presentation structure for Work Types
+   This addresses the rendering aspect of the Show/New/Edit page.
+1. Splice in a shim for rendering existing Curate work types via data-driven methods
+1. Data-driven predicate definition for Work Types
+   This addresses indexing strategy, validation, and configurablity of work types.
+1. Splice in the Work Wrangler to reify Fedora objects
+1. Splice in WorkActorShim to preserve existing Curate Actor behaviors
+
+## Workflow
+
+### Where does this exist in Curate?
+
+Presently this exists in the Actor and spread across numerous callbacks for Hydra components
+
+* Creating child GenericFiles under a Work
+* Derivatives
+* Remote Identifiers (DOIs)
+* Generate checksums
+* Characterization
+* Assigning a representative image
+* Running anti-virus
+* Establish provenance of attachments
+
+### Replacement Strategy
+
+1. Create or leverage existing Workflow project (i.e. push Heracles over the hump) to implement an asynchronous messaging system.
+1. Create single-focus tasks (i.e. hydramata/works/tasks/generate_derivatives) that behave well within the Workflow subsystems
+1. Replace existing Curate actors with data-driven Workflows.
+   This will obviate the need for the WorkActorShim as the Workflows expect to interact with objects that implement the Work interface.
+
+## Permissions
+
+### Where does this exist in Curate?
+
+This information is spread across:
+
+* Hydra::AccessControls
+* The repository manager YML file
+* The application manager YML file
+
+The concerns are partially merged into CanCan's expected [Ability class](https://github.com/projecthydra-labs/curate/blob/master/app/models/concerns/curate/ability.rb)
+
+The enforcement is spread across controllers and views, leveraging both CanCan queries (i.e. `can?(:edit, @work)`)
+and inline `if current_user.repository_manager?`.
+
+### How to replace these interactions
+
+## Administrative Context
+
+### Where does this exist in Curate?
+
+No where. This is a yet to be defined concept.

data/fs

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+script/fast_specs

data/gemfiles/rails4.1.gemfile

@@ -0,0 +1,12 @@
+source 'http://rubygems.org'
+
+file = File.expand_path("../../Gemfile", __FILE__)
+
+if File.exists?(file)
+  puts "Loading #{file} ..." if $DEBUG # `ruby -d` or `bundle -v`
+  instance_eval File.read(file)
+end
+gem 'sass', '~> 3.2.15'
+gem 'sprockets', '~> 2.11.0'
+
+gem 'rails', '4.1.0'

data/gemfiles/rails4.gemfile

@@ -0,0 +1,13 @@
+source 'http://rubygems.org'
+
+file = File.expand_path("../../Gemfile", __FILE__)
+
+if File.exists?(file)
+  puts "Loading #{file} ..." if $DEBUG # `ruby -d` or `bundle -v`
+  instance_eval File.read(file)
+end
+
+gem 'sass', '~> 3.2.15'
+gem 'sprockets', '~> 2.11.0'
+
+gem 'rails', '4.0.3'

data/hydramata-works.gemspec

@@ -0,0 +1,43 @@
+$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+
+# Maintain your gem's version:
+require 'hydramata/works/version'
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name = 'hydramata-works'
+  s.version     = Hydramata::Works::VERSION
+  s.authors     = [
+    'Jeremy Friesen'
+  ]
+  s.email       = [
+    'jeremy.n.friesen@gmail.com'
+  ]
+  s.homepage    = 'https://github.com/jeremyf/hydramata-work'
+  s.summary     = 'Provide a well defined data-structure to ease the interaction between differing layers of a Hydra application.'
+  s.description = 'Provide a well defined data-structure to ease the interaction between differing layers of a Hydra application.'
+  s.required_ruby_version = '~> 2.0'
+
+  s.license = 'APACHE2'
+
+  s.files         = `git ls-files -z`.split("\x0")
+  s.executables   = s.files.grep(%r{^bin/}) do |f|
+    f == 'bin/rails' ? nil : File.basename(f)
+  end.compact
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ['lib']
+
+  s.add_dependency "rails", "~> 4.0"
+  s.add_dependency 'rdf', '~> 1.1'
+  s.add_dependency 'psych', '~> 2.0.5'
+
+  s.add_development_dependency 'engine_cart', '~> 0.3'
+  s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'rspec-rails', '~> 3.0'
+  s.add_development_dependency 'rspec-html-matchers', '~>0.6'
+  s.add_development_dependency 'sqlite3', '~> 1.3'
+  s.add_development_dependency 'rubydora', '~> 1.7'
+  s.add_development_dependency 'vcr', '~> 2.9'
+  s.add_development_dependency 'webmock', '~> 1.18'
+  s.add_development_dependency 'database_cleaner', '~> 1.3'
+end

data/lib/hydramata-works.rb

@@ -0,0 +1,23 @@
+require 'hydramata/works/engine' if defined?(Rails)
+module Hydramata
+  # Responsible for providing a well defined data-structure to ease the
+  # interaction between differing layers of an application.
+  #
+  # * Persistence Layer
+  # * In Memory
+  # * Rendering/Output Buffer
+  module Works
+    module_function
+    def table_name_prefix
+      'hydramata_works_'
+    end
+
+    # Because I am not using isolate_namespace for Hydramata::Works::Engine
+    # I need this for the application router to find the appropriate routes.
+    # @api private
+    def use_relative_model_naming?
+      true
+    end
+
+  end
+end

data/lib/hydramata/works/conversions.rb

@@ -0,0 +1,21 @@
+require 'hydramata/works/conversions/predicate'
+require 'hydramata/works/conversions/predicate_set'
+require 'hydramata/works/conversions/presented_fieldsets'
+require 'hydramata/works/conversions/presenter'
+require 'hydramata/works/conversions/property'
+require 'hydramata/works/conversions/property_set'
+require 'hydramata/works/conversions/translation_key_fragment'
+require 'hydramata/works/conversions/value'
+require 'hydramata/works/conversions/work_type'
+
+module Hydramata
+  module Works
+    # Taking a que from Avdi Grimm's "Confident Ruby", the Conversion module
+    # is responsible for coercing the inputs to another format.
+    #
+    # This is somewhat experimental, though analogous to the Array() method in
+    # base ruby.
+    module Conversions
+    end
+  end
+end

data/lib/hydramata/works/conversions/exceptions.rb

@@ -0,0 +1,18 @@
+require 'hydramata/works/conversions/exceptions'
+
+module Hydramata
+  module Works
+    # Taking a que from Avdi Grimm's "Confident Ruby", the Conversion module
+    # is responsible for coercing the inputs to another format.
+    #
+    # This is somewhat experimental, though analogous to the Array() method in
+    # base ruby.
+    module Conversions
+      class ConversionError < RuntimeError
+        def initialize(class_name, input)
+          super("Could not convert #{input.inspect} to #{class_name}")
+        end
+      end
+    end
+  end
+end

data/lib/hydramata/works/conversions/predicate.rb

@@ -0,0 +1,22 @@
+require 'hydramata/works/conversions/exceptions'
+require 'hydramata/works/predicate'
+require 'hydramata/works/predicates'
+
+module Hydramata
+  module Works
+    module Conversions
+      private
+      def Predicate(input)
+        return input.to_predicate if input.respond_to?(:to_predicate)
+
+        case input
+        when Predicate then input
+        when String, Symbol then Predicates.find(input)
+        when Hash then Predicates.find(input.fetch(:identity), input)
+        else
+          raise ConversionError.new(:Predicate, input)
+        end
+      end
+    end
+  end
+end