cogitate 0.0.1 → 0.0.2

data/lib/cogitate/models.rb

@@ -0,0 +1,6 @@
+module Cogitate
+  # The data structure and model definitions of Cogitate objects.
+  # Found within this module are models that are shared concepts between Client and Server.
+  module Models
+  end
+end

data/lib/cogitate/models/agent.rb

@@ -0,0 +1,143 @@
+require 'cogitate/interfaces'
+require 'cogitate/client'
+require 'cogitate/models/identifier'
+require 'base64'
+
+module Cogitate
+  module Models
+    # @api public
+    #
+    # An Agent is a "bucket" of attributes. It represents a single acting entity:
+    #
+    # * a Person - the human clacking away at the keyboard requesting things
+    # * a Service - an application that "does stuff" to data
+    #
+    # @todo Consider adding #to_token so that an Agent can fulfill the AgentWithToken interface
+    class Agent
+      # @api public
+      def self.build_with_identifying_information(strategy:, identifying_value:, **keywords, &block)
+        identifier = Cogitate::Models::Identifier.new(strategy: strategy, identifying_value: identifying_value)
+        new(identifier: identifier, **keywords, &block)
+      end
+
+      # @api public
+      def self.build_with_encoded_id(encoded_identifier:)
+        strategy, identifying_value = Cogitate::Client.extract_strategy_and_identifying_value(encoded_identifier)
+        build_with_identifying_information(strategy: strategy, identifying_value: identifying_value)
+      end
+
+      include Contracts
+      Contract(
+        Contracts::KeywordArgs[identifier: Cogitate::Interfaces::IdentifierInterface], Contracts::Any =>
+        Cogitate::Interfaces::AgentInterface
+      )
+      # @note I'm choosing the :identifier as the input and :primary_identifier as the attribute. I believe it is possible that during the
+      #       process that builds the Agent, I may encounter a more applicable primary_identifier.
+      def initialize(identifier:, container: default_container, serializer_builder: default_serializer_builder)
+        self.identifiers = container.new
+        self.verified_identifiers = container.new
+        self.primary_identifier = identifier
+        self.serializer = serializer_builder.call(agent: self)
+        self.emails = container.new
+        yield(self) if block_given?
+        self
+      end
+
+      Contract(Cogitate::Interfaces::IdentifierInterface => Cogitate::Interfaces::IdentifierInterface)
+      # @api public
+      #
+      # Add an identifier to the agent.
+      #
+      # @param identifier [Cogitate::Interfaces::IdentifierInterface]
+      # @return [Cogitate::Interfaces::IdentifierInterface]
+      def add_identifier(identifier)
+        identifiers << identifier
+        identifier
+      end
+
+      # @api public
+      # @return [Enumerator, nil] nil if a block is given else an Enumerator
+      def with_identifiers
+        return enum_for(:with_identifiers) unless block_given?
+        identifiers.each { |identifier| yield(identifier) }
+        nil
+      end
+
+      Contract(Cogitate::Interfaces::IdentifierInterface => Cogitate::Interfaces::IdentifierInterface)
+      # @api public
+      #
+      # Add a verified identifier to the agent.
+      #
+      # @param identifier [Cogitate::Interfaces::IdentifierInterface]
+      # @return [Cogitate::Interfaces::IdentifierInterface]
+      def add_verified_identifier(identifier)
+        verified_identifiers << identifier
+        identifier
+      end
+
+      # @api public
+      # @return [Enumerator, nil] nil if a block is given else an Enumerator
+      def with_verified_identifiers
+        return enum_for(:with_verified_identifiers) unless block_given?
+        verified_identifiers.each { |identifier| yield(identifier) }
+        nil
+      end
+
+      # @api private
+      # I am not yet set on this method being part of the public API.
+      def add_email(input)
+        emails << input
+      end
+
+      # @api public
+      # @return [Enumerator, nil] nil if a block is given else an Enumerator
+      def with_emails
+        return enum_for(:with_emails) unless block_given?
+        emails.each { |email| yield(email) }
+        nil
+      end
+
+      # @return [Cogitate::Interfaces::IdentifierInterface] What has been assigned as the primary identifier of this agent.
+      attr_reader :primary_identifier
+
+      extend Forwardable
+      def_delegators :primary_identifier, *Cogitate::Models::Identifier.interface_method_names
+      def_delegators :serializer, :as_json
+
+      # Consider the scenario in which a student assigns a faculty member (via an email address) as a collaborating
+      # researcher. That faculty member should have permission to collaborate on the student's work. The permissions
+      # are stored as the Faculty's email. Then the Faculty authenticates with a NetID (a canonical identifier for the
+      # institution that stood up this Cogitate instance) and associates the NetID with their email address.
+      #
+      # At that point we want to allow objects associated with both the NetID and connected email to be available to
+      # the faculty.
+      #
+      # @api public
+      # @return [Array] of ids for each of the verified identifiers
+      def ids
+        [id] + with_verified_identifiers.map(&:id)
+      end
+
+      private
+
+      attr_accessor :identifiers
+      attr_accessor :verified_identifiers
+      attr_accessor :emails
+
+      Contract(Cogitate::Interfaces::IdentifierInterface => Contracts::Any)
+      attr_writer :primary_identifier
+
+      def default_container
+        require 'set' unless defined?(Set)
+        Set
+      end
+
+      attr_accessor :serializer
+      # @todo This is something that needs greater consideration. Is it applicable for both client and server?
+      def default_serializer_builder
+        require 'cogitate/models/agent/serializer' unless defined?(Cogitate::Models::Agent::Serializer)
+        Cogitate::Models::Agent::Serializer.method(:new)
+      end
+    end
+  end
+end

