setsuzoku 0.10.1

data/lib/setsuzoku/auth_strategy.rb

@@ -0,0 +1,72 @@
+# typed: false
+# frozen_string_literal: true
+
+module Setsuzoku
+  # The API Authentication Interface definition.
+  # Any AuthStrategy that implements this interface must implement all abstract methods defined by AuthStrategy.
+  #
+  # Defines all necessary methods for handling authentication for any authentication strategy.
+  module AuthStrategy
+
+    extend Forwardable
+    extend T::Sig
+    extend T::Helpers
+    abstract!
+
+    attr_accessor :service
+    attr_accessor :credential
+    def_delegators :@service, :plugin, :api_strategy, :external_api_handler
+
+    # Initialize the auth_strategy and provide reference to service.
+    #
+    # @param service [Service] the new instance of service with its correct strategies.
+    #
+    # @return [AuthStrategy] the new instance of auth_strategy
+    sig(:final) do
+      params(
+          service: T.any(
+              Setsuzoku::Service::WebService::Service,
+              T.untyped
+          ),
+          args: T.untyped
+      ).returns(T.any(
+          Setsuzoku::Service::WebService::AuthStrategies::BasicAuthStrategy,
+          Setsuzoku::Service::WebService::AuthStrategies::OAuthStrategy,
+          T.untyped
+      ))
+    end
+
+    def initialize(service:, **args)
+      self.service = service
+      credential = args[:credential]
+      self.credential = if self.plugin.registered_instance
+                          credential
+                        else
+                          self.class.credential_class.stub_credential
+                        end
+      self
+    end
+
+    # The getter method for a credential should retrieve dynamically if it's a proc.
+    # We cannot assign this at initialize time, as it may not yet exist on the instance.
+    #
+    # @return [Credential] the credential to use for the current requests.
+    def credential
+      self.plugin.get_registered_instance_val(@credential)
+    end
+
+    # Check if a credential is valid.
+    # Additionally it should revalidate if invalid.
+    #
+    # @return [Boolean] true if the credential is valid.
+    sig { abstract.returns(T::Boolean) }
+    def auth_credential_valid?; end
+
+    # Authorize a credential for a specific auth_strategy.
+    # It should also set the credential attributes and save if appropriate.
+    #
+    # @return [void]
+    sig { abstract.params(args: T.untyped).void }
+    def new_credential!(**args); end
+  end
+end

data/lib/setsuzoku/credential.rb

