cogitate 0.0.1 → 0.0.2

data/lib/cogitate/client/request.rb

@@ -0,0 +1,56 @@
+require 'active_support/core_ext/array/wrap'
+
+module Cogitate
+  module Client
+    # Request from Cogitate the given identifiers and parse leveraging the custom parser.
+    class Request
+      # @api public
+      def self.call(identifiers:, **keywords)
+        new(identifiers: identifiers, **keywords).call
+      end
+
+      def initialize(identifiers:, response_parser:, configuration: default_configuration)
+        self.identifiers = identifiers
+        self.configuration = configuration
+        self.response_parser = response_parser
+        initialize_urlsafe_base64_encoded_identifiers!
+        initialize_url_for_request!
+      end
+
+      def call
+        response = client_request_handler.call(url: url_for_request)
+        response_parser.call(response: response)
+      end
+
+      private
+
+      extend Forwardable
+      def_delegator :configuration, :client_request_handler
+
+      attr_accessor :response_parser, :configuration
+
+      attr_reader :identifiers, :urlsafe_base64_encoded_identifiers, :url_for_request
+
+      def identifiers=(input)
+        @identifiers = Array.wrap(input)
+      end
+
+      def initialize_urlsafe_base64_encoded_identifiers!
+        @urlsafe_base64_encoded_identifiers = Base64.urlsafe_encode64(
+          identifiers.map { |identifier| Base64.urlsafe_decode64(identifier) }.join("\n")
+        )
+      end
+
+      def initialize_url_for_request!
+        @url_for_request = configuration.url_for_retrieving_agents_for(
+          urlsafe_base64_encoded_identifiers: urlsafe_base64_encoded_identifiers
+        )
+      end
+
+      def default_configuration
+        require 'cogitate'
+        Cogitate.configuration
+      end
+    end
+  end
+end

data/lib/cogitate/client/response_parsers.rb

@@ -0,0 +1,19 @@
+require 'cogitate/client/exceptions'
+
+module Cogitate
+  module Client
+    # Responsibl
+    module ResponseParsers
+      def self.fetch(name)
+        return name if name.respond_to?(:call)
+        const_get("#{name}Extractor")
+      rescue NameError
+        raise Client::ResponseParserNotFound.new(name, self)
+      end
+    end
+  end
+end
+
+Dir.glob(File.expand_path('../response_parsers/**/*', __FILE__)).each do |filename|
+  require filename
+end

data/lib/cogitate/client/response_parsers/agents_with_detailed_identifiers_extractor.rb

@@ -0,0 +1,15 @@
+require 'json'
+require 'cogitate/client/data_to_object_coercer'
+
+module Cogitate
+  module Client
+    module ResponseParsers
+      # Responsible for parsing a Cogitate response and just getting the basic data
+      module AgentsWithDetailedIdentifiersExtractor
+        def self.call(response:)
+          JSON.parse(response).fetch('data').map { |datum| DataToObjectCoercer.call(datum) }
+        end
+      end
+    end
+  end
+end

data/lib/cogitate/client/response_parsers/agents_without_group_membership_extractor.rb

@@ -0,0 +1,23 @@
+require 'json'
+require 'cogitate/client/data_to_object_coercer'
+require 'cogitate/models/identifier'
+
+module Cogitate
+  module Client
+    module ResponseParsers
+      # When you want an agent that omits identifiers associated with a group
+      module AgentsWithoutGroupMembershipExtractor
+        def self.call(response:)
+          identifier_guard = method(:identifier_is_not_a_group?)
+          JSON.parse(response).fetch('data').map { |datum| DataToObjectCoercer.call(datum, identifier_guard: identifier_guard) }
+        end
+
+        # @api private
+        # Perhaps a weird place to put this code, but it appears to work
+        def self.identifier_is_not_a_group?(identifier:)
+          identifier.strategy != Cogitate::Models::Identifier::GROUP_STRATEGY_NAME
+        end
+      end
+    end
+  end
+end

data/lib/cogitate/client/response_parsers/basic_extractor.rb

@@ -0,0 +1,14 @@
+require 'json'
+
+module Cogitate
+  module Client
+    module ResponseParsers
+      # Responsible for parsing a Cogitate response and just getting the basic data
+      module BasicExtractor
+        def self.call(response:)
+          JSON.parse(response).fetch('data')
+        end
+      end
+    end
+  end
+end

data/lib/cogitate/client/response_parsers/email_extractor.rb