data/lib/cogitate/models/agent/serializer.rb

@@ -0,0 +1,75 @@
+require 'figaro'
+require 'set'
+require 'cogitate/models/agent'
+
+module Cogitate
+  module Models
+    class Agent
+      # Responsible for the serialization of an Agent
+      class Serializer
+        # @api public
+        def initialize(agent:)
+          self.agent = agent
+        end
+
+        private
+
+        attr_accessor :agent
+
+        public
+
+        def as_json(*)
+          prepare_relationships_and_inclusions!
+          {
+            'type' => JSON_API_TYPE, 'id' => agent.encoded_id,
+            'links' => { 'self' => "#{url_for_identifier(agent.encoded_id)}" },
+            'attributes' => { 'strategy' => agent.strategy, 'identifying_value' => agent.identifying_value, 'emails' => emails_as_json },
+            'relationships' => { 'identifiers' => identities_as_json, 'verified_identifiers' => verified_identities_as_json },
+            'included' => included_objects_as_json
+          }
+        end
+
+        private
+
+        JSON_API_TYPE = 'agents'.freeze
+        def type
+          JSON_API_TYPE
+        end
+
+        def emails_as_json
+          agent.with_emails.each_with_object([]) do |email, mem|
+            mem << email
+          end
+        end
+
+        # @note This method is rather complicated but it reduces the number of times we iterate
+        #       through each of the Enumerators.
+        def prepare_relationships_and_inclusions!
+          included_objects_as_json = Set.new
+          identities_as_json = Set.new
+          verified_identities_as_json = Set.new
+
+          agent.with_identifiers do |identifier|
+            identities_as_json << { 'type' => 'identifiers', 'id' => identifier.encoded_id }
+            included_objects_as_json << { 'type' => 'identifiers', 'id' => identifier.encoded_id, 'attributes' => identifier.as_json }
+          end
+
+          agent.with_verified_identifiers do |identifier|
+            verified_identities_as_json << { 'type' => 'identifiers', 'id' => identifier.encoded_id }
+            included_objects_as_json << { 'type' => 'identifiers', 'id' => identifier.encoded_id, 'attributes' => identifier.as_json }
+          end
+
+          @included_objects_as_json = included_objects_as_json.to_a
+          @identities_as_json = identities_as_json.to_a
+          @verified_identities_as_json = verified_identities_as_json.to_a
+        end
+
+        attr_reader :included_objects_as_json, :identities_as_json, :verified_identities_as_json
+
+        def url_for_identifier(encoded_identifier)
+          "#{Figaro.env.protocol}://#{Figaro.env.domain_name}/api/agents/#{encoded_identifier}"
+        end
+      end
+    end
+  end
+end

data/lib/cogitate/models/agent/with_token.rb