@@ -0,0 +1,37 @@
+
+# typed: ignore
+# frozen_string_literal: true
+
+module Setsuzoku
+  module Credential
+    extend T::Sig
+    extend T::Helpers
+    interface!
+
+    # Create a stub implementation of the credential for testing purposes
+    #
+    # @return [Struct] a struct that implements stubbed version of a credential's required methods.
+    sig { abstract.returns(Struct) }
+    def self.stub_credential; end
+
+    # A settings object for the credential.
+    #
+    # @return [Hash] the settings for the credential.
+    sig { abstract.returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+    def settings; end
+
+    # Setter for the settings object for the credential.
+    #
+    # @param val [Hash] a settings object to set.
+    #
+    # @return [Hash] the settings for the credential.
+    sig do
+      abstract
+          .params(val: T.nilable(T::Hash[T.untyped, T.untyped]))
+          .returns(T.nilable(T::Hash[T.untyped, T.untyped]))
+    end
+    def settings=(val); end
+  end
+end
+
+

data/lib/setsuzoku/exception.rb

@@ -0,0 +1,18 @@
+# typed: true
+
+module Setsuzoku
+  module Exception
+    class InvalidAuthCredentials < StandardError
+      def initialize(msg='The authentication credentials for this request are invalid.')
+        super(msg)
+      end
+    end
+
+    class UndefinedRequiredMethod < StandardError
+      def initialize(registering_instance:, plugin_class:, method_name:)
+        msg = "#{registering_instance.name} attempted to register #{plugin_class.name} but did not define the required instance method: #{method_name}"
+        super(msg)
+      end
+    end
+  end
+end

data/lib/setsuzoku/external_api_handler.rb

@@ -0,0 +1,19 @@
+# typed: true
+# frozen_string_literal: true
+
+module Setsuzoku
+  # The base definition for the exception handling class.
+  # This can be overridden by application configuration.
+  class ExternalApiHandler
+    def call_external_api_wrapper(**args)
+      puts('Setsuzoku API call pending')
+      response = yield
+      puts("Setsuzoku API call complete. Success status: #{response[:success]}")
+    end
+
+    def call_external_api_exception(**args)
+      puts(args[:exception].backtrace.join("\n")) if args[:exception]
+      puts("call_external_api failed with: #{args.inspect}")
+    end
+  end
+end

data/lib/setsuzoku/pluggable.rb

@@ -0,0 +1,87 @@
+# typed: false
+# frozen_string_literal: true
+
+module Setsuzoku
+  # The module to include into a class to give it plugin functionality.
+  module Pluggable
+    extend Forwardable
+    extend T::Sig
+    extend T::Helpers
+    abstract!
+
+    attr_accessor :plugin
+    def_delegators :@plugin, :plugin_service, :plugin_request_class
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+      klass.class_eval do
+        if klass.respond_to?(:after_initialize)
+          after_initialize :assign_plugin
+        else
+          # Initialize the pluggable instance and associate its plugin.
+          #
+          # @param _args [Array] array of args passed into new. #unused
+          # @param _block [Proc] the block passed into new. #unused
+          #
+          # @return [Class] the instance of the class that is pluggable.
+          def initialize(*_args, &_block)
+            super
+            self.assign_plugin
+            self
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+      extend T::Sig
+
+      def plugin_context
+        @plugin_context
+      end
+      def plugin_context=(val)
+        @plugin_context = val
+      end
+      def plugin_class
+        @plugin_class
+      end
+      def plugin_class=(val)
+        @plugin_class = val
+      end
+
+      def default_options
+        {
+            plugin_class: self
+        }
+      end
+
+      # Upon class load (or whenever you call this) register the core configuration
+      # for the pluggable class.
+      #
+      # param options [Any] a list of keyword options to be passed in to customize registration.
+      #
+      # @return [Void]
+      sig(:final) { params(options: T.untyped).void }
+      def register_plugin(**options)
+        options[:plugin_class].config_context[:required_instance_methods].each do |req_method|
+
+          unless options[:required_instance_methods].key?(req_method)
+            raise Setsuzoku::Exception::UndefinedRequiredMethod.new(registering_instance: self, plugin_class: options[:plugin_class], method_name: req_method)
+          end
+        end
+
+        self.plugin_context = self.default_options.merge(options)
+      end
+    end
+
+    def assign_plugin(*_args, &block)
+      self.plugin = self.class.plugin_context[:plugin_class].new(registering_instance: self, **self.class.plugin_context.except(:plugin_class))
+    end
+
+    # Define the Plugin that this class should use for its plugin interface.
+    #
+    # @return [Class] any class in Setsuzoku::Plugin
+    sig { abstract.returns(T.untyped) }
+    def plugin_class; end
+  end
+end

data/lib/setsuzoku/plugin.rb

@@ -0,0 +1,128 @@
+# typed: false
+# frozen_string_literal: true
+
+module Setsuzoku
+  # The base definition for a plugin.
+  # A plugin is a unification of an ApiStrategy and an AuthStrategy.
+  # It allows each Strategy to manage its various jobs of sending/receiving requests, and managing authentication/connections.
+  # However it acts as the director that allows these 2 to interact with one another.
+  module Plugin
+    autoload :Mobile, 'setsuzoku/plugin/mobile'
+
+    extend Forwardable
+    extend T::Sig
+    extend T::Helpers
+    abstract!
+
+    attr_accessor :name
+    attr_accessor :registered_instance
+    attr_accessor :service
+    attr_accessor :config_context
+    def_delegators :@service, :auth_strategy, :api_strategy, :exception_handler, :call_external_api, :request_class, :new_credential!
+
+    alias :plugin_service :service
+    alias :plugin_request_class :request_class
+
+    AVAILABLE_SERVICES = {
+        web_service: Setsuzoku::Service::WebService::Service
+    }
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def config_context
+        @config_context
+      end
+
+      def config_context=(val)
+        @config_context = val
+      end
+      # Register the service for a plugin.
+      # This will collect configuration level data to use when a plugin is registered.
+      # It will also impose interface requirements on the registering class.
+      #
+      # @param name [String] the name of the plugin.
+      # @param options [Any] list of keyword options to customize service registration.
+      #
+      # @return [void]
+      def register(name:, service:, **options)
+        context = {
+            name: name,
+            service: service
+        }
+
+        # @options are any additional options you want available inside the plugin
+
+        options.each do |key, val|
+          context[key] = val || self.with_options[key]
+        end
+
+        required_instance_methods = options[:required_instance_methods] || []
+        service[:strategies].each do |type, strategy|
+          type = type.to_s.split('_strategy').first.to_sym
+          strategy = strategy[:strategy]
+          strategy_klass = AVAILABLE_SERVICES[service[:type]].available_strategies[type][strategy]
+          required_instance_methods += strategy_klass.required_instance_methods
+          include strategy_klass.superclass::InterfaceMethods
+        end
+
+        context[:required_instance_methods] = required_instance_methods
+
+        self.config_context = context
+      end
+    end
+
+    # Initialize the plugin.
+    #
+    # @param registering_instance [Any] an instance of a class that needs to register with a plugin.
+    #
+    # @return the new registered instance of a plugin.
+    sig(:final) { params(options: T.untyped).returns(T.untyped) }
+    def initialize(**options)
+      context = self.class.config_context || { name: 'Default plugin', service: {} }
+      self.name = context[:name]
+      service_config = context[:service].except(:type).merge({ plugin: self, credential: options[:credential] })
+      self.registered_instance = options[:registering_instance]
+      if context[:service] && context[:service][:type]
+        service = AVAILABLE_SERVICES[context[:service][:type]]
+        self.service = service.new(service_config)
+      end
+      self.config_context = context.merge(options.except(:registering_instance))
+      self
+    end
+
+    # This method allows a safe way to access the registered_instance's methods or specify a static value
+    # This allows allows plugins to be tested in isolation, e.g. independent of a class that uses them.
+    #
+    # @param method_name [Symbol] the name of the method to try or to stub.
+    # @param args [Array] any additional args that need to be passed to the dynamic method.
+    #
+    # @return [Any] any value that the method could return.
+    sig(:final) { params(method_name: Symbol, args: T.untyped).returns(T.untyped) }
+    def get_from_registered_instance_method(method_name, *args)
+      if self.registered_instance
+        #either get the value if its defined generically in the
+        val = self.config_context[:required_instance_methods][method_name.to_sym]
+        self.get_registered_instance_val(val, *args)
+      else
+        #TODO: this needs to return any data type somehow...the plugin might need to stub this, as it stubs tests as well...
+        # this seems like a reasonable approach...
+        "stubbed_#{method_name}"
+      end
+    end
+
+    # Convenience method for performing instance_exec on the registered_instance.
+    # This is used for calling procs that are defined in the application's registration procs.
+    #
+    # @param val [Any] the value or a proc to instance_exec to get the value.
+    # @param args [Array] a list  of  args to be used for the proc.
+    #
+    # @return [Any] returns the value of the proc.
+    sig(:final) { params(val: T.untyped, args: T.untyped).returns(T.untyped) }
+    def get_registered_instance_val(val, *args)
+      val.is_a?(Proc) ? self.registered_instance.instance_exec(*args, &val) : val
+    end
+  end
+end

data/lib/setsuzoku/rspec.rb

@@ -0,0 +1,2 @@
+# typed: strict
+require 'setsuzoku/rspec/dynamic_spec_helper'

data/lib/setsuzoku/rspec/dynamic_spec_helper.rb

@@ -0,0 +1,281 @@
+# typed: false
+
+require 'active_support/core_ext/class/subclasses'
+require 'active_support/inflector/methods'
+module Setsuzoku
+  module DynamicSpecHelper
+
+    ### EXTERNAL PLUGIN SPEC HELPERS ###
+    #
+    # These specs are designed to test and ensure that a plugin's implementations uphold their contract.
+    # Additionally they ensure that a plugin's blackbox stubbing also upholds their  contract.
+    #
+    #
+    # This will register plugin specs for a base plugin class that defines its interfaces.
+    #
+    # It will register specs to ensure the base plugin's black box stubs are correct.
+    #
+    # It will also register specs for all implementations of the plugin to ensure the implementations are valid.
+    # (This is similar to register_plugin_tests_and_stubs)
+    def register_all_plugin_tests_and_stubs(plugin_class: self.described_class, subclasses_to_register: plugin_class.subclasses, registering_instance: nil, stub_directory: nil)
+      context "*Dynamic Specs* for #{plugin_class.name}: Stub Definitions" do
+        let(:plugin){ plugin_class.new }
+        plugin_class.spec_definitions.each do |action_name, spec|
+          define_stub_plugin_method(plugin_class, action_name, spec)
+          it(spec[:name], action_name: action_name, &spec[:spec])
+        end
+      end
+
+      perform_register(plugin_class, registering_instance: registering_instance, subclasses_to_register: subclasses_to_register, stub_directory: stub_directory)
+    end
+    #
+    # This will register plugin specs for a single plugin class.
+    # The specs will test the plugin to ensure its implementations are valid.
+    def register_plugin_tests_and_stubs(plugin_class, registering_instance: nil, stub_directory: nil)
+      perform_register(plugin_class, registering_instance: registering_instance, stub_directory: stub_directory)
+    end
+    #
+    ### END EXTERNAL PLUGIN SPEC HELPERS ###
+
+
+    ### APPLICATION SPEC HELPERS ###
+    #
+    # These stubs completely black box the plugin's functionality and returns a stubbed response
+    # without invoking the plugin's method.
+    #
+    # Stub all plugin interface methods at a context level for an application class that registers a plugin.
+    # This also defines a before each to execute the stubs.
+    #
+    # @param registering_class [Array/Class] the application's class/es that register a plugin and need methods stubbed.
+    #
+    # @return void
+    def stub_all_plugin_methods(registering_class = self.described_class)
+      registering_class = [registering_class] unless registering_class.is_a?(Array)
+      registering_class.each do |klass|
+        plugin_class = klass.plugin_context[:plugin_class]
+        plugin_class.spec_definitions.each do |action_name, spec|
+          define_stub_plugin_method(plugin_class, action_name, spec, true)
+        end
+      end
+    end
+    #
+    # Stub all plugin interface methods for an application class that registers a plugin for a single spec.
+    #
+    # @param registering_class [Array/Class] the application's class/es that register a plugin and need methods stubbed.
+    #
+    # @return void
+    def stub_plugin_methods_for_spec(registering_class = self.described_class)
+      plugin_class = registering_class.plugin_context[:plugin_class]
+      plugin_class.spec_definitions.each do |action_name, spec|
+        allow_any_instance_of(plugin_class).to receive(action_name).and_return(spec[:stub][:response])
+        # a plugin spec might have some dynamic data, e.g. certain methods are called with plugin specific args.
+        if spec[:stub][:dynamic_methods]
+          spec[:stub][:dynamic_methods].each do |meth, resp|
+            #how can we ignore the call count instead of just putting a high limit?
+            allow_any_instance_of(plugin_class).to receive(meth).and_return(resp)
+          end
+        end
+      end
+    end
+    #
+    ### END APPLICATION SPEC HELPERS ###
+
+    private
+
+    def perform_register(plugin_class, register_tests = true, registering_instance: nil, subclasses_to_register: nil, stub_directory: nil)
+      #iterate over all api methods defined by the plugin and create a context and tests for each method
+      # in register_tests_and_get_stubs, and return the stub defs up to this method.
+      plugin_classes = subclasses_to_register || [plugin_class]
+      plugin_classes.each do |plugin_class|
+        p = plugin_class.new(registering_instance: registering_instance)
+        register_tests_and_get_stubs(p, register_tests).each do |method_name, stubs|
+          register_stub(p, method_name, stubs, registering_instance: registering_instance, stub_directory: stub_directory)
+        end
+      end
+    end
+
+    # This will iterate over every registered plugin defined in the including helper
+    # and generate formatted hashes of stub configs.
+    #
+    # register_stubs uses these config objects to define stubs dynamically
+    def register_tests_and_get_stubs(plugin, register_tests = true)
+      definitions = {}
+      specs = []
+      action_name_namespace = :"#{plugin.name.gsub(' ', '').underscore}"
+      stub_name = :"stub_#{action_name_namespace}"
+      definitions[stub_name] = { action_name_namespace => {} }
+      plugin.api_actions.each do |api_action|
+        action_name, options = api_action
+        plugin.api_strategy.current_action = action_name
+        request_props = plugin.api_strategy.get_request_properties(action_name: action_name, for_stub: true)
+        (definitions[stub_name][action_name_namespace][action_name] ||= []) << {
+            method: request_props[:request_method],
+            request_format: request_props[:request_format],
+            response_format: request_props[:response_format],
+            url: request_props[:formatted_full_url],
+            stub_data: request_props[:stub_data]
+        }
+        # include the generic interface specs for this plugin's action
+        specs << { spec: plugin.class.spec_definitions[action_name], action_name: action_name }
+      end
+      if register_tests
+        context "*Dynamic Specs* for #{plugin.class.name}: Interface Implementations" do
+          #we will instantiate the plugin, any registered_instance dependent methods/data must be stubbed by the plugin because of this!
+          let!(:plugin) { plugin }
+
+          before :each do
+            send(stub_name, self)
+          end
+
+          specs.each do |spec_def|
+            if spec_def[:spec] && spec_def[:spec][:spec]
+              it(spec_def[:spec][:name], &spec_def[:spec][:spec])
+            else
+              it "Undefined spec for #{spec_def[:action_name]}" do
+                raise NotImplemented, "Spec for action: #{spec_def[:action_name]} is not defined. Expected #{plugin.class} or its parent to define it."
+              end
+            end
+          end
+        end
+      end
+
+      definitions
+    end
+
+    # This method will then iterate over stub defs and actually define the stubs here in the stub_defs array.
+    # It will then lastly collect all the stubs in stub_defs array and do call to define the stub.
+    def register_stub(plugin, method_name, stubs, registering_instance: nil, stub_directory: nil)
+      stub_defs = []
+      stubs.each do |provider, stub|
+        stub.each do |action_name, props|
+          props.each do |propz|
+            plugin.api_strategy.current_action = action_name
+            default_headers = plugin.api_strategy.request_options(propz[:request_format])[:headers] || { 'Authorization' => 'Bearer stubbed_token', 'Content-Type' => "application/#{propz[:request_format]}" }
+            if plugin.auth_strategy.is_a?(Setsuzoku::Service::WebService::AuthStrategies::BasicAuthStrategy)
+              basic_auth = plugin.api_strategy.request_options(propz[:request_format])[:basic_auth]
+              auth_header = { 'Authorization' => "Basic #{Base64.encode64("#{basic_auth[:username]}:#{basic_auth[:password]}").gsub("\n", '')}" }
+              default_headers.merge!(auth_header)
+            end
+            headers = propz[:headers] ? [propz[:headers]] : [default_headers]
+            stub_directory ||= "#{plugin.class.plugin_namespace}/#{provider}"
+            headers.each do |header|
+              header = {
+                  'Accept'=>'*/*',
+                  'Accept-Encoding'=>'gzip;q=1.0,deflate;q=0.6,identity;q=0.3',
+                  'User-Agent'=>'Ruby'
+              }.merge(header.deep_stringify_keys)
+
+              if propz[:stub_data]
+                # we have specified specific stub data for this action
+                propz[:stub_data].each do |stub_datum|
+                  url, body = get_url_and_body(plugin, propz, stub_directory, action_name, stub_datum[:url_params])
+
+                  stub_defs << proc do
+                    stub_request(propz[:method], url)
+                        .with(
+                            headers: header, body: body, query: stub_datum[:url_params]
+                        )
+                        .to_return(status: 200, headers: {}, body: File.read("#{Dir.pwd}/spec/support/setsuzoku/#{plugin.class.plugin_namespace}/#{provider}/#{action_name}.#{propz[:response_format]}"))
+                  end
+                end
+              else
+                # this is a generic action so the stub uses the default structure
+                url, body = get_url_and_body(plugin, propz, stub_directory, action_name)
+
+                stub_defs << proc do
+                  stub_request(propz[:method], url)
+                      .with(
+                          headers: header, body: body
+                      )
+                      .to_return(status: 200, headers: {}, body: File.read("#{Dir.pwd}/spec/support/setsuzoku/#{plugin.class.plugin_namespace}/#{provider}/#{action_name}.#{propz[:response_format]}"))
+                end
+              end
+            end
+          end
+        end
+      end
+
+      #iterate over all the stub_requests collected above and call them to stub them.
+      define_method method_name do |spec_instance = self|
+        stub_defs.each do |stub_def|
+          instance_exec(&stub_def)
+        end
+      end
+    end
+
+    def define_stub_plugin_method(plugin_class, action_name, spec, always_stub = false)
+      stub_plugin_method_name = :"stub_plugin_method_#{action_name}"
+      define_method stub_plugin_method_name do
+        #TODO: let this use the appropriate rspec instance stub method
+        #TODO: Does it make sense to have the stub with the method? or should it be in a json file we parse?
+        plugin_class.any_instance.should_receive(action_name).and_return(spec[:stub][:response])
+        # a plugin spec might have some dynamic data, e.g. certain methods are called with plugin specific args.
+        if spec[:stub][:dynamic_methods]
+          spec[:stub][:dynamic_methods].each do |meth, resp|
+            #how can we ignore the call count instead of just putting a high limit?
+            plugin_class.any_instance.should_receive(meth).and_return(resp)
+          end
+        end
+      end
+      if always_stub
+        before :each do
+          send(stub_plugin_method_name)
+        end
+      else
+        before :each, action_name: action_name do
+          send(stub_plugin_method_name)
+        end
+      end
+    end
+
+    def get_url_and_body(plugin, propz, stub_directory, action_name, url_params = nil)
+      body = nil
+      url = propz[:url]
+      format = propz[:request_format].to_s.include?('x-www-form') ? :json : propz[:request_format]
+      begin
+        body = File.read("#{Dir.pwd}/spec/support/setsuzoku/#{stub_directory}/#{action_name}_request.#{format}")
+        body.squish!
+        case format
+        when :xml
+          body.gsub!('> <', '><')
+        when :json
+          body.gsub!(' "', '"')
+          body.gsub!('" ', '"')
+          body.gsub!(': ', ':')
+          body.gsub!('{ ', '{')
+          body.gsub!(' }', '}')
+        end
+
+        # We will convert these to url params when making requests. need to replicate that.
+
+
+        req_params = case format
+                     when :json
+                       temp_body = JSON.parse(body)
+                       if url_params
+                         url_params.each{ |k,v| temp_body.delete(k.to_s) }
+                       end
+                       temp_body
+                     else
+                       # will we need to parse xml here?
+                       req_params = {}
+                       body
+                     end
+
+
+        if url.match?(/.*\{\{.*\}\}/)
+          url, body = plugin.api_strategy.replace_dynamic_vars(full_url: url, req_params: req_params)
+        end
+
+        case format
+        when :json
+          #faraday sorts hash keys for some reason
+          body = JSON.parse(body).sort.to_h
+        end
+        [url, body]
+      rescue
+        [url, nil]
+      end
+    end
+  end
+end