@@ -0,0 +1,17 @@
+require 'json'
+module Cogitate
+  module Client
+    module ResponseParsers
+      # Responsible for parsing a Cogitate response with a focus on getting emails
+      module EmailExtractor
+        def self.call(response:)
+          data = JSON.parse(response).fetch('data')
+          data.each_with_object({}) do |datum, mem|
+            mem[datum.fetch('id')] = datum.fetch('attributes').fetch('emails')
+            mem
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cogitate/client/retrieve_agent_from_ticket.rb

@@ -0,0 +1,43 @@
+require 'cogitate/interfaces'
+require 'cogitate/models/agent/with_token'
+
+module Cogitate
+  module Client
+    # Responsible for converting a ticket into an agent
+    class RetrieveAgentFromTicket
+      # @api public
+      def self.call(ticket:, **keywords)
+        new(ticket: ticket, **keywords).call
+      end
+
+      def initialize(ticket:, ticket_coercer: default_ticket_coercer, token_coercer: default_token_coercer)
+        self.ticket = ticket
+        self.ticket_coercer = ticket_coercer
+        self.token_coercer = token_coercer
+      end
+
+      include Contracts
+      Contract(Contracts::None => Cogitate::Interfaces::AgentWithTokenInterface)
+      def call
+        token = ticket_coercer.call(ticket: ticket)
+        agent = token_coercer.call(token: token)
+        Cogitate::Models::Agent::WithToken.new(token: token, agent: agent)
+      end
+
+      private
+
+      attr_accessor :ticket, :ticket_coercer, :token_coercer
+
+      def default_ticket_coercer
+        # Responsible for issuing a request back to the Cogitate Server and reading the body
+        require 'cogitate/client/ticket_to_token_coercer' unless defined?(TicketToTokenCoercer)
+        TicketToTokenCoercer
+      end
+
+      def default_token_coercer
+        require 'cogitate/client/token_to_object_coercer' unless defined?(TokenToObjectCoercer)
+        TokenToObjectCoercer
+      end
+    end
+  end
+end

data/lib/cogitate/client/ticket_to_token_coercer.rb

@@ -0,0 +1,35 @@
+require 'rest-client'
+module Cogitate
+  module Client
+    # Responsible for converting a ticket into a token by leveraging a remote call to a Cogitate server.
+    class TicketToTokenCoercer
+      # @api public
+      # @param ticket [String] A ticket issued by a Cogitate server
+      # @return token [String] An encoded token
+      #
+      # @see Cogitate::Services::UriSafeTicketForIdentifierCreator
+      def self.call(ticket:, **keywords)
+        new(ticket: ticket, **keywords).call
+      end
+
+      def initialize(ticket:, configuration: default_configuration)
+        self.ticket = ticket
+        self.configuration = configuration
+      end
+
+      def call
+        response = RestClient.get(configuration.url_for_claiming_a_ticket, params: { ticket: ticket })
+        response.body
+      end
+
+      private
+
+      attr_accessor :ticket, :configuration
+
+      def default_configuration
+        require 'cogitate'
+        Cogitate.configuration
+      end
+    end
+  end
+end

data/lib/cogitate/client/token_to_object_coercer.rb

@@ -0,0 +1,38 @@
+module Cogitate
+  module Client
+    # Responsible for decoding a Cogitate token into an object (or objects)
+    #
+    # @see Cogitate::Services::Tokenizer for how the tokens get encoded and decoded
+    class TokenToObjectCoercer
+      # @api public
+      def self.call(token:, **keywords)
+        new(token: token, **keywords).call
+      end
+
+      def initialize(token:, token_to_data_coercer: default_token_to_data_coercer, data_to_object_coercer: default_data_to_object_coercer)
+        self.token = token
+        self.token_to_data_coercer = token_to_data_coercer
+        self.data_to_object_coercer = data_to_object_coercer
+      end
+
+      def call
+        data = token_to_data_coercer.call(token: token)
+        data_to_object_coercer.call(data)
+      end
+
+      private
+
+      attr_accessor :token, :token_to_data_coercer, :data_to_object_coercer
+
+      def default_token_to_data_coercer
+        require 'cogitate/services/tokenizer' unless defined?(Cogitate::Services::Tokenizer)
+        Cogitate::Services::Tokenizer.method(:from_token)
+      end
+
+      def default_data_to_object_coercer
+        require 'cogitate/client/data_to_object_coercer' unless defined?(Cogitate::Client::DataToObjectCoercer)
+        Cogitate::Client::DataToObjectCoercer
+      end
+    end
+  end
+end

data/lib/cogitate/configuration.rb