@@ -0,0 +1,29 @@
+require 'cogitate/interfaces'
+
+module Cogitate
+  module Models
+    class Agent
+      # A parameter style class that can be sent to the client of Cogitate.
+      #
+      # The token, if decoded and parsed will be the given agent. Likewise the agent, if encoded would be the given token.
+      class WithToken < SimpleDelegator
+        include Contracts
+        Contract(KeywordArgs[agent: Cogitate::Interfaces::AgentInterface, token: String] => Any)
+        def initialize(agent:, token:)
+          self.token = token
+          self.agent = agent
+          super(agent)
+        end
+
+        private
+
+        attr_accessor :agent, :token
+
+        public
+
+        alias_method :to_token, :token
+        public :to_token
+      end
+    end
+  end
+end

data/lib/cogitate/models/identifier.rb

@@ -0,0 +1,114 @@
+require 'contracts'
+require 'cogitate/interfaces'
+require 'base64'
+
+module Cogitate
+  module Models
+    # @api public
+    #
+    # A parameter object that defines how we go from decoding identifiers to extracting an identity.
+    class Identifier
+      INTERFACE_METHOD_NAMES = [:identifying_value, :<=>, :encoded_id, :id, :strategy, :name].freeze
+      def self.interface_method_names
+        INTERFACE_METHOD_NAMES
+      end
+
+      GROUP_STRATEGY_NAME = 'group'.freeze
+      include Contracts
+
+      # @api public
+      #
+      # There are implicit groups that exist and are associated with a given strategy.
+      # This method exists to create a consistent group name.
+      #
+      # @param strategy [String] What is the scope of this identifier (i.e. a Netid, email)
+      # @return [Cogitate::Models::Identifier]
+      def self.new_for_implicit_verified_group_by_strategy(strategy:)
+        new(strategy: GROUP_STRATEGY_NAME, identifying_value: %(All Verified "#{strategy.to_s.downcase}" Users))
+      end
+
+      Contract(Cogitate::Interfaces::IdentifierInitializationInterface => Cogitate::Interfaces::IdentifierInterface)
+      # @api public
+      #
+      # Initialize a value object for identification
+      #
+      # @param strategy [String] What is the scope of this identifier (i.e. a Netid, email)
+      # @param identifying_value [String] What is the value of this identifier (i.e. hello@test.com)
+      def initialize(strategy:, identifying_value:)
+        self.strategy = strategy
+        self.identifying_value = identifying_value
+        self
+      end
+
+      # @api public
+      #
+      # Provides context for the `identifying_value`
+      #
+      # @example 'netid', 'orcid', 'email', 'twitter' are all potential strategies
+      #
+      # @return [String] one of the contexts for identity of this object
+      # @see #<=>
+      attr_reader :strategy
+
+      # @api public
+      #
+      # For the given `strategy` what is the (hopefully) unique value that can be used for identification?
+      #
+      # @example
+      #   Given a `strategy` of "email", examples of identifying values are:
+      #   * hello@world.com
+      #   * test@test.com
+      #
+      #   It is also possible that someone might say 'taco' is an identifying value for the email strategy.
+      #   And that is fine.
+      #
+      # @return [String] one of the contexts for identity of this object
+      # @see #<=>
+      attr_reader :identifying_value
+
+      alias_method :name, :identifying_value
+
+      # The JSON representation of this object
+      #
+      # @return [Hash]
+      def as_json(*)
+        { 'identifying_value' => identifying_value, 'strategy' => strategy }
+      end
+
+      include Comparable
+
+      Contract(Cogitate::Interfaces::IdentifierInterface => Contracts::Num)
+      # @api public
+      #
+      # Provide a means of sorting.
+      #
+      # @return [Integer] -1, 0, 1 as per `Comparable#<=>` interface
+      def <=>(other)
+        strategy_sort = strategy <=> other.strategy
+        return strategy_sort if strategy_sort != 0
+        identifying_value <=> other.identifying_value
+      end
+
+      # @api public
+      #
+      # A URL safe encoding of this object's `strategy` and `identifying_value`
+      #
+      # @return [String] a URL safe encoding of the object's identifying attributes
+      def encoded_id
+        Base64.urlsafe_encode64("#{strategy}\t#{identifying_value}")
+      end
+
+      alias_method :id, :encoded_id
+
+      private
+
+      # @api private
+      attr_writer :identifying_value
+
+      # @api private
+      def strategy=(value)
+        @strategy = value.to_s.downcase
+      end
+    end
+  end
+end