@@ -0,0 +1,99 @@
+module Cogitate
+  # Responsible for containing the configuration information for Cogitate
+  class Configuration
+    # If something is not properly configured
+    class ConfigurationError < RuntimeError
+      def initialize(method_name)
+        super("Cogitate::Configuration##{method_name} has not been set")
+      end
+    end
+
+    CONFIG_ATTRIBUTE_NAMES = [
+      # !@attribute [rw] after_authentication_callback_url
+      #   Where should the Cogitate server redirect to after a successful authentication?
+      #   @note Cogitate::Client configuration (and not Cogitate::Server)
+      :after_authentication_callback_url,
+      # !@attribute [rw] remote_server_base_url
+      # @note Cogitate::Client configuration
+      #   @return [String] What is the URL of the Cogitate server you want to connect to?
+      :remote_server_base_url,
+      # !@attribute [rw] tokenizer_password
+      #   What is the tokenizer password you are going to be using to:
+      #   * create a token (i.e. a private RSA key)
+      #   * decode a token (i.e. a public RSA key)
+      #
+      #   If you are implemnting a Cogitate client, you'll want to use the public key
+      #   @return [String]
+      #   @note Cogitate::Client and Cogitate::Server configuration
+      #   @see Cogitate::Services::Tokenizer
+      :tokenizer_password,
+      # !@attribute [rw] tokenizer_encryption_type
+      #   What is the encryption type for the tokenizer. You will need to ensure that
+      #   the Cogitate server and client are using the same encryption mechanism.
+      #   @return [String]
+      #   @note Cogitate::Client and Cogitate::Server configuration
+      #   @example `configuration.tokenizer_encryption_type = 'RS256'`
+      #   @see Cogitate::Services::Tokenizer
+      :tokenizer_encryption_type,
+      # !@attribute [rw] tokenizer_issuer_claim
+      #   As per JSON Web Token specification, what is the Issuer Claim
+      #   the Cogitate server and client are using the same encryption mechanism.
+      #
+      #   @note Cogitate::Client and Cogitate::Server configuration
+      #   @return [String]
+      #   @example `configuration.tokenizer_issuer_claim = 'https://library.nd.edu'`
+      #   @see https://tools.ietf.org/html/rfc7519#section-4.1.1
+      #   @see https://github.com/jwt/ruby-jwt#issuer-claim
+      :tokenizer_issuer_claim
+    ].freeze
+
+    def initialize(client_request_handler: default_client_request_handler, **keywords)
+      CONFIG_ATTRIBUTE_NAMES.each do |name|
+        send("#{name}=", keywords.fetch(name)) if keywords.key?(name)
+      end
+      self.client_request_handler = client_request_handler
+    end
+
+    CONFIG_ATTRIBUTE_NAMES.each do |method_name|
+      attr_writer method_name
+      define_method(method_name) do
+        instance_variable_get("@#{method_name}") || fail(ConfigurationError, method_name)
+      end
+    end
+
+    # What is the authentication URL of the client's configured Cogitate server
+    # @note Cogitate::Client configuration (and not Cogitate::Server)
+    # @return String
+    def url_for_authentication
+      query_params = "?after_authentication_callback_url=#{CGI.escape(after_authentication_callback_url)}"
+      File.join(remote_server_base_url, '/authenticate') << query_params
+    end
+
+    # What is the URL for claiming a ticket
+    # @note Cogitate::Client configuration (and not Cogitate::Server)
+    # @return String
+    def url_for_claiming_a_ticket
+      File.join(remote_server_base_url, '/claim')
+    end
+
+    # What is the URL for retrieving the agents based on the given identifiers
+    # @note Cogitate::Client configuration (and not Cogitate::Server)
+    # @param urlsafe_base64_encoded_identifiers [String]
+    # @return String
+    def url_for_retrieving_agents_for(urlsafe_base64_encoded_identifiers:)
+      File.join(remote_server_base_url, '/api/agents', urlsafe_base64_encoded_identifiers)
+    end
+
+    # What will be negotiating the remote request to the Cogitate::Server
+    #
+    # @return [#call(url:)]
+    # @see #default_client_request_handler for interface
+    attr_accessor :client_request_handler
+
+    private
+
+    def default_client_request_handler
+      -> (url:) { RestClient.get(url).body }
+    end
+  end
+end

data/lib/cogitate/exceptions.rb

@@ -0,0 +1,25 @@
+module Cogitate
+  # When the thing we are trying to decode is improperly encoded, this exception is to provide clarity
+  class InvalidIdentifierEncoding < ArgumentError
+    def initialize(encoded_string:)
+      super("Unable to decode #{encoded_string}; Expected it to be URL-safe Base64 encoded (use Base64.urlsafe_encode64)")
+    end
+  end
+
+  # When the thing we have decoded is not properly formated, this exception is to provide clarity
+  class InvalidIdentifierFormat < RuntimeError
+    EXPECTED_FORMAT = "strategy\tvalue\nstrategy\tvalue".freeze
+    def initialize(decoded_string:)
+      super("Expected #{decoded_string.inspect} to be of the format #{EXPECTED_FORMAT.inspect}")
+    end
+  end
+
+  # When the thing we have decoded is not properly formated, this exception is to provide clarity
+  class InvalidMembershipVisitationKeys < RuntimeError
+    def initialize(identifier:, visitation_type:)
+      super(
+        "Unable to find membership visitation service for visitation_type: #{visitation_type.inspect}, identifier: #{identifier.inspect}"
+      )
+    end
+  end
+end

data/lib/cogitate/generators/install_generator.rb

@@ -0,0 +1,10 @@
+module Commitment
+  # :nodoc:
+  class InstallGenerator < Rails::Generators::Base
+    source_root(File.expand_path("../templates", __FILE__))
+
+    def create_cogitate_initializer
+      template('cogitate_initializer.rb.erb', 'config/initializers/cogitate_initializer.rb')
+    end
+  end
+end

data/lib/cogitate/generators/templates/cogitate_initializer.rb.erb

@@ -0,0 +1,17 @@
+Cogitate.configure do |config|
+  <% if defined?(Figaro) %>
+  config.tokenizer_password = Figaro.env.cogitate_services_tokenizer_public_password!
+  config.remote_server_base_url = Figaro.env.cogitate_services_remote_server_base_url!
+  config.tokenizer_encryption_type = Figaro.env.cogitate_services_tokenizer_encryption_type!
+  config.tokenizer_issuer_claim = Figaro.env.cogitate_services_tokenizer_issuer_claim!
+  config.after_authentication_callback_url = Figaro.env.cogitate_services_after_authentication_callback_url!
+  <% else %>
+  # The public key for the RSA key
+  config.tokenizer_password = 'You need to provide this'
+  config.tokenizer_encryption_type = 'RS256'
+  config.tokenizer_issuer_claim = 'CHANGE THIS: Cogitate Client'
+  # Change this
+  config.remote_server_base_url = "http://localhost:3001"
+  config.after_authentication_callback_url = "http://localhost:3000/authenticate/from/cogitate"
+  <% end %>
+end

data/lib/cogitate/interfaces.rb

@@ -0,0 +1,40 @@
+require 'contracts'
+
+module Cogitate
+  # Herein lies the Cogitate namespace
+  module Interfaces
+    include Contracts
+    IdentifierInterface = RespondTo[:strategy, :identifying_value, :<=>, :name, :id, :encoded_id]
+    IdentifierCollectionInterface = Contracts::ArrayOf[Cogitate::Interfaces::IdentifierInterface]
+
+    AgentInterface = RespondTo[
+      :with_identifiers, :with_verified_identifiers, :with_emails, :add_identifier, :add_verified_identifier, :add_email, :ids, :name
+    ]
+    AgentCollectionInterface = Contracts::ArrayOf[Cogitate::Interfaces::AgentInterface]
+    AgentWithTokenInterface = And[AgentInterface, RespondTo[:to_token]]
+
+    VisitorInterface = RespondTo[:visit]
+    VisitorV2Interface = And[VisitorInterface, RespondTo[:return_from_visitations]]
+    AgentCollectorInitializationInterface = KeywordArgs[visitor: VisitorInterface, agent: Optional[AgentInterface]]
+
+    # All identifiers must be comparable, otherwise we could spiral into an endless visitation of related identifiers
+    VerifiedIdentifierInterface = IdentifierInterface
+
+    AuthenticationVectorNetidInterface = And[
+      RespondTo[:first_name, :last_name, :netid, :full_name, :ndguid, :strategy, :identifying_value],
+      IdentifierInterface
+    ]
+
+    HostInterface = RespondTo[:invite]
+
+    IdentifierInitializationInterface = KeywordArgs[strategy: RespondTo[:to_s], identifying_value: Any]
+    IdentifierBuilderInterface = Func[IdentifierInitializationInterface]
+
+    FindNetidRepositoryInterface = RespondTo[:find]
+
+    MembershipVisitationStrategyInterface = RespondTo[:call]
+
+    VerifiableIdentifierInterface = And[IdentifierInterface, RespondTo[:verified?]]
+    VerifiedGroupInterface = And[VerifiableIdentifierInterface, RespondTo[:name, :description]]
+  end
+end