data/lib/cogitate/models/identifiers.rb

@@ -0,0 +1,7 @@
+module Cogitate
+  module Models
+    # Establishing namespace
+    module Identifiers
+    end
+  end
+end

data/lib/cogitate/models/identifiers/with_attribute_hash.rb

@@ -0,0 +1,44 @@
+require 'cogitate/interfaces'
+require 'cogitate/models/identifier'
+module Cogitate
+  module Models
+    module Identifiers
+      # Responsible for exposing
+      class WithAttributeHash
+        include Contracts
+        Contract(
+          Contracts::KeywordArgs[identifier: ::Cogitate::Interfaces::IdentifierInterface, attributes: Contracts::HashOf[String, Any]] =>
+          Contracts::Any
+        )
+        def initialize(identifier:, attributes: {})
+          self.identifier = identifier
+          self.attributes = attributes
+          self.attributes.freeze
+        end
+
+        def as_json(*)
+          { 'strategy' => strategy, 'identifying_value' => identifying_value }.merge(attributes)
+        end
+
+        extend Forwardable
+        include Comparable
+        def_delegators :identifier, *Cogitate::Models::Identifier.interface_method_names
+
+        attr_reader :attributes
+
+        private
+
+        attr_accessor :identifier
+        attr_writer :attributes
+
+        def method_missing(method_name, *args, &block)
+          attributes.fetch(method_name.to_s) { super }
+        end
+
+        def respond_to_missing?(method_name, *args)
+          attributes.key?(method_name.to_s) || super
+        end
+      end
+    end
+  end
+end

data/lib/cogitate/railtie.rb

@@ -0,0 +1,8 @@
+module Cogitate
+  # :nodoc:
+  class Railtie < Rails::Railtie
+    generators do
+      require 'cogitate/generators/install_generator'
+    end
+  end
+end

data/lib/cogitate/services/identifiers_decoder.rb

@@ -0,0 +1,61 @@
+require 'base64'
+require 'contracts'
+require 'cogitate/interfaces'
+require 'cogitate/exceptions'
+require 'cogitate/client'
+
+module Cogitate
+  module Services
+    # A service module for extracting identifiers from an encoded payload.
+    #
+    # @example
+    #
+    #   encoded_string = Base64.urlsafe_encode64("netid\tmynetid")
+    #
+    #
+    # @see Cogitate::Services::IdentifieresDecoder.call
+    module IdentifiersDecoder
+      # Responsible for decoding a string into a collection of identifier types and identifier ids
+      #
+      # @param encoded_string [#to_s] The thing we are going to decode
+      # @return [Array[Hash]]
+      # @raise InvalidIdentifierFormat
+      # @raise InvalidIdentifierEncoding
+      #
+      # @api public
+      # @note I have chosen to not use a keyword, as I don't want to imply the "form" of object is that is being passed in.
+      # @todo Determine if we should return an Array of hashes or if it should be a more proper class?
+      extend Contracts
+      Contract(
+        String, { Contracts::KeywordArgs[identifier_builder: Contracts::Func[Cogitate::Interfaces::IdentifierBuilderInterface]] =>
+        Contracts::ArrayOf[Cogitate::Interfaces::IdentifierInterface] }
+      )
+      def self.call(encoded_string, identifier_builder: default_identifier_builder)
+        decoded_string = decode(encoded_string)
+
+        decoded_string.split("\n").each_with_object([]) do |strategy_value, object|
+          strategy, value = strategy_value.split("\t")
+          if strategy.to_s.size == 0 || value.to_s.size == 0
+            fail Cogitate::InvalidIdentifierFormat, decoded_string: decoded_string
+          end
+          object << identifier_builder.call(strategy: strategy, identifying_value: value)
+        end
+      end
+
+      # @api private
+      def self.decode(encoded_string)
+        Base64.urlsafe_decode64(encoded_string.to_s)
+      rescue ArgumentError
+        raise Cogitate::InvalidIdentifierEncoding, encoded_string: encoded_string
+      end
+      private_class_method :decode
+
+      # @api private
+      def self.default_identifier_builder
+        require "cogitate/models/identifier" unless defined?(Cogitate::Models::Identifier)
+        Cogitate::Models::Identifier.method(:new)
+      end
+      private_class_method :default_identifier_builder
+    end
+  end
